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.elicit, 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 --comments
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 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 scannable, concrete, and self-contained — terse and fact-dense. Default to one or two sentences per bullet; if a bullet runs long, split it or cut it. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).

• 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.
• Lead design sections with a philosophy sentence. Bold a short principle before the tradeoff details — e.g. "Philosophy: fail fast on config errors, degrade gracefully on runtime errors." Establishes the lens for the rest of the section.
• Prefer Markdown tables for comparisons. When showing options, tiers, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
• Separate ### Scope from ### Out of scope. The latter is as important as the former — it pre-empts scope-creep debates in comments and signals you've thought about the boundaries.
• Use Depends on: owner/repo#N to declare ordering explicitly when implementation is blocked on another issue landing first.
• Cut what dilutes the signal. Mechanism walkthroughs (link the PR or doc instead), ceremonial framings ("This issue covers…"), conversation references ("as discussed", "per offline"), and kitchen-sink Additional context blocks. If a paragraph isn't pulling weight, drop it.
• 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

CLI (non-interactive)

Structure the --body to match the template's form fields:

gh issue create -R cyanheads/mcp-ts-core \
  --title "bug(scope): concise description" \
  --label "bug" \
  --assignee "@me" \
  --body "$(cat <<'ISSUE'
### mcp-ts-core version

0.1.29

### Runtime

Bun

### Runtime version

Bun 1.3.x

### Transport

stdio

### OS

macOS 15.x

### Description

Brief explanation of the bug — what you expected vs what happened.

### Reproduction

```ts
import { tool, z } from '@cyanheads/mcp-ts-core';

export const broken = tool('broken_example', {
  description: 'Minimal repro.',
  input: z.object({ id: z.string().describe('ID') }),
  output: z.object({
    name: z.string().describe('Name'),
    extra: z.string().optional().describe('Optional field'),
  }),
  async handler(input, ctx) {
    return { name: 'test' }; // omitting optional field causes validation error
  },
});
```

### Actual behavior

```
Error: Output validation failed: ...
```

### Expected behavior

Omitting an optional output field should pass validation.

### Additional context

Any workarounds, related issues, or observations.
ISSUE
)"

Title conventions

Format: bug(<scope>): concise description

Scope	When
tool	Tool builder, handler, format, annotations
resource	Resource builder, handler, list, params
prompt	Prompt builder, generate, args
context	Context, logger, state, progress, elicit
config	AppConfig, parseConfig, env parsing
errors	McpError, error factories, typed contracts (errors[] / ctx.fail), conformance lint, httpErrorFromResponse, auto-classification
auth	Auth modes, scope checking, JWT/OAuth
storage	StorageService, providers
transport	stdio/http transport, SSE, session handling
worker	createWorkerHandler, Worker runtime
utils	Utilities (formatting, parsing, pagination, etc.)
linter	Definition linter false positives/negatives
types	Type exports, type inference
services	LLM, Speech, Graph services
deps	Dependency issues, peer dep conflicts

Labels

Every issue needs exactly one primary label. Stack secondary labels on top when applicable.

Primary (required — pick one):

Label	When
bug	Something broken
enhancement	Feature request or improvement
documentation	Documentation is wrong, missing, or misleading

Secondary (optional — stack on top of primary):

Label	When
regression	Worked before, broken after an update
performance	Memory, CPU, latency, or resource usage
security	Vulnerability, CVE, or hardening work
breaking-change	Fix/feature will break public API; requires a major bump
surplus-token-idea	Worth exploring when token budget allows

Combine labels: --label "bug" --label "regression".

Attaching logs or stack traces

For long output, write to a file and attach. Note: --body-file replaces the entire body — it does not supplement a --body flag. For structured bugs with logs, either embed the log content in the Additional context section of a normal --body, or file the issue first and add the log as a comment:

bun run rebuild && bun run start:stdio 2>&1 | head -100 > /tmp/mcp-error.log

# As part of a new issue (the log becomes the entire body — no template fields)
gh issue create -R cyanheads/mcp-ts-core \
  --title "bug(transport): stdio crashes on large payload" \
  --label "bug" \
  --assignee "@me" \
  --body-file /tmp/mcp-error.log

# Or as a comment on an existing issue
gh issue comment <number> -R cyanheads/mcp-ts-core --body-file /tmp/mcp-error.log

Filing a Feature Request

Browser (interactive)

gh issue create -R cyanheads/mcp-ts-core --template "Feature Request" --web

CLI (non-interactive)

Template below demonstrates the richer structure. Omit sections you don't need — simple requests don't require Flow / Design / Dependencies blocks.

gh issue create -R cyanheads/mcp-ts-core \
  --title "feat(scope): concise description" \
  --label "enhancement" \
  --assignee "@me" \
  --body "$(cat <<'ISSUE'
Concrete statement of what's currently missing or broken in the framework. Name the specific builder, utility, context method, or config field. Two or three sentences — the reader should know the gap before the end of the paragraph.

Related: #N

## Proposal

What you want the framework to do, in one paragraph. Link external libraries on first mention: [lib name](https://github.com/owner/repo). Include a short justification — what this gives us that we don't have today.

### Proposed API

```ts
import { withRetry } from '@cyanheads/mcp-ts-core/utils';

const result = await withRetry(() => fetchExternal(url), {
  maxAttempts: 3,
  backoff: 'exponential',
});
```

### Flow (optional)

Ordered steps — e.g. `trigger → resolve → fetch → degrade`. Useful when the change spans multiple phases or fallbacks.

### Design / Tradeoffs (optional)

Philosophy: **one-line principle in bold.**

| Option | Strengths | Weaknesses |
|:---|:---|:---|
| A | ... | ... |
| B | ... | ... |

### Scope

- Files or modules touched
- New exports, env vars, or config keys
- Tier (Tier 1 core / Tier 2 standard / Tier 3 optional peer dep)

### Out of scope

- What we're deliberately not doing
- Adjacent work that belongs in a separate issue

### Dependencies (optional)

- Depends on: owner/repo#N

### Alternatives considered

What you tried or evaluated instead, and why it didn't fit.
ISSUE
)"

Following Up

# Check issue status (with comment thread)
gh issue view <number> -R cyanheads/mcp-ts-core --comments

# Add context or respond to maintainer questions
gh issue comment <number> -R cyanheads/mcp-ts-core --body "Additional context..."

# List your open issues
gh issue list -R cyanheads/mcp-ts-core --author @me

Checklist

• Confirmed bug is in @cyanheads/mcp-ts-core, not server code
• Running latest (or documented) framework version
• Searched existing issues — no duplicate found
• If documentation or contract enhancement: confirmed src/, docs/, skills/, and public exports don't already cover the surface
• All secrets, credentials, and tokens redacted
• Primary label assigned (bug / enhancement / documentation)
• If bug: version, runtime, repro code, actual vs expected behavior included
• If feature: Proposal and Scope sections present; Out of scope defined