@cyanheads/mcp-ts-core 0.6.11 → 0.6.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +1 -1
- package/README.md +1 -1
- package/changelog/0.6.x/0.6.12.md +15 -0
- package/dist/logs/combined.log +4 -4
- package/dist/logs/error.log +4 -4
- package/package.json +1 -1
- package/skills/report-issue-framework/SKILL.md +54 -4
- package/skills/report-issue-local/SKILL.md +60 -5
package/CLAUDE.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Agent Protocol
|
|
2
2
|
|
|
3
|
-
**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.6.
|
|
3
|
+
**Package:** `@cyanheads/mcp-ts-core` · **Version:** 0.6.12
|
|
4
4
|
**npm:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) · **Docker:** [ghcr.io/cyanheads/mcp-ts-core](https://ghcr.io/cyanheads/mcp-ts-core)
|
|
5
5
|
|
|
6
6
|
> **Developer note:** Never assume. Read related files and docs before making changes. Read full file content for context. Never edit a file before reading it.
|
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
<div align="center">
|
|
7
7
|
|
|
8
|
-
[](./CHANGELOG.md) [](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [](https://modelcontextprotocol.io/) [](./LICENSE)
|
|
9
9
|
|
|
10
10
|
[](https://www.typescriptlang.org/) [](https://bun.sh/)
|
|
11
11
|
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
summary: Enrich report-issue-framework and report-issue-local skills with Writing Well-Structured Issues guidance and an expanded feature-request template
|
|
3
|
+
breaking: false
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 0.6.12 — 2026-04-23
|
|
7
|
+
|
|
8
|
+
Thickens the two issue-filing skills so feature requests land as scannable, self-contained proposals instead of abstract "wouldn't it be nice" framings. No code changes.
|
|
9
|
+
|
|
10
|
+
## Changed
|
|
11
|
+
|
|
12
|
+
- **`skills/report-issue-framework/SKILL.md`** bumped to v1.2. Adds a **Writing Well-Structured Issues** section with nine bullets covering concrete openings, inline library links, `owner/repo#N` cross-repo refs, `Related: #N` provenance, philosophy-before-tradeoff framing, Markdown tables for comparisons, explicit `Scope` vs `Out of scope`, `Depends on:` ordering, and a generalized "skip collaborator-framing sign-offs" rule that works for both maintainer and external-contributor contexts. Expands the feature-request CLI template from three fields to a richer structure: concrete opening paragraph → `Related:` → `## Proposal` → `### Proposed API` → optional `Flow` (with a `trigger → resolve → fetch → degrade` hint) → optional `Design / Tradeoffs` (philosophy line + tradeoff table) → `Scope` → `Out of scope` → optional `Dependencies` → `Alternatives considered`. Adds a one-line cross-link to the `github-cli` skill for general `gh` workflows outside issue filing.
|
|
13
|
+
- **`skills/report-issue-local/SKILL.md`** bumped to v1.2 with the same treatment, adapted for server context — `### Proposed behavior` instead of `### Proposed API`, examples scoped to tools/services/resources, and a `Dependencies` section that hints at cross-repo refs to upstream framework issues.
|
|
14
|
+
|
|
15
|
+
Resolves [#48](https://github.com/cyanheads/mcp-ts-core/issues/48).
|
package/dist/logs/combined.log
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
{"level":50,"time":
|
|
2
|
-
{"level":50,"time":
|
|
3
|
-
{"level":50,"time":
|
|
4
|
-
{"level":50,"time":
|
|
1
|
+
{"level":50,"time":1776966178178,"env":"testing","version":"0.0.0-test","pid":78759,"requestId":"44GLL-MUSY2","timestamp":"2026-04-23T17:42:58.177Z","operation":"HandleToolRequest","input":{"message":"blocked"},"critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"c554df94160cff7175e42850d8f0f46eefbfcfdb4190cf2f23abdb6a21e0962d","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant"},"errorData":{"sessionId":"c554df94160cff7175e42850d8f0f46eefbfcfdb4190cf2f23abdb6a21e0962d","toolName":"scoped_echo","input":{"message":"blocked"},"requestId":"44GLL-MUSY2","timestamp":"2026-04-23T17:42:58.177Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:61:15)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:68:17)\n at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:168:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:101:42)\n at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}
|
|
2
|
+
{"level":50,"time":1776966179159,"env":"testing","version":"0.6.12","pid":78798,"requestId":"JM7M8-2BAH5","timestamp":"2026-04-23T17:42:59.158Z","operation":"httpErrorHandler","critical":false,"errorCode":-32006,"originalErrorType":"McpError","finalErrorType":"McpError","path":"/mcp","method":"POST","errorData":{"path":"/mcp","method":"POST","requestId":"JM7M8-2BAH5","timestamp":"2026-04-23T17:42:59.158Z","operation":"httpErrorHandler","originalErrorName":"McpError","originalMessage":"Missing or invalid Authorization header. Bearer scheme required.","originalStack":"McpError: Missing or invalid Authorization header. Bearer scheme required.\n at unauthorized (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:86:61)\n at authMiddleware (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/authMiddleware.js:64:19)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpTransport.js:119:22)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at cors2 (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/middleware/cors/index.js:82:11)\n at processTicksAndRejections (native:7:39)"},"stack":"McpError: Missing or invalid Authorization header. Bearer scheme required.\n at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:168:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpErrorHandler.js:59:39)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:26:25)\n at processTicksAndRejections (native:7:39)","msg":"Error in httpTransport: Missing or invalid Authorization header. Bearer scheme required."}
|
|
3
|
+
{"level":50,"time":1776966179173,"env":"testing","version":"0.6.12","pid":78798,"requestId":"OIV34-PX46Q","timestamp":"2026-04-23T17:42:59.173Z","operation":"httpErrorHandler","critical":false,"errorCode":-32006,"originalErrorType":"McpError","finalErrorType":"McpError","path":"/mcp","method":"POST","errorData":{"path":"/mcp","method":"POST","requestId":"OIV34-PX46Q","timestamp":"2026-04-23T17:42:59.173Z","operation":"httpErrorHandler","originalErrorName":"McpError","originalMessage":"Token has expired.","originalStack":"McpError: Token has expired.\n at unauthorized (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:86:61)\n at handleJoseVerifyError (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/claimParser.js:56:11)\n at verify (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/strategies/jwtStrategy.js:91:13)\n at processTicksAndRejections (native:7:39)"},"stack":"McpError: Token has expired.\n at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:168:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpErrorHandler.js:59:39)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:26:25)\n at processTicksAndRejections (native:7:39)","msg":"Error in httpTransport: Token has expired."}
|
|
4
|
+
{"level":50,"time":1776966179179,"env":"testing","version":"0.6.12","pid":78798,"requestId":"LRG26-T34QU","timestamp":"2026-04-23T17:42:59.179Z","operation":"httpErrorHandler","critical":false,"errorCode":-32006,"originalErrorType":"McpError","finalErrorType":"McpError","path":"/mcp","method":"GET","errorData":{"path":"/mcp","method":"GET","requestId":"LRG26-T34QU","timestamp":"2026-04-23T17:42:59.179Z","operation":"httpErrorHandler","originalErrorName":"McpError","originalMessage":"Missing or invalid Authorization header. Bearer scheme required.","originalStack":"McpError: Missing or invalid Authorization header. Bearer scheme required.\n at unauthorized (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:86:61)\n at authMiddleware (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/authMiddleware.js:64:19)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpTransport.js:119:22)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at cors2 (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/middleware/cors/index.js:82:11)\n at processTicksAndRejections (native:7:39)"},"stack":"McpError: Missing or invalid Authorization header. Bearer scheme required.\n at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:168:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpErrorHandler.js:59:39)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:26:25)\n at processTicksAndRejections (native:7:39)","msg":"Error in httpTransport: Missing or invalid Authorization header. Bearer scheme required."}
|
package/dist/logs/error.log
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
{"level":50,"time":
|
|
2
|
-
{"level":50,"time":
|
|
3
|
-
{"level":50,"time":
|
|
4
|
-
{"level":50,"time":
|
|
1
|
+
{"level":50,"time":1776966178178,"env":"testing","version":"0.0.0-test","pid":78759,"requestId":"44GLL-MUSY2","timestamp":"2026-04-23T17:42:58.177Z","operation":"HandleToolRequest","input":{"message":"blocked"},"critical":false,"errorCode":-32005,"originalErrorType":"McpError","finalErrorType":"McpError","sessionId":"c554df94160cff7175e42850d8f0f46eefbfcfdb4190cf2f23abdb6a21e0962d","toolName":"scoped_echo","tenantId":"authz-tenant","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant"},"errorData":{"sessionId":"c554df94160cff7175e42850d8f0f46eefbfcfdb4190cf2f23abdb6a21e0962d","toolName":"scoped_echo","input":{"message":"blocked"},"requestId":"44GLL-MUSY2","timestamp":"2026-04-23T17:42:58.177Z","tenantId":"authz-tenant","operation":"HandleToolRequest","auth":{"sub":"authz-user","scopes":["tool:other:read"],"clientId":"authz-client","tenantId":"authz-tenant"},"originalErrorName":"McpError","originalMessage":"Insufficient permissions.","originalStack":"McpError: Insufficient permissions.\n at forbidden (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:84:58)\n at withRequiredScopes (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/authUtils.js:61:15)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:68:17)\n at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n at processTicksAndRejections (native:7:39)"},"stack":"McpError: Insufficient permissions.\n at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:168:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/tools/utils/toolHandlerFactory.js:101:42)\n at executeToolHandler (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:231:34)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js:126:43)\n at processTicksAndRejections (native:7:39)","msg":"Error in tool:scoped_echo: Insufficient permissions."}
|
|
2
|
+
{"level":50,"time":1776966179159,"env":"testing","version":"0.6.12","pid":78798,"requestId":"JM7M8-2BAH5","timestamp":"2026-04-23T17:42:59.158Z","operation":"httpErrorHandler","critical":false,"errorCode":-32006,"originalErrorType":"McpError","finalErrorType":"McpError","path":"/mcp","method":"POST","errorData":{"path":"/mcp","method":"POST","requestId":"JM7M8-2BAH5","timestamp":"2026-04-23T17:42:59.158Z","operation":"httpErrorHandler","originalErrorName":"McpError","originalMessage":"Missing or invalid Authorization header. Bearer scheme required.","originalStack":"McpError: Missing or invalid Authorization header. Bearer scheme required.\n at unauthorized (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:86:61)\n at authMiddleware (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/authMiddleware.js:64:19)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpTransport.js:119:22)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at cors2 (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/middleware/cors/index.js:82:11)\n at processTicksAndRejections (native:7:39)"},"stack":"McpError: Missing or invalid Authorization header. Bearer scheme required.\n at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:168:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpErrorHandler.js:59:39)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:26:25)\n at processTicksAndRejections (native:7:39)","msg":"Error in httpTransport: Missing or invalid Authorization header. Bearer scheme required."}
|
|
3
|
+
{"level":50,"time":1776966179173,"env":"testing","version":"0.6.12","pid":78798,"requestId":"OIV34-PX46Q","timestamp":"2026-04-23T17:42:59.173Z","operation":"httpErrorHandler","critical":false,"errorCode":-32006,"originalErrorType":"McpError","finalErrorType":"McpError","path":"/mcp","method":"POST","errorData":{"path":"/mcp","method":"POST","requestId":"OIV34-PX46Q","timestamp":"2026-04-23T17:42:59.173Z","operation":"httpErrorHandler","originalErrorName":"McpError","originalMessage":"Token has expired.","originalStack":"McpError: Token has expired.\n at unauthorized (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:86:61)\n at handleJoseVerifyError (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/lib/claimParser.js:56:11)\n at verify (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/strategies/jwtStrategy.js:91:13)\n at processTicksAndRejections (native:7:39)"},"stack":"McpError: Token has expired.\n at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:168:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpErrorHandler.js:59:39)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:26:25)\n at processTicksAndRejections (native:7:39)","msg":"Error in httpTransport: Token has expired."}
|
|
4
|
+
{"level":50,"time":1776966179179,"env":"testing","version":"0.6.12","pid":78798,"requestId":"LRG26-T34QU","timestamp":"2026-04-23T17:42:59.179Z","operation":"httpErrorHandler","critical":false,"errorCode":-32006,"originalErrorType":"McpError","finalErrorType":"McpError","path":"/mcp","method":"GET","errorData":{"path":"/mcp","method":"GET","requestId":"LRG26-T34QU","timestamp":"2026-04-23T17:42:59.179Z","operation":"httpErrorHandler","originalErrorName":"McpError","originalMessage":"Missing or invalid Authorization header. Bearer scheme required.","originalStack":"McpError: Missing or invalid Authorization header. Bearer scheme required.\n at unauthorized (/Users/casey/Developer/github/mcp-ts-core/dist/types-global/errors.js:86:61)\n at authMiddleware (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/auth/authMiddleware.js:64:19)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpTransport.js:119:22)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:22:23)\n at cors2 (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/middleware/cors/index.js:82:11)\n at processTicksAndRejections (native:7:39)"},"stack":"McpError: Missing or invalid Authorization header. Bearer scheme required.\n at handleError (/Users/casey/Developer/github/mcp-ts-core/dist/utils/internal/error-handler/errorHandler.js:168:23)\n at <anonymous> (/Users/casey/Developer/github/mcp-ts-core/dist/mcp-server/transports/http/httpErrorHandler.js:59:39)\n at dispatch (/Users/casey/Developer/github/mcp-ts-core/node_modules/hono/dist/compose.js:26:25)\n at processTicksAndRejections (native:7:39)","msg":"Error in httpTransport: Missing or invalid Authorization header. Bearer scheme required."}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cyanheads/mcp-ts-core",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.12",
|
|
4
4
|
"mcpName": "io.github.cyanheads/mcp-ts-core",
|
|
5
5
|
"description": "Agent-native TypeScript framework for building MCP servers. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.",
|
|
6
6
|
"main": "dist/core/index.js",
|
|
@@ -4,7 +4,7 @@ description: >
|
|
|
4
4
|
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.
|
|
5
5
|
metadata:
|
|
6
6
|
author: cyanheads
|
|
7
|
-
version: "1.
|
|
7
|
+
version: "1.2"
|
|
8
8
|
audience: external
|
|
9
9
|
type: workflow
|
|
10
10
|
---
|
|
@@ -20,6 +20,8 @@ You've isolated a problem to `@cyanheads/mcp-ts-core` itself — not your server
|
|
|
20
20
|
- Type exports are incorrect or missing (compile error on documented usage)
|
|
21
21
|
- The definition linter (`bun run lint:mcp`) produces false positives or misses real violations
|
|
22
22
|
|
|
23
|
+
For general `gh` CLI workflows outside issue filing (PRs, workflows, API access), see the `github-cli` skill.
|
|
24
|
+
|
|
23
25
|
## Before Filing
|
|
24
26
|
|
|
25
27
|
1. **Confirm framework version** — `bun pm ls @cyanheads/mcp-ts-core` or check `node_modules/@cyanheads/mcp-ts-core/package.json`
|
|
@@ -31,6 +33,20 @@ You've isolated a problem to `@cyanheads/mcp-ts-core` itself — not your server
|
|
|
31
33
|
gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword"
|
|
32
34
|
```
|
|
33
35
|
|
|
36
|
+
## Writing Well-Structured Issues
|
|
37
|
+
|
|
38
|
+
Good issues are scannable, concrete, and self-contained. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
|
|
39
|
+
|
|
40
|
+
- **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.
|
|
41
|
+
- **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.
|
|
42
|
+
- **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.
|
|
43
|
+
- **Add a `Related: #N` line** near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
|
|
44
|
+
- **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.
|
|
45
|
+
- **Prefer Markdown tables for comparisons.** When showing options, tiers, strategies, or tradeoffs — tables are the highest-density format for scanning N rows × M attributes.
|
|
46
|
+
- **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.
|
|
47
|
+
- **Use `Depends on: owner/repo#N`** to declare ordering explicitly when implementation is blocked on another issue landing first.
|
|
48
|
+
- **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.
|
|
49
|
+
|
|
34
50
|
## Redact Before Posting
|
|
35
51
|
|
|
36
52
|
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.
|
|
@@ -174,14 +190,20 @@ gh issue create -R cyanheads/mcp-ts-core --template "Feature Request" --web
|
|
|
174
190
|
|
|
175
191
|
### CLI (non-interactive)
|
|
176
192
|
|
|
193
|
+
Template below demonstrates the richer structure. Omit sections you don't need — simple requests don't require Flow / Design / Dependencies blocks.
|
|
194
|
+
|
|
177
195
|
````bash
|
|
178
196
|
gh issue create -R cyanheads/mcp-ts-core \
|
|
179
197
|
--title "feat(scope): concise description" \
|
|
180
198
|
--label "enhancement" \
|
|
181
199
|
--body "$(cat <<'ISSUE'
|
|
182
|
-
|
|
200
|
+
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.
|
|
183
201
|
|
|
184
|
-
|
|
202
|
+
Related: #N
|
|
203
|
+
|
|
204
|
+
## Proposal
|
|
205
|
+
|
|
206
|
+
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.
|
|
185
207
|
|
|
186
208
|
### Proposed API
|
|
187
209
|
|
|
@@ -194,9 +216,37 @@ const result = await withRetry(() => fetchExternal(url), {
|
|
|
194
216
|
});
|
|
195
217
|
```
|
|
196
218
|
|
|
219
|
+
### Flow (optional)
|
|
220
|
+
|
|
221
|
+
Ordered steps — e.g. `trigger → resolve → fetch → degrade`. Useful when the change spans multiple phases or fallbacks.
|
|
222
|
+
|
|
223
|
+
### Design / Tradeoffs (optional)
|
|
224
|
+
|
|
225
|
+
Philosophy: **one-line principle in bold.**
|
|
226
|
+
|
|
227
|
+
| Option | Strengths | Weaknesses |
|
|
228
|
+
|:---|:---|:---|
|
|
229
|
+
| A | ... | ... |
|
|
230
|
+
| B | ... | ... |
|
|
231
|
+
|
|
232
|
+
### Scope
|
|
233
|
+
|
|
234
|
+
- Files or modules touched
|
|
235
|
+
- New exports, env vars, or config keys
|
|
236
|
+
- Tier (Tier 1 core / Tier 2 standard / Tier 3 optional peer dep)
|
|
237
|
+
|
|
238
|
+
### Out of scope
|
|
239
|
+
|
|
240
|
+
- What we're deliberately not doing
|
|
241
|
+
- Adjacent work that belongs in a separate issue
|
|
242
|
+
|
|
243
|
+
### Dependencies (optional)
|
|
244
|
+
|
|
245
|
+
- Depends on: owner/repo#N
|
|
246
|
+
|
|
197
247
|
### Alternatives considered
|
|
198
248
|
|
|
199
|
-
What you tried or
|
|
249
|
+
What you tried or evaluated instead, and why it didn't fit.
|
|
200
250
|
ISSUE
|
|
201
251
|
)"
|
|
202
252
|
````
|
|
@@ -4,7 +4,7 @@ description: >
|
|
|
4
4
|
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.
|
|
5
5
|
metadata:
|
|
6
6
|
author: cyanheads
|
|
7
|
-
version: "1.
|
|
7
|
+
version: "1.2"
|
|
8
8
|
audience: external
|
|
9
9
|
type: workflow
|
|
10
10
|
---
|
|
@@ -22,6 +22,8 @@ The bug is in this server's code, not in `@cyanheads/mcp-ts-core`. Typical trigg
|
|
|
22
22
|
|
|
23
23
|
**If the issue is in the framework itself** (builders, Context, utilities, type exports, linter), use `report-issue-framework` instead.
|
|
24
24
|
|
|
25
|
+
For general `gh` CLI workflows outside issue filing (PRs, workflows, API access), see the `github-cli` skill.
|
|
26
|
+
|
|
25
27
|
## Before Filing
|
|
26
28
|
|
|
27
29
|
1. **Identify the repo**:
|
|
@@ -40,6 +42,20 @@ gh issue list --search "your error message or keyword"
|
|
|
40
42
|
|
|
41
43
|
4. **Check logs** — review `ctx.log` output and any framework telemetry for clues. If running HTTP, check the response body for structured error details.
|
|
42
44
|
|
|
45
|
+
## Writing Well-Structured Issues
|
|
46
|
+
|
|
47
|
+
Good issues are scannable, concrete, and self-contained. These patterns apply to both bugs and features — the guidance targets any prose block (Description, Additional context, feature proposals).
|
|
48
|
+
|
|
49
|
+
- **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.
|
|
50
|
+
- **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.
|
|
51
|
+
- **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.
|
|
52
|
+
- **Add a `Related: #N` line** near the top when the issue grows from prior context (discussions, other issues, PRs). Makes provenance clickable.
|
|
53
|
+
- **Lead design sections with a philosophy sentence.** Bold a short principle before the tradeoff details — e.g. "Philosophy: **return best-effort data, don't fail the tool call on parsing edge cases.**" Establishes the lens for the rest of the section.
|
|
54
|
+
- **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.
|
|
55
|
+
- **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.
|
|
56
|
+
- **Use `Depends on: owner/repo#N`** to declare ordering explicitly when implementation is blocked on an upstream framework change or another issue landing first.
|
|
57
|
+
- **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.
|
|
58
|
+
|
|
43
59
|
## Redact Before Posting
|
|
44
60
|
|
|
45
61
|
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.
|
|
@@ -158,22 +174,61 @@ gh issue create --template "Feature Request" --web
|
|
|
158
174
|
|
|
159
175
|
### CLI (non-interactive)
|
|
160
176
|
|
|
177
|
+
Template below demonstrates the richer structure. Omit sections you don't need — simple requests don't require Flow / Design / Dependencies blocks.
|
|
178
|
+
|
|
161
179
|
````bash
|
|
162
180
|
gh issue create \
|
|
163
181
|
--title "feat(scope): concise description" \
|
|
164
182
|
--label "enhancement" \
|
|
165
183
|
--body "$(cat <<'ISSUE'
|
|
166
|
-
|
|
184
|
+
Concrete statement of what's currently missing or broken. Name the specific tool, service, resource, or domain area. Two or three sentences — the reader should know the gap before the end of the paragraph.
|
|
167
185
|
|
|
168
|
-
|
|
186
|
+
Related: #N
|
|
187
|
+
|
|
188
|
+
## Proposal
|
|
189
|
+
|
|
190
|
+
What you want the server to do, in one paragraph. Link external libraries or services on first mention: [lib name](https://github.com/owner/repo). Include a short justification — what this gives users that they don't have today.
|
|
169
191
|
|
|
170
192
|
### Proposed behavior
|
|
171
193
|
|
|
172
|
-
Describe the
|
|
194
|
+
Describe the new behavior or surface. For tool/resource changes, show example input/output or the new schema fields:
|
|
195
|
+
|
|
196
|
+
```ts
|
|
197
|
+
// Example: new input field or output shape
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Flow (optional)
|
|
201
|
+
|
|
202
|
+
Ordered steps — e.g. `request → lookup → fallback → respond`. Useful when the change spans multiple phases or fallbacks.
|
|
203
|
+
|
|
204
|
+
### Design / Tradeoffs (optional)
|
|
205
|
+
|
|
206
|
+
Philosophy: **one-line principle in bold.**
|
|
207
|
+
|
|
208
|
+
| Option | Strengths | Weaknesses |
|
|
209
|
+
|:---|:---|:---|
|
|
210
|
+
| A | ... | ... |
|
|
211
|
+
| B | ... | ... |
|
|
212
|
+
|
|
213
|
+
### Scope
|
|
214
|
+
|
|
215
|
+
- Files or modules touched
|
|
216
|
+
- New env vars, config keys, or service integrations
|
|
217
|
+
- New or modified tools / resources / prompts
|
|
218
|
+
|
|
219
|
+
### Out of scope
|
|
220
|
+
|
|
221
|
+
- What we're deliberately not doing
|
|
222
|
+
- Adjacent work that belongs in a separate issue
|
|
223
|
+
|
|
224
|
+
### Dependencies (optional)
|
|
225
|
+
|
|
226
|
+
- Depends on: cyanheads/mcp-ts-core#N (upstream framework change)
|
|
227
|
+
- Depends on: owner/repo#N (other server work)
|
|
173
228
|
|
|
174
229
|
### Alternatives considered
|
|
175
230
|
|
|
176
|
-
What you tried or
|
|
231
|
+
What you tried or evaluated instead, and why it didn't fit.
|
|
177
232
|
ISSUE
|
|
178
233
|
)"
|
|
179
234
|
````
|