Report Issue Local

When to Use

The bug is in this server's code, not in @cyanheads/mcp-ts-core. Typical triggers:

• A tool handler returns wrong results or throws on valid input
• A service integration (external API, database, third-party SDK) fails or misbehaves
• Server-specific config (server-config.ts) rejects valid env vars or has wrong defaults
• Resource handlers return stale, incomplete, or incorrect data
• Domain logic errors — wrong calculations, missing edge cases, bad state transitions
• Missing or incorrect .describe() on schema fields causing poor LLM tool use

If the issue is in the framework itself (builders, Context, utilities, type exports, linter), use report-issue-framework instead.

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

Before Filing

1. Identify the repo:

gh repo view --json nameWithOwner -q '.nameWithOwner'

2. Search existing issues — if a close match exists (same symptom, different tool; same tool, different symptom; closed issue that might cover the new case), add a comment on that issue instead of filing a new one — unless the symptom or scope is distinct enough to warrant separate tracking:

gh issue list --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>              # body
gh issue view <number> --comments   # thread only — without a TTY it prints no body
gh api 'repos/{owner}/{repo}/issues/<number>/timeline' --paginate \
  --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'

3. Reproduce the issue — confirm it's reproducible. Note the exact input, transport mode, and any relevant env vars.

4. Check logs — review ctx.log output and any framework telemetry for clues. If running HTTP, check the response body for structured error details.

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, service, resource, or symptom. "Currently search_docs returns an empty array for queries containing &" beats "Search is broken." A reader should know what's wrong before the end of the first sentence.
• Embed library/service links on first mention. [Hono](https://hono.dev/), [Supabase](https://supabase.com/). 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/mcp-ts-core#46). Bare #N only works for same-repo issues — useful when the bug depends on or relates to a framework issue.
• 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, data sources, 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 an upstream framework change or 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

This repo includes YAML form issue templates (scaffolded from the framework). 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 --template "Bug Report" --web

CLI (non-interactive)

Structure the --body to match the template's form fields. Description is two or three sentences; the reproduction is the exact input and the observed output, nothing else. Add ### Additional context only when it changes the fix (a workaround, a related issue, the one log line that matters) — omitted by default.

gh issue create \
  --title "bug(tool_name): concise description" \
  --label "bug" \
  --assignee "@me" \
  --body "$(cat <<'ISSUE'
### Server version

<package.json version>

### mcp-ts-core version

<installed version from node_modules/@cyanheads/mcp-ts-core/package.json — not the ^ range>

### Runtime

Bun

### Runtime version

<bun --version>

### Transport

stdio

### Description

What happened and what you expected instead.

### Steps to reproduce

1. Call `tool_name` with input: `{ "key": "value" }`
2. Observe error / wrong output

### Actual behavior

```
Error or incorrect output here
```

### Expected behavior

What should have happened.
ISSUE
)"

Title conventions

Format: type(scope): description

• type: bug, feat, docs, chore
• scope: tool name, service name, resource name, config, auth, or domain area

Examples:

• bug(search_docs): returns empty results for queries with special characters
• feat(analytics): add date range filter to usage_report tool
• docs(setup): .env.example missing REDIS_URL