MCP TypeScript Starter 是一个以生产环境为考量、使用 TypeScript 构建 Model Context Protocol 服务器的基础项目。它包含一个类型化的示例工具、stdio 和 Streamable HTTP 传输、严格的校验、测试、加固容器，以及自动化的 GHCR 发布。
克隆它，替换示例业务领域，并保留真正的 MCP 服务器所需的基础设施。
Related MCP server: mcp-server-http-streamable
在 GitHub 上点击 使用此模板，创建一个拥有独立 Git 历史的 MCP 服务器。创建后，按照 自定义此模板 中的说明替换示例工具并更新项目身份。
如果你希望通过 Pull Request 回馈改进，请 Fork 此仓库。在提交更改之前，请参阅 贡献。
如果这个模板帮助到了你，请考虑为该仓库加一个 Star。这有助于其他 TypeScript 开发者发现该项目。
该模板演示了从经过验证的 MCP 工具定义到客户端可见的结构化结果的完整路径。服务器使用当前的模块化 MCP TypeScript SDK 和 Hono 的 Web 标准 HTTP 模型，而不是自定义服务器框架。
默认的 stdio 传输适用于将服务器作为子进程启动的本地客户端。Streamable HTTP 是无状态的，并为每个请求创建一个全新的 MCP 服务器，因此无需共享会话存储即可进行复制。
该示例执行有界的内存操作。没有遥测、应用程序数据库、持久化存储、身份验证或外部服务依赖。
使用严格的 Zod 输入和输出模式注册工具。
返回人类可读的内容和类型化的结构化内容。
包含准确的 MCP 安全注解。
支持 stdio 和无状态的 Streamable HTTP。
使用 Hono，并通过 Host 和 Origin 校验来防御 DNS 重绑定。
默认将 HTTP 绑定到回环地址，并要求其他接口使用允许列表。
限制工具输入和 HTTP 请求体的大小。
在 stdio 模式下保持 stdout 专用于 MCP 协议消息。
使用幂等的优雅停机处理 SIGINT 和 SIGTERM。
以非 root 容器运行，并支持只读根文件系统。
测试配置、stdio 集成、MCP 行为、Hono 路由和真实 HTTP 流量。
仅在质量检查通过后发布多架构镜像。
echo回显一条经过验证的消息和可选的字符串元数据。它刻意保持简单，以便该仓库可以教授 MCP 模式、注册、注解和结果，而不需要引入业务领域。
示例输入：
{
"message": "Hello, MCP!",
"metadata": {
"source": "example-client"
}
}示例结构化输出：
{
"message": "Hello, MCP!",
"metadata": {
"source": "example-client"
}
}消息最多 10,000 个字符。元数据最多接受 20 个条目；键最长 64 个字符，值最长 1,024 个字符。
Node.js 24+ 和 pnpm 11，用于本地开发。
Docker 和 Docker Compose，用于容器部署。
推荐的 HTTP 部署使用已发布的多架构镜像：
ghcr.io/lukegskw/mcp-typescript-starter:latest下载 Compose 示例，并提供客户端将使用的主机名：
curl -O https://raw.githubusercontent.com/lukegskw/mcp-typescript-starter/main/compose.example.yaml
export MCP_ALLOWED_HOSTS='mcp.example.internal'
docker compose -f compose.example.yaml up -dStreamable HTTP 和健康检查端点将可在以下地址访问：
http://<host>:3000/mcp
http://<host>:3000/healthz如需发布不同的主机端口，请设置 MCP_PUBLISHED_PORT。应用程序在容器内部仍使用端口 3000。
latest 标签跟随默认分支上最新成功的构建。请使用版本标签或不可变的 sha-* 标签，以实现受控部署和回滚。
docker run -d \
--name mcp-typescript-starter \
--restart unless-stopped \
--read-only \
--user 10001:10001 \
--cap-drop ALL \
--security-opt no-new-privileges:true \
--tmpfs /tmp:size=16m,mode=1777 \
-e MCP_TRANSPORT=streamable-http \
-e MCP_HOST=0.0.0.0 \
-e MCP_ALLOWED_HOSTS=127.0.0.1,localhost,mcp.example.internal \
-p 3000:3000 \
ghcr.io/lukegskw/mcp-typescript-starter:latestgit clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
docker buildx build --load -t mcp-typescript-starter:local .git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
pnpm install --frozen-lockfile
pnpm build
pnpm start -- --transport stdio用于本地 Streamable HTTP 开发：
MCP_TRANSPORT=streamable-http pnpm dev变量 | 必填 | 默认值 | 说明 |
| 否 |
|
|
| 否 |
| HTTP 绑定地址。 |
| 否 |
| HTTP 监听端口。 |
| 非回环地址时 | 无 | 以逗号分隔的 Host 和 Origin 主机名允许列表。 |
--transport 命令行选项会覆盖 MCP_TRANSPORT。MCP_ALLOWED_HOSTS 包含的是主机名而非 URL；请确保包含所有合法客户端和健康检查使用的主机名。
服务器在示例配置中没有机密信息。请通过部署平台或环境添加域凭据，切勿将其作为 MCP 工具参数或写入提交的文件中。
对于接受 Streamable HTTP 服务器定义的客户端：
mcp_servers:
starter:
url: http://127.0.0.1:3000/mcp对于启动本地 stdio 服务器的客户端：
{
"mcpServers": {
"starter": {
"command": "node",
"args": [
"/absolute/path/to/mcp-typescript-starter/dist/main.js",
"--transport",
"stdio"
]
}
}
}要让本地客户端通过 stdio 启动容器，请使用 docker run -i --rm，并在镜像名之后传递 --transport stdio。-i 是必需的，这样客户端才能通过标准输入和输出交换 MCP 消息。
客户端配置格式各不相同。请查阅客户端的文档以了解其确切模式，并在更改服务器定义后重启或重新加载客户端。
主要的扩展点被刻意设计得很直接：
复制或替换 src/tools/echo.ts。
在编写处理程序之前定义严格的输入和输出模式。
在 src/server.ts 中注册工具。
添加 MCP 行为测试和任何领域集成测试。
替换包名、服务器身份、镜像引用和 README 内容。
让工具模块负责各自的模式和处理程序。保持传输模块与领域工具相互独立。只有在真实行为需要时，才引入服务或持久化。
运行完整的仓库测试套件：
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build针对容器更改：
docker buildx build --load -t mcp-typescript-starter:test .最后，连接一个 MCP 客户端，确认 echo 已列出，并且同时返回文本和结构化内容。在 HTTP 模式下，确认 /healthz 返回 {"status":"ok"}。
该示例只暴露一个工具，没有资源或提示词。
Streamable HTTP 没有身份验证。请将其限制在回环地址、受信任的局域网、VPN、私有容器网络或经过身份验证的反向代理内。
Host 和 Origin 允许列表可以防止某些类别的 DNS 重绑定攻击，但不会对调用者进行身份验证。
HTTP 服务器是无状态的，不包含共享持久化或分布式协调。
未包含速率限制、链路追踪、指标和特定领域的日志记录。
该仓库是一个源码模板，而不是已发布的 npm 库。
在暴露 HTTP 传输或报告安全漏洞之前，请查阅 SECURITY.md。
欢迎贡献。在提交 Pull Request 之前：
pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t mcp-typescript-starter:test .更改必须保留严格类型、有界校验、结构化 MCP 结果、stdout 协议纯净性、安全的 HTTP 默认值、确定性测试，以及针对用户可见行为的文档。不要在没有具体用例的情况下添加抽象。
MIT。参见 LICENSE。
Echo a validated message and optional string metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| metadata | No |
| Name | Required | Description |
|---|---|---|
| message | Yes | |
| metadata | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect expectations. The description adds minimal behavioral context, mainly 'validated', which hints that inputs are checked but not how. No contradiction with annotations; the bar is lower, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no unnecessary words. The verb is front-loaded, and the optional part is clearly flagged. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a trivial echo tool, the description is nearly sufficient. The output schema exists, and annotations cover read-only/idempotent behavior, so return-value details are not needed. The only gap is vague 'validated' wording, but the tool is simple enough that an agent can invoke it correctly with the given information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It names 'message' and 'optional string metadata', but the schema already provides types and constraints. Calling metadata 'string metadata' is potentially misleading because the schema defines metadata as an object with string values, not a string. This adds little value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('echo') and resource ('a validated message and optional string metadata'), making the core function clear. There are no sibling tools to differentiate from, so the lack of distinction is not a flaw. However, 'validated' is slightly ambiguous — it might imply an extra validation step that is actually handled by the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool or what to prefer it over. There are no siblings, but the description still does not state typical scenarios (e.g., debugging, round-trip testing). The intended usage is only implied by the verb 'echo'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0echoScored across 1 tool
With only one tool, there is no possibility of confusion or overlap. The single 'echo' tool is clearly distinct by virtue of being the only tool available.
The single tool name 'echo' is short, clear, and directly describes its function. Since there is only one tool, naming consistency is trivially satisfied.
One tool feels minimal even for a starter server, but it is a common pattern for a simple template. The count is at the lower edge of being acceptable rather than egregiously insufficient.
The server only provides an echo function, which is useful for testing connectivity but lacks any real domain operations. There are no CRUD or workflow capabilities, representing a significant gap for any practical use beyond a basic demo.
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
A Model Context Protocol server for Wix AI tools
Ovanek MCP: Model Context Protocol server for Ovanek platform tools; writes are dry-run by default.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
