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: ```bash 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 `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 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) ```bash 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: ````bash 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 | | `blocked-by-sdk` | Fix requires changes in `@modelcontextprotocol/sdk` | | `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: ```bash 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) ```bash gh issue create -R cyanheads/mcp-ts-core --template "Feature Request" --web ``` ### CLI (non-interactive) The first three headings are the Feature Request form's own fields, in its order — `Use case` and `Proposed API` are required by the form, so a body without them does not satisfy it. Everything after `Alternatives considered` is supplemental; omit what you don't need — simple requests don't require Flow / Design / Dependencies blocks. ````bash gh issue create -R cyanheads/mcp-ts-core \ --title "feat(scope): concise description" \ --label "enhancement" \ --assignee "@me" \ --body "$(cat <<'ISSUE' ### Use case One or two sentences: who hits this gap in the framework and why it matters. Name the specific builder, utility, context method, or config field. Kept short on purpose — a field that invites a paragraph gets padded with background and skipped by the next reader. Related: #N ### Proposed API What you want the framework to do, then the API as a consumer would call it. Link external libraries on first mention: [lib name](https://github.com/owner/repo). ```ts import { withRetry } from '@cyanheads/mcp-ts-core/utils'; const result = await withRetry(() => fetchExternal(url), { maxAttempts: 3, backoff: 'exponential', }); ``` ### Alternatives considered What you tried or evaluated instead, and why it didn't fit. ### 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 ### 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 | ... | ... | ### Dependencies (optional) - Depends on: owner/repo#N ISSUE )" ```` ## Following Up ```bash # 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/`, `framework-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: `Use case` and `Proposed API` present (the form's required fields), `Alternatives considered` third; Out of scope defined