# https://github.com/cyanheads/mcp-ts-template Project Manual
Generated on: 2026-05-22 15:39:59 UTC
## Table of Contents
- [Repository Overview](#overview)
- [Entrypoints and Runtime Surface](#entrypoints)
- [Architecture Evidence Map](#architecture)
- [Operations and Verification Boundaries](#operations)
## Repository Overview
### Related Pages
Related topics: [Entrypoints and Runtime Surface](#entrypoints), [Architecture Evidence Map](#architecture), [Operations and Verification Boundaries](#operations)
Relevant source files
The following source files were used to generate this page:
- [Dockerfile](https://github.com/cyanheads/mcp-ts-template/blob/main/Dockerfile)
- [README.md](https://github.com/cyanheads/mcp-ts-template/blob/main/README.md)
- [package.json](https://github.com/cyanheads/mcp-ts-template/blob/main/package.json)
- [skills/README.md](https://github.com/cyanheads/mcp-ts-template/blob/main/skills/README.md)
- [templates/Dockerfile](https://github.com/cyanheads/mcp-ts-template/blob/main/templates/Dockerfile)
- [templates/package.json](https://github.com/cyanheads/mcp-ts-template/blob/main/templates/package.json)
- [skills/polish-docs-meta/references/readme.md](https://github.com/cyanheads/mcp-ts-template/blob/main/skills/polish-docs-meta/references/readme.md)
- [src/index.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/index.ts)
- [src/cli/init.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/cli/init.ts)
- [src/config/index.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/config/index.ts)
- [src/config/parseEnvConfig.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/config/parseEnvConfig.ts)
- [src/core/app.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/core/app.ts)
# Repository Overview
This page is generated from repository evidence because the Human Wiki provider was unavailable. It intentionally limits itself to README and file-tree facts.
## README Evidence
@cyanheads/mcp-ts-core
Agent-native TypeScript framework for building MCP servers. Build tools, not infrastructure. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Bun/Node/Cloudflare Workers.
[](./CHANGELOG.md) [](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2025-11-25/changelog.mdx) [](https://modelcontextprotocol.io/) [](./LICENSE)
[](https://www.typescriptlang.org/) [](https://bun.sh/)
---
## What is this?
`@cyanheads/mcp-ts-core` is the infrastructure layer for TypeScript MCP servers. Install it as a dependency — don't fork it. Your agent collaborates with you to design and build the tools, resources, and prompts for your server.
The framework handles the plumbing: transports, auth, config, logging, telemetry, & more. Define your domain logic with the builders and let the framework take care of the rest.
```ts
import { createApp, tool, z } from '@cyanheads/mcp-ts-core';
const greet = tool('greet', {
description: 'Greet someone by name and return a personalized message.',
annotations: { readOnlyHint: true },
input: z.object({
name: z.string().describe('Name of the person to greet'),
}),
output: z.object({
message: z.string().describe('The greeting message'),
}),
errors: [
{
reason: 'name_blocked',
code: JsonRpcErrorCode.Forbidden,
when: 'The provided name is on the configured block list.',
recovery: 'Use a different name.',
},
],
handler: async (input, ctx) => {
if (isBlocked(input.name)) throw ctx.fail('name_blocked', `"${input.name}" is blocked`);
return { message: `Hello, ${input.name}!` };
},
});
await createApp({ tools: [greet] });
```
That's a complete MCP server. Every tool cal
[excerpt truncated]
## Selected Source Inventory
- `Dockerfile`
- `README.md`
- `package.json`
- `skills/README.md`
- `templates/Dockerfile`
- `templates/package.json`
- `skills/polish-docs-meta/references/readme.md`
- `src/index.ts`
- `src/cli/init.ts`
- `src/config/index.ts`
- `src/config/parseEnvConfig.ts`
- `src/core/app.ts`
| File | Evidence role | Size |
|---|---|---|
| `Dockerfile` | repository evidence | 4057 bytes |
| `README.md` | README/product and usage evidence | 15590 bytes |
| `package.json` | package/runtime metadata | 11594 bytes |
| `skills/README.md` | documentation evidence | 2004 bytes |
| `templates/Dockerfile` | repository evidence | 3517 bytes |
| `templates/package.json` | package/runtime metadata | 1625 bytes |
| `skills/polish-docs-meta/references/readme.md` | documentation evidence | 18454 bytes |
| `src/index.ts` | implementation surface | 270 bytes |
| `src/cli/init.ts` | implementation surface | 9118 bytes |
| `src/config/index.ts` | implementation surface | 26418 bytes |
| `src/config/parseEnvConfig.ts` | implementation surface | 2729 bytes |
| `src/core/app.ts` | implementation surface | 24448 bytes |
Source: `[README.md:1-120]()`
---
## Entrypoints and Runtime Surface
### Related Pages
Related topics: [Repository Overview](#overview), [Architecture Evidence Map](#architecture), [Operations and Verification Boundaries](#operations)
Relevant source files
The following source files were used to generate this page:
- [Dockerfile](https://github.com/cyanheads/mcp-ts-template/blob/main/Dockerfile)
- [README.md](https://github.com/cyanheads/mcp-ts-template/blob/main/README.md)
- [package.json](https://github.com/cyanheads/mcp-ts-template/blob/main/package.json)
- [skills/README.md](https://github.com/cyanheads/mcp-ts-template/blob/main/skills/README.md)
- [templates/Dockerfile](https://github.com/cyanheads/mcp-ts-template/blob/main/templates/Dockerfile)
- [templates/package.json](https://github.com/cyanheads/mcp-ts-template/blob/main/templates/package.json)
- [skills/polish-docs-meta/references/readme.md](https://github.com/cyanheads/mcp-ts-template/blob/main/skills/polish-docs-meta/references/readme.md)
- [src/index.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/index.ts)
- [src/cli/init.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/cli/init.ts)
- [src/config/index.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/config/index.ts)
- [src/config/parseEnvConfig.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/config/parseEnvConfig.ts)
- [src/core/app.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/core/app.ts)
# Entrypoints and Runtime Surface
The files below are the highest-signal candidates for how the project is installed, started, configured, or embedded. Treat this as an evidence map, not an inferred API contract.
| File | Evidence role | Size |
|---|---|---|
| `Dockerfile` | repository evidence | 4057 bytes |
| `README.md` | README/product and usage evidence | 15590 bytes |
| `package.json` | package/runtime metadata | 11594 bytes |
| `skills/README.md` | documentation evidence | 2004 bytes |
| `templates/Dockerfile` | repository evidence | 3517 bytes |
| `templates/package.json` | package/runtime metadata | 1625 bytes |
| `skills/polish-docs-meta/references/readme.md` | documentation evidence | 18454 bytes |
| `src/index.ts` | implementation surface | 270 bytes |
| `src/cli/init.ts` | implementation surface | 9118 bytes |
| `src/config/index.ts` | implementation surface | 26418 bytes |
| `src/config/parseEnvConfig.ts` | implementation surface | 2729 bytes |
| `src/core/app.ts` | implementation surface | 24448 bytes |
Source: `[Dockerfile:1-120](https://github.com/cyanheads/mcp-ts-template/blob/main/Dockerfile)`
---
## Architecture Evidence Map
### Related Pages
Related topics: [Repository Overview](#overview), [Entrypoints and Runtime Surface](#entrypoints), [Operations and Verification Boundaries](#operations)
Relevant source files
The following source files were used to generate this page:
- [Dockerfile](https://github.com/cyanheads/mcp-ts-template/blob/main/Dockerfile)
- [README.md](https://github.com/cyanheads/mcp-ts-template/blob/main/README.md)
- [package.json](https://github.com/cyanheads/mcp-ts-template/blob/main/package.json)
- [skills/README.md](https://github.com/cyanheads/mcp-ts-template/blob/main/skills/README.md)
- [templates/Dockerfile](https://github.com/cyanheads/mcp-ts-template/blob/main/templates/Dockerfile)
- [templates/package.json](https://github.com/cyanheads/mcp-ts-template/blob/main/templates/package.json)
- [skills/polish-docs-meta/references/readme.md](https://github.com/cyanheads/mcp-ts-template/blob/main/skills/polish-docs-meta/references/readme.md)
- [src/index.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/index.ts)
- [src/cli/init.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/cli/init.ts)
- [src/config/index.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/config/index.ts)
- [src/config/parseEnvConfig.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/config/parseEnvConfig.ts)
- [src/core/app.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/core/app.ts)
# Architecture Evidence Map
This section maps source paths into likely architectural areas based on repository layout only. Claims that require execution are intentionally not made here.
- `.`: `Dockerfile`, `README.md`, `package.json`
- `skills`: `skills/README.md`, `skills/polish-docs-meta/references/readme.md`
- `src`: `src/index.ts`, `src/cli/init.ts`, `src/config/index.ts`, `src/config/parseEnvConfig.ts`, `src/core/app.ts`
- `templates`: `templates/Dockerfile`, `templates/package.json`
Source: `[README.md:1-120](https://github.com/cyanheads/mcp-ts-template/blob/main/README.md)`
---
## Operations and Verification Boundaries
### Related Pages
Related topics: [Repository Overview](#overview), [Entrypoints and Runtime Surface](#entrypoints), [Architecture Evidence Map](#architecture)
Relevant source files
The following source files were used to generate this page:
- [Dockerfile](https://github.com/cyanheads/mcp-ts-template/blob/main/Dockerfile)
- [README.md](https://github.com/cyanheads/mcp-ts-template/blob/main/README.md)
- [package.json](https://github.com/cyanheads/mcp-ts-template/blob/main/package.json)
- [skills/README.md](https://github.com/cyanheads/mcp-ts-template/blob/main/skills/README.md)
- [templates/Dockerfile](https://github.com/cyanheads/mcp-ts-template/blob/main/templates/Dockerfile)
- [templates/package.json](https://github.com/cyanheads/mcp-ts-template/blob/main/templates/package.json)
- [skills/polish-docs-meta/references/readme.md](https://github.com/cyanheads/mcp-ts-template/blob/main/skills/polish-docs-meta/references/readme.md)
- [src/index.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/index.ts)
- [src/cli/init.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/cli/init.ts)
- [src/config/index.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/config/index.ts)
- [src/config/parseEnvConfig.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/config/parseEnvConfig.ts)
- [src/core/app.ts](https://github.com/cyanheads/mcp-ts-template/blob/main/src/core/app.ts)
# Operations and Verification Boundaries
Operational guidance is limited to files that are present in the repository. Before using this project in an agent workflow, verify install, quickstart, and runtime behavior in a sandbox.
- Containerization signal: `Dockerfile`
- Documentation signal: `README.md`
- Runtime/package signal: `package.json`
- Documentation signal: `skills/README.md`
- Containerization signal: `templates/Dockerfile`
- Runtime/package signal: `templates/package.json`
- Documentation signal: `skills/polish-docs-meta/references/readme.md`
- Source inspection signal: `src/index.ts`
- Source inspection signal: `src/cli/init.ts`
- Source inspection signal: `src/config/index.ts`
Source: `[package.json:1-120](https://github.com/cyanheads/mcp-ts-template/blob/main/package.json)`
---
---
## Doramagic Pitfall Log
Project: cyanheads/mcp-ts-template
Summary: Found 38 potential pitfall items; 4 are high/blocking. Highest priority: installation - 来源证据：bug(transport): HTTP per-request McpServer cleanup leaks ~30 KB/req on heap.
## 1. installation · 来源证据：bug(transport): HTTP per-request McpServer cleanup leaks ~30 KB/req on heap
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug(transport): HTTP per-request McpServer cleanup leaks ~30 KB/req on heap
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_b652b8d6139f43c1bcf51562afed3525 | https://github.com/cyanheads/mcp-ts-core/issues/50 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 2. configuration · 来源证据：bug(transport): list_changed notifications silently dropped under HTTP per-request McpServer model
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug(transport): list_changed notifications silently dropped under HTTP per-request McpServer model
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_3d3b719431cb499f914e169e6dce21b2 | https://github.com/cyanheads/mcp-ts-core/issues/135 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 3. configuration · 来源证据：feat(tool): flatten SDK input-validation error text and move issues to error.data (follow-up to #55)
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(tool): flatten SDK input-validation error text and move issues to error.data (follow-up to #55)
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_ed2fba370b864c57980fcc78c30fa336 | https://github.com/cyanheads/mcp-ts-core/issues/66 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. security_permissions · 失败模式：security_permissions: feat(auth): add RFC 7662 Token Introspection as a third auth strategy
- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: feat(auth): add RFC 7662 Token Introspection as a third auth strategy
- User impact: Developers may expose sensitive permissions or credentials: feat(auth): add RFC 7662 Token Introspection as a third auth strategy
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat(auth): add RFC 7662 Token Introspection as a third auth strategy. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/cyanheads/mcp-ts-core/issues/139
- Evidence: failure_mode_cluster:github_issue | fmev_79b989da05ab81a148513987aa506d71 | https://github.com/cyanheads/mcp-ts-core/issues/139 | feat(auth): add RFC 7662 Token Introspection as a third auth strategy
## 5. installation · 失败模式：installation: feat(templates): MCPB bundle packaging for scaffolded servers
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: feat(templates): MCPB bundle packaging for scaffolded servers
- User impact: Developers may fail before the first successful local run: feat(templates): MCPB bundle packaging for scaffolded servers
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat(templates): MCPB bundle packaging for scaffolded servers. Context: Observed when using node, docker, windows, macos
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_22c10ce8863043b0adf9a54a6f51d108 | https://github.com/cyanheads/mcp-ts-core/issues/137 | feat(templates): MCPB bundle packaging for scaffolded servers
## 6. installation · 来源证据：bug(utils): fetchWithTimeout collapses every non-ok HTTP status to ServiceUnavailable, erasing codes and causing spurio…
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：bug(utils): fetchWithTimeout collapses every non-ok HTTP status to ServiceUnavailable, erasing codes and causing spurious retries
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_9f6a4823d56640848bd04ac60d2856af | https://github.com/cyanheads/mcp-ts-core/issues/126 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 7. configuration · 失败模式：configuration: Connect card: active-tab styling, default to Claude, add Codex/Cursor/Gemini
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Connect card: active-tab styling, default to Claude, add Codex/Cursor/Gemini
- User impact: Developers may misconfigure credentials, environment, or host setup: Connect card: active-tab styling, default to Claude, add Codex/Cursor/Gemini
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Connect card: active-tab styling, default to Claude, add Codex/Cursor/Gemini. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_5c7acd2f18c877d832b1a859cd234468 | https://github.com/cyanheads/mcp-ts-core/issues/136 | Connect card: active-tab styling, default to Claude, add Codex/Cursor/Gemini
## 8. configuration · 失败模式：configuration: bug(utils): fetchWithTimeout attaches full upstream HTTP error body to error.data.responseBod...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: bug(utils): fetchWithTimeout attaches full upstream HTTP error body to error.data.responseBody — no cap, no MIME filter
- User impact: Developers may misconfigure credentials, environment, or host setup: bug(utils): fetchWithTimeout attaches full upstream HTTP error body to error.data.responseBody — no cap, no MIME filter
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(utils): fetchWithTimeout attaches full upstream HTTP error body to error.data.responseBody — no cap, no MIME filter. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_7d40e777d2ccdbab34bc3b3d1402bd71 | https://github.com/cyanheads/mcp-ts-core/issues/120 | bug(utils): fetchWithTimeout attaches full upstream HTTP error body to error.data.responseBody — no cap, no MIME filter
## 9. configuration · 失败模式：configuration: bug(worker): Workers compatibility — runtime detection broken under nodejs_compat, plus 8 rel...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: bug(worker): Workers compatibility — runtime detection broken under nodejs_compat, plus 8 related findings
- User impact: Developers may misconfigure credentials, environment, or host setup: bug(worker): Workers compatibility — runtime detection broken under nodejs_compat, plus 8 related findings
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(worker): Workers compatibility — runtime detection broken under nodejs_compat, plus 8 related findings. Context: Observed when using node
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_41ff925fb40ebff8720b5c65f8b20ece | https://github.com/cyanheads/mcp-ts-core/issues/124 | bug(worker): Workers compatibility — runtime detection broken under nodejs_compat, plus 8 related findings
## 10. configuration · 失败模式：configuration: changelog: raise summary cap from 250 → 350 chars
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: changelog: raise summary cap from 250 → 350 chars
- User impact: Developers may misconfigure credentials, environment, or host setup: changelog: raise summary cap from 250 → 350 chars
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: changelog: raise summary cap from 250 → 350 chars. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_5d2f31e619abdbc2e753d5c67819c1a8 | https://github.com/cyanheads/mcp-ts-core/issues/129 | changelog: raise summary cap from 250 → 350 chars
## 11. configuration · 失败模式：configuration: docs(api-canvas): add minimum-viable spillover server recipe as the default
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: docs(api-canvas): add minimum-viable spillover server recipe as the default
- User impact: Developers may misconfigure credentials, environment, or host setup: docs(api-canvas): add minimum-viable spillover server recipe as the default
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: docs(api-canvas): add minimum-viable spillover server recipe as the default. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_44db3da73c060fc8e7affa9e6c321749 | https://github.com/cyanheads/mcp-ts-core/issues/138 | docs(api-canvas): add minimum-viable spillover server recipe as the default
## 12. configuration · 失败模式：configuration: feat(docs/skills): codify agent-observed correctness across response design surface
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat(docs/skills): codify agent-observed correctness across response design surface
- User impact: Developers may misconfigure credentials, environment, or host setup: feat(docs/skills): codify agent-observed correctness across response design surface
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat(docs/skills): codify agent-observed correctness across response design surface. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_a5a5f36d76023182a160cd1189430916 | https://github.com/cyanheads/mcp-ts-core/issues/131 | feat(docs/skills): codify agent-observed correctness across response design surface
## 13. configuration · 失败模式：configuration: feat(linter): `schema-properties-need-type` — flag typeless leaves missed by `schema-anyof-ne...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat(linter): `schema-properties-need-type` — flag typeless leaves missed by `schema-anyof-needs-type`
- User impact: Developers may misconfigure credentials, environment, or host setup: feat(linter): `schema-properties-need-type` — flag typeless leaves missed by `schema-anyof-needs-type`
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat(linter): `schema-properties-need-type` — flag typeless leaves missed by `schema-anyof-needs-type`. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_008c058324c5476cab1114c3b507a398 | https://github.com/cyanheads/mcp-ts-core/issues/141 | feat(linter): `schema-properties-need-type` — flag typeless leaves missed by `schema-anyof-needs-type`
## 14. configuration · 失败模式：configuration: feat(linter,docs): cross-vendor JSON Schema portability rules
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat(linter,docs): cross-vendor JSON Schema portability rules
- User impact: Developers may misconfigure credentials, environment, or host setup: feat(linter,docs): cross-vendor JSON Schema portability rules
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat(linter,docs): cross-vendor JSON Schema portability rules. Context: Observed when using python
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_442715f721a7d8f0d431a38068bdcfcd | https://github.com/cyanheads/mcp-ts-core/issues/132 | feat(linter,docs): cross-vendor JSON Schema portability rules
## 15. configuration · 失败模式：configuration: feat(skill): polish-docs-meta should recommend linking OTEL_ENABLED to framework telemetry docs
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat(skill): polish-docs-meta should recommend linking OTEL_ENABLED to framework telemetry docs
- User impact: Developers may misconfigure credentials, environment, or host setup: feat(skill): polish-docs-meta should recommend linking OTEL_ENABLED to framework telemetry docs
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat(skill): polish-docs-meta should recommend linking OTEL_ENABLED to framework telemetry docs. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_94fb8f4bb9c19f4e783136fcde3ed772 | https://github.com/cyanheads/mcp-ts-core/issues/130 | feat(skill): polish-docs-meta should recommend linking OTEL_ENABLED to framework telemetry docs
## 16. configuration · 失败模式：configuration: feat(telemetry): wire Worker-native OTel exporter (sdk-trace-web + OTLP fetch)
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat(telemetry): wire Worker-native OTel exporter (sdk-trace-web + OTLP fetch)
- User impact: Developers may misconfigure credentials, environment, or host setup: feat(telemetry): wire Worker-native OTel exporter (sdk-trace-web + OTLP fetch)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat(telemetry): wire Worker-native OTel exporter (sdk-trace-web + OTLP fetch). Context: Observed when using node, cuda
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_e38ad2dfdd02625b61bb0948c324e842 | https://github.com/cyanheads/mcp-ts-core/issues/134 | feat(telemetry): wire Worker-native OTel exporter (sdk-trace-web + OTLP fetch)
## 17. configuration · 失败模式：configuration: feat(tool): first-class support for discriminated-union tool inputs (multi-mode tools)
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: feat(tool): first-class support for discriminated-union tool inputs (multi-mode tools)
- User impact: Developers may misconfigure credentials, environment, or host setup: feat(tool): first-class support for discriminated-union tool inputs (multi-mode tools)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat(tool): first-class support for discriminated-union tool inputs (multi-mode tools). Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_de75bb8a294c55ed56f1bb44faf7bd37 | https://github.com/cyanheads/mcp-ts-core/issues/142 | feat(tool): first-class support for discriminated-union tool inputs (multi-mode tools)
## 18. configuration · 来源证据：feat(telemetry): wire Worker-native OTel exporter (sdk-trace-web + OTLP fetch)
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat(telemetry): wire Worker-native OTel exporter (sdk-trace-web + OTLP fetch)
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_22e974aafd5649c7b4e239b2a07a33ec | https://github.com/cyanheads/mcp-ts-core/issues/134 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 19. capability · 能力判断依赖假设
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: 假设不成立时，用户拿不到承诺的能力。
- Suggested check: 将假设转成下游验证清单。
- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。
- Evidence: capability.assumptions | mcp_registry:io.github.cyanheads/mcp-ts-template:3.0.9 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.cyanheads%2Fmcp-ts-template/versions/3.0.9 | README/documentation is current enough for a first validation pass.
## 20. runtime · 失败模式：runtime: bug(transport): list_changed notifications silently dropped under HTTP per-request McpServer...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: bug(transport): list_changed notifications silently dropped under HTTP per-request McpServer model
- User impact: Developers may hit a documented source-backed failure mode: bug(transport): list_changed notifications silently dropped under HTTP per-request McpServer model
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(transport): list_changed notifications silently dropped under HTTP per-request McpServer model. Context: Observed when using node
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_c771a0d6f06fc6e6e023bd2f45ada5a3 | https://github.com/cyanheads/mcp-ts-core/issues/135 | bug(transport): list_changed notifications silently dropped under HTTP per-request McpServer model
## 21. runtime · 失败模式：runtime: bug(utils): fetchWithTimeout collapses every non-ok HTTP status to ServiceUnavailable, erasin...
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: bug(utils): fetchWithTimeout collapses every non-ok HTTP status to ServiceUnavailable, erasing codes and causing spurious retries
- User impact: Developers may hit a documented source-backed failure mode: bug(utils): fetchWithTimeout collapses every non-ok HTTP status to ServiceUnavailable, erasing codes and causing spurious retries
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(utils): fetchWithTimeout collapses every non-ok HTTP status to ServiceUnavailable, erasing codes and causing spurious retries. Context: Observed when using macos
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_e7737d7800a604e87586603a0d3fe8d5 | https://github.com/cyanheads/mcp-ts-core/issues/126 | bug(utils): fetchWithTimeout collapses every non-ok HTTP status to ServiceUnavailable, erasing codes and causing spurious retries
## 22. maintenance · 失败模式：migration: bug(utils): logger rate-limit map only sweeps when suppression triggered
- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: bug(utils): logger rate-limit map only sweeps when suppression triggered
- User impact: Developers may hit a documented source-backed failure mode: bug(utils): logger rate-limit map only sweeps when suppression triggered
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(utils): logger rate-limit map only sweeps when suppression triggered. Context: Source discussion did not expose a precise runtime context.
- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_0716f10fda662c3e061d6b59d0f45b12 | https://github.com/cyanheads/mcp-ts-core/issues/115 | bug(utils): logger rate-limit map only sweeps when suppression triggered
## 23. maintenance · 来源证据：bug(utils): logger rate-limit map only sweeps when suppression triggered
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：bug(utils): logger rate-limit map only sweeps when suppression triggered
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_8fb7b505af3f480c95c67b34c105329e | https://github.com/cyanheads/mcp-ts-core/issues/115 | 来源类型 github_issue 暴露的待验证使用条件。
## 24. maintenance · 维护活跃度未知
- Severity: medium
- Evidence strength: source_linked
- Finding: 未记录 last_activity_observed。
- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。
- Evidence: evidence.maintainer_signals | mcp_registry:io.github.cyanheads/mcp-ts-template:3.0.9 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.cyanheads%2Fmcp-ts-template/versions/3.0.9 | last_activity_observed missing
## 25. security_permissions · 下游验证发现风险项
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 下游已经要求复核，不能在页面中弱化。
- Suggested check: 进入安全/权限治理复核队列。
- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。
- Evidence: downstream_validation.risk_items | mcp_registry:io.github.cyanheads/mcp-ts-template:3.0.9 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.cyanheads%2Fmcp-ts-template/versions/3.0.9 | no_demo; severity=medium
## 26. security_permissions · 存在评分风险
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 风险会影响是否适合普通用户安装。
- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。
- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。
- Evidence: risks.scoring_risks | mcp_registry:io.github.cyanheads/mcp-ts-template:3.0.9 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.cyanheads%2Fmcp-ts-template/versions/3.0.9 | no_demo; severity=medium
## 27. security_permissions · 来源证据：bug(utils): fetchWithTimeout attaches full upstream HTTP error body to error.data.responseBody — no cap, no MIME filter
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(utils): fetchWithTimeout attaches full upstream HTTP error body to error.data.responseBody — no cap, no MIME filter
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_5df71519e99747a0a028db7767bd9b86 | https://github.com/cyanheads/mcp-ts-core/issues/120 | 来源类型 github_issue 暴露的待验证使用条件。
## 28. security_permissions · 来源证据：bug(utils): unbounded label cardinality on mcp.ratelimit.rejections counter
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(utils): unbounded label cardinality on mcp.ratelimit.rejections counter
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_c1d184e56e66446085332f42b7500be4 | https://github.com/cyanheads/mcp-ts-core/issues/114 | 来源类型 github_issue 暴露的待验证使用条件。
## 29. security_permissions · 来源证据：bug(worker): Workers compatibility — runtime detection broken under nodejs_compat, plus 8 related findings
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：bug(worker): Workers compatibility — runtime detection broken under nodejs_compat, plus 8 related findings
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_a6e8146b33d0467584baf5d0c8d433c8 | https://github.com/cyanheads/mcp-ts-core/issues/124 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 30. security_permissions · 来源证据：changelog: raise summary cap from 250 → 350 chars
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：changelog: raise summary cap from 250 → 350 chars
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_d2eeeaa093654bed9869dc412630cb74 | https://github.com/cyanheads/mcp-ts-core/issues/129 | 来源类型 github_issue 暴露的待验证使用条件。
## 31. security_permissions · 来源证据：docs(api-canvas): add minimum-viable spillover server recipe as the default
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：docs(api-canvas): add minimum-viable spillover server recipe as the default
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_d5b1c38bbee5494abc71a7f891389997 | https://github.com/cyanheads/mcp-ts-core/issues/138 | 来源类型 github_issue 暴露的待验证使用条件。
## 32. security_permissions · 来源证据：feat(docs/skills): codify agent-observed correctness across response design surface
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(docs/skills): codify agent-observed correctness across response design surface
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_8db18d54bc9948a28dcf10fd5207d1fa | https://github.com/cyanheads/mcp-ts-core/issues/131 | 来源类型 github_issue 暴露的待验证使用条件。
## 33. security_permissions · 来源证据：feat(linter): `schema-properties-need-type` — flag typeless leaves missed by `schema-anyof-needs-type`
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(linter): `schema-properties-need-type` — flag typeless leaves missed by `schema-anyof-needs-type`
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_680ec4f7c0ff4c8c9f29762e8c8e2520 | https://github.com/cyanheads/mcp-ts-core/issues/141 | 来源类型 github_issue 暴露的待验证使用条件。
## 34. security_permissions · 来源证据：feat(linter,docs): cross-vendor JSON Schema portability rules
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(linter,docs): cross-vendor JSON Schema portability rules
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_69d95636c7024bf2bb5d8aad01b7ab6d | https://github.com/cyanheads/mcp-ts-core/issues/132 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 35. security_permissions · 来源证据：feat(skill): polish-docs-meta should recommend linking OTEL_ENABLED to framework telemetry docs
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(skill): polish-docs-meta should recommend linking OTEL_ENABLED to framework telemetry docs
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_0280b913a8284f73ad4ac3932a76ebd5 | https://github.com/cyanheads/mcp-ts-core/issues/130 | 来源类型 github_issue 暴露的待验证使用条件。
## 36. security_permissions · 来源证据：feat(tool): first-class support for discriminated-union tool inputs (multi-mode tools)
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(tool): first-class support for discriminated-union tool inputs (multi-mode tools)
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_8a3ab16a17764a828dc447d9462d875c | https://github.com/cyanheads/mcp-ts-core/issues/142 | 来源类型 github_issue 暴露的待验证使用条件。
## 37. maintenance · issue/PR 响应质量未知
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: 用户无法判断遇到问题后是否有人维护。
- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。
- Guardrail action: issue/PR 响应未知时，必须提示维护风险。
- Evidence: evidence.maintainer_signals | mcp_registry:io.github.cyanheads/mcp-ts-template:3.0.9 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.cyanheads%2Fmcp-ts-template/versions/3.0.9 | issue_or_pr_quality=unknown
## 38. maintenance · 发布节奏不明确
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。
- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- Evidence: evidence.maintainer_signals | mcp_registry:io.github.cyanheads/mcp-ts-template:3.0.9 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.cyanheads%2Fmcp-ts-template/versions/3.0.9 | release_recency=unknown