@cyanheads/mcp-ts-core 0.1.28 → 0.2.0

package/skills/report-issue-framework/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: report-issue-framework
+description: >
+  File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
+metadata:
+  author: cyanheads
+  version: "1.1"
+  audience: external
+  type: workflow
+---
+
+## 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
+
+## 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"
+```
+
+## Redact Before Posting
+
+GitHub issues are **public and permanent**. Before submitting any issue, scrub the title, body, logs, and code snippets for:
+
+- **Secrets** — API keys, tokens, passwords, `MCP_AUTH_SECRET_KEY`, `OPENROUTER_API_KEY`, JWT values
+- **Credentials** — auth headers (`Authorization: Bearer ...`), session IDs, cookie values
+- **PII** — names, emails, IP addresses, user IDs tied to real people
+- **Internal URLs** — private API endpoints, internal hostnames, database connection strings
+- **Env dumps** — `process.env` output, `.env` file contents, Cloudflare Worker bindings
+
+Replace sensitive values with obvious placeholders: `REDACTED`, `sk-...REDACTED`, `https://internal.example.com`, `user-id-123`. Do not rely on partial masking (`sk-abc...xyz`) — 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" \
+  --body "$(cat <<'ISSUE'
+### mcp-ts-core version
+
+0.1.29
+
+### Runtime
+
+Bun
+
+### Runtime version
+
+Bun 1.2.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, sample |
+| `config` | AppConfig, parseConfig, env parsing |
+| `errors` | McpError, error factories, 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
+
+| Label | When |
+|:------|:-----|
+| `bug` | Something broken |
+| `regression` | Worked before, broken after update |
+| `types` | TypeScript type issue |
+| `docs` | Documentation is wrong or misleading |
+| `enhancement` | Feature request or improvement (not a bug) |
+
+Combine labels: `--label "bug" --label "types"`.
+
+### Attaching logs or stack traces
+
+For long output, write to a file and attach:
+
+```bash
+bun run dev:stdio 2>&1 | head -100 > /tmp/mcp-error.log
+
+# As part of a new issue
+gh issue create -R cyanheads/mcp-ts-core \
+  --title "bug(transport): stdio crashes on large payload" \
+  --label "bug" \
+  --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)
+
+````bash
+gh issue create -R cyanheads/mcp-ts-core \
+  --title "feat(scope): concise description" \
+  --label "enhancement" \
+  --body "$(cat <<'ISSUE'
+### Use case
+
+Describe the problem you're solving and why the framework should handle it.
+
+### Proposed API
+
+```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 considered instead.
+ISSUE
+)"
+````
+
+## Following Up
+
+```bash
+# Check issue status
+gh issue view <number> -R cyanheads/mcp-ts-core
+
+# 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
+- [ ] All secrets, credentials, PII, and internal URLs redacted
+- [ ] Issue filed with: version, runtime, repro code, actual vs expected behavior

package/skills/report-issue-local/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: report-issue-local
+description: >
+  File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
+metadata:
+  author: cyanheads
+  version: "1.1"
+  audience: external
+  type: workflow
+---
+
+## 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.
+
+## Before Filing
+
+1. **Identify the repo**:
+
+```bash
+gh repo view --json nameWithOwner -q '.nameWithOwner'
+```
+
+2. **Search existing issues**:
+
+```bash
+gh issue list --search "your error message or keyword"
+```
+
+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.
+
+## Redact Before Posting
+
+GitHub issues are **public and permanent**. Before submitting any issue, scrub the title, body, logs, and code snippets for:
+
+- **Secrets** — API keys, tokens, passwords, env var values from `.env` or server config
+- **Credentials** — auth headers (`Authorization: Bearer ...`), session IDs, cookie values
+- **PII** — names, emails, IP addresses, user IDs tied to real people
+- **Internal URLs** — private API endpoints, internal hostnames, database connection strings
+- **Env dumps** — `process.env` output, `.env` file contents, Worker bindings
+
+Replace sensitive values with obvious placeholders: `REDACTED`, `sk-...REDACTED`, `https://internal.example.com`, `user-id-123`. Do not rely on partial masking (`sk-abc...xyz`) — 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)
+
+```bash
+gh issue create --template "Bug Report" --web
+```
+
+### CLI (non-interactive)
+
+Structure the `--body` to match the template's form fields:
+
+````bash
+gh issue create \
+  --title "bug(tool_name): concise description" \
+  --label "bug" \
+  --body "$(cat <<'ISSUE'
+### Server version
+
+0.1.0
+
+### mcp-ts-core version
+
+0.1.29
+
+### Runtime
+
+Bun
+
+### Runtime version
+
+Bun 1.2.x
+
+### 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.
+
+### Additional context
+
+Relevant `ctx.log` output, stack traces, or telemetry spans.
+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`
+
+### Labels
+
+| Label | When |
+|:------|:-----|
+| `bug` | Something broken |
+| `enhancement` | New feature or improvement |
+| `docs` | Documentation issue |
+| `config` | Configuration or environment issue |
+| `regression` | Worked before, broken after a change |
+
+Combine labels: `--label "bug" --label "regression"`.
+
+### Attaching logs or large output
+
+```bash
+bun run dev:stdio 2>&1 | head -200 > /tmp/server-error.log
+
+# As part of a new issue
+gh issue create \
+  --title "bug(ingest): crashes on large payload" \
+  --label "bug" \
+  --body-file /tmp/server-error.log
+
+# Or as a comment on an existing issue
+gh issue comment <number> --body-file /tmp/server-error.log
+```
+
+## Filing a Feature Request
+
+### Browser (interactive)
+
+```bash
+gh issue create --template "Feature Request" --web
+```
+
+### CLI (non-interactive)
+
+````bash
+gh issue create \
+  --title "feat(scope): concise description" \
+  --label "enhancement" \
+  --body "$(cat <<'ISSUE'
+### Use case
+
+What problem does this solve? Who benefits?
+
+### Proposed behavior
+
+Describe the expected behavior or API change.
+
+### Alternatives considered
+
+What you tried or considered instead.
+ISSUE
+)"
+````
+
+## Triage: Framework vs Server
+
+Not sure where the bug lives? Quick checks:
+
+| Signal | Likely framework | Likely server |
+|:-------|:-----------------|:--------------|
+| Error originates in `node_modules/@cyanheads/mcp-ts-core/` | Yes | |
+| Error in `src/mcp-server/tools/` or `src/services/` | | Yes |
+| Same bug reproduces with a bare `tool()` definition (no services) | Yes | |
+| Bug disappears when you swap in a dummy handler | | Yes |
+| `ctx.state`, `ctx.log`, `ctx.elicit` behave wrong on any tool | Yes | |
+| Only one specific tool/resource is affected | | Yes |
+
+When genuinely ambiguous, file against this server's repo and note that it might be a framework issue. The maintainer can transfer it upstream.
+
+## Following Up
+
+```bash
+# View issue details
+gh issue view <number>
+
+# Add context
+gh issue comment <number> --body "Additional findings..."
+
+# List your open issues
+gh issue list --author @me
+
+# Close if resolved
+gh issue close <number> --reason completed --comment "Fixed in <commit or PR>"
+```
+
+## Checklist
+
+- [ ] Confirmed bug is in server code, not the framework
+- [ ] Searched existing issues — no duplicate found
+- [ ] All secrets, credentials, PII, and internal URLs redacted
+- [ ] Issue filed with: version, runtime, repro steps, actual vs expected behavior

package/skills/setup/SKILL.md

@@ -35,6 +35,7 @@ What `init` actually creates:
 ```text
 CLAUDE.md                                       # Agent protocol (project-specific)
 AGENTS.md                                       # Same content — discard whichever you don't use
+.github/ISSUE_TEMPLATE/                         # GitHub issue templates (bug report, feature request)
 skills/                                         # Project skills (source of truth)
 src/
   index.ts                                      # createApp() entry point

package/templates/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,106 @@
+name: Bug Report
+description: Report a bug in {{PACKAGE_NAME}}
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Do not include secrets, credentials, API keys, tokens, PII, or other sensitive data.** Redact env vars, auth headers, user-identifying information, and internal URLs from all code snippets, logs, and stack traces before submitting. GitHub issues are public and permanent.
+
+  - type: input
+    id: version
+    attributes:
+      label: Server version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: framework-version
+    attributes:
+      label: mcp-ts-core version
+      placeholder: "0.1.29"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: runtime
+    attributes:
+      label: Runtime
+      options:
+        - Bun
+        - Node.js
+        - Cloudflare Workers
+    validations:
+      required: true
+
+  - type: input
+    id: runtime-version
+    attributes:
+      label: Runtime version
+      placeholder: "Bun 1.2.x / Node 22.x"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: transport
+    attributes:
+      label: Transport
+      options:
+        - stdio
+        - HTTP (Streamable HTTP)
+        - Worker (Cloudflare)
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: "macOS 15.x / Ubuntu 24.04 / etc."
+    validations:
+      required: false
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened and what you expected instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Exact inputs, tool calls, or sequence of actions to trigger the bug.
+      placeholder: |
+        1. Call `tool_name` with input: `{ "key": "value" }`
+        2. Observe error / wrong output
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Error messages, stack traces, or incorrect output.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened.
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Workarounds, related issues, logs, or anything else relevant.
+    validations:
+      required: false

package/templates/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/templates/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature Request
+description: Suggest a new feature or improvement for {{PACKAGE_NAME}}
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use case
+      description: What problem does this solve? Who benefits?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-behavior
+    attributes:
+      label: Proposed behavior
+      description: Describe the expected behavior or API change. Include example code if possible.
+      render: typescript
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What you tried or considered instead, and why it fell short.
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Related issues, prior art, links, or anything else relevant.
+    validations:
+      required: false

package/templates/CLAUDE.md

@@ -227,6 +227,8 @@ Available skills:
 | `devcheck` | Lint, format, typecheck, audit |
 | `polish-docs-meta` | Finalize docs, README, metadata, and agent protocol for shipping |
 | `maintenance` | Sync skills and dependencies after updates |
+| `report-issue-framework` | File a bug or feature request against `@cyanheads/mcp-ts-core` via `gh` CLI |
+| `report-issue-local` | File a bug or feature request against this server's own repo via `gh` CLI |
 | `api-auth` | Auth modes, scopes, JWT/OAuth |
 | `api-config` | AppConfig, parseConfig, env vars |
 | `api-context` | Context interface, logger, state, progress |