MCP TypeScript Starter

MCP TypeScript Starter 是一个以生产环境为考量、使用 TypeScript 构建 Model Context Protocol 服务器的基础项目。它包含一个类型化的示例工具、stdio 和 Streamable HTTP 传输、严格的校验、测试、加固容器，以及自动化的 GHCR 发布。

克隆它，替换示例业务领域，并保留真正的 MCP 服务器所需的基础设施。

导航

• 使用此模板

• 关于

• 功能特性

• MCP 工具

• 技术栈

• 安装

• 配置

• 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 流量。

• 仅在质量检查通过后发布多架构镜像。

MCP 工具

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+

• TypeScript（采用严格的项目规则）

• Model Context Protocol TypeScript SDK 2

• Hono

• Zod

• Vitest

• pnpm

• Docker

安装

先决条件

• Node.js 24+ 和 pnpm 11，用于本地开发。

• Docker 和 Docker Compose，用于容器部署。

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 -d

Streamable HTTP 和健康检查端点将可在以下地址访问：

http://<host>:3000/mcp
http://<host>:3000/healthz

如需发布不同的主机端口，请设置 MCP_PUBLISHED_PORT。应用程序在容器内部仍使用端口 3000。

latest 标签跟随默认分支上最新成功的构建。请使用版本标签或不可变的 sha-* 标签，以实现受控部署和回滚。

Docker run

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:latest

从源码构建容器

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
docker buildx build --load -t mcp-typescript-starter:local .

本地 Node.js 安装

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

配置

--transport 命令行选项会覆盖 MCP_TRANSPORT。MCP_ALLOWED_HOSTS 包含的是主机名而非 URL；请确保包含所有合法客户端和健康检查使用的主机名。

服务器在示例配置中没有机密信息。请通过部署平台或环境添加域凭据，切勿将其作为 MCP 工具参数或写入提交的文件中。

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 消息。

客户端配置格式各不相同。请查阅客户端的文档以了解其确切模式，并在更改服务器定义后重启或重新加载客户端。

自定义此模板

主要的扩展点被刻意设计得很直接：

1. 复制或替换 src/tools/echo.ts。

2. 在编写处理程序之前定义严格的输入和输出模式。

3. 在 src/server.ts 中注册工具。

4. 添加 MCP 行为测试和任何领域集成测试。

5. 替换包名、服务器身份、镜像引用和 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。