Report Issue Framework

When to Use

You've isolated a problem to @cyanheads/mcp-ts-core itself — not your server code, not a misconfiguration, not a missing peer dependency. Typical triggers:

• Framework builder (tool(), resource(), prompt()) rejects valid input or produces incorrect output
• createApp() or createWorkerHandler() fails on a valid config
• Context properties (ctx.log, ctx.state, ctx.inputs, etc.) behave contrary to docs
• A utility from /utils, /errors, /auth, /storage, /services returns wrong results or throws unexpectedly
• Type exports are incorrect or missing (compile error on documented usage)
• The definition linter (bun run lint:mcp) produces false positives or misses real violations

For general gh CLI workflows outside issue filing (PRs, workflows, API access), see the github-cli skill.

Before Filing

1. Confirm framework version — bun pm ls @cyanheads/mcp-ts-core or check node_modules/@cyanheads/mcp-ts-core/package.json
2. Check you're on latest — bun outdated @cyanheads/mcp-ts-core. If behind, update and retest before filing.
3. Isolate the issue — reproduce with a minimal handler or standalone script. Strip server-specific services, config, and dependencies. If the bug disappears when isolated, it's likely in your server code.
4. Search existing issues — don't file duplicates:

gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword" --state all

# Assess a close match before commenting — is it already linked to a fix or referenced elsewhere?
gh issue view <number> -R cyanheads/mcp-ts-core              # body
gh issue view <number> -R cyanheads/mcp-ts-core --comments   # thread only — without a TTY it prints no body
gh api 'repos/cyanheads/mcp-ts-core/issues/<number>/timeline' --paginate \
  --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'

5. For documentation- or contract-shaped requests, audit all three doc layers first — proposals to add reference docs, public-API conventions, attribute/event catalogs, or stability commitments often duplicate surface that already exists. Check src/ for behavior, docs/ for human-facing reference, and framework-skills/ for agent-facing reference. Skill files marked audience: external are the framework's public contract — treat them as authoritative when evaluating whether a documentation gap exists. Also verify the constants or types you'd reference aren't already exported from @cyanheads/mcp-ts-core or one of its subpaths.

Writing Well-Structured Issues

Good issues are terse and fact-dense. Budget: a bug reads in ~150 words, a feature in ~250, code and logs excluded. Every section past the form's required fields must earn its place — a section you could delete without changing the fix is noise. One or two sentences per bullet; if a bullet runs long, split it or cut it.

• Cut what dilutes the signal. Mechanism walkthroughs (link the PR or doc instead), ceremonial framings ("This issue covers…"), conversation references ("as discussed", "per offline"), restated context the reader already has, and kitchen-sink Additional context blocks. If a paragraph isn't pulling weight, drop it.
• Lead with specifics. Name the tool, function, module, or symptom. "Currently createApp() throws ConfigurationError when MCP_HTTP_PORT is set to 0" beats "There's a problem with the config." A reader should know what's broken or missing before the end of the first sentence.
• Embed library/service links on first mention. [Hono](https://hono.dev/), [linkedom](https://github.com/WebReflection/linkedom). Link to the canonical repo or homepage so readers can verify the dependency and reach docs in one click.
• Use owner/repo#N for cross-repo issue references. GitHub auto-renders them as linked references (e.g. cyanheads/pubmed-mcp-server#34). Bare #N only works for same-repo issues.
• Add a Related: #N line near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
• Cite cross-references once per body. Link an issue/PR in Related:, the description, or Additional context — not all three. The reader sees them all; redundant linking dilutes signal.
• Prefer Markdown tables for comparisons. When showing options, tiers, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
• Use Depends on: owner/repo#N to declare ordering explicitly when implementation is blocked on another issue landing first.
• Skip collaborator-framing sign-offs. Lines like "Happy to open a PR", "let me know if you'd like", "willing to contribute", "if that's the preferred flow" read as noise. A PR link beats an offer; if you're the maintainer filing against your own repo, the offer is redundant. End the body at the last substantive point.

Redact Before Posting

GitHub issues are public. Do not include secrets, credentials, API keys, or tokens. Redact sensitive values from env vars, headers, and logs before submitting. Replace with obvious placeholders: REDACTED, sk-...REDACTED. Do not rely on partial masking — partial keys can still be exploited.

Filing a Bug

The repo has YAML form issue templates. Use --web to open the form in the browser (preferred when available), or pass --title + --body for non-interactive use.

Browser (interactive)

gh issue create -R cyanheads/mcp-ts-core --template "Bug Report" --web