MCP TypeScript Server Starter

MCP TypeScript 服务入门项目

一个用于使用 TypeScript 构建 Model Context Protocol（MCP）服务的入门项目。此项目提供了一个简单的回显服务实现，用于演示 MCP 的核心功能。

快速入门清单

📥 安装

• 克隆仓库：

  git clone https://github.com/ralf-boltshauser/mcp-typescript-server-starter.git
  cd mcp-typescript-server-starter
  

• 安装依赖项：

  pnpm install
  

🛠️ 本地开发

• 启动开发服务：

  pnpm dev
  

• 访问检查器：http://localhost:6274
• 测试你的 MCP 服务：
  1. 在检查器中点击“连接”
  2. 前往“工具”部分
  3. 点击“列出工具”
  4. 选择“echo”工具
  5. 输入测试消息
  6. 点击“提交”
• 打开 src/index.ts，添加你自己的：
  • 工具（AI 可以调用的函数）
  • 资源（AI 可以访问的数据）
  • 提示词（用于 AI 交互的模板）
• 更新 src/index.html，填写服务的描述和文档

🚀 部署（Coolify 示例）

• 在 Coolify 上进行设置：
  1. 连接你的仓库
  2. 在高级设置中：
     • 禁用 GZIP 压缩（SSE 所必需）
  3. 配置域名：
     • 添加你的域名：https://subdomain.yourdomain.com:3001
       • :3001 至关重要，它会告知 traefik 绑定到你的内部端口
• 验证部署：
  1. 访问 subdomain.yourdomain.com 查看你的 index.html
  2. 在 https://subdomain.yourdomain.com/sse 测试 SSE 连接

🔌 连接到已部署的服务

使用此命令连接到你的服务：

npx -y mcp-remote https://subdomain.yourdomain.com/sse

Cursor/Claude Desktop 的示例配置：

{
  "mcpServers": {
    "your-server-name": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://subdomain.yourdomain.com/sse"]
    },
  }
}

功能

• 简单的回显服务实现
• 支持工具、资源和提示词
• 支持 TypeScript
• 支持热重载的开发服务
• 内置检查器，可用于测试和调试
• 支持 STDIO 和 SSE 两种通信模式

前置条件

• Node.js（v16 或更高版本）
• pnpm（推荐）或 npm

使用模式

此服务支持两种主要通信模式：

1. STDIO 模式

   • 非常适合本地开发和基础测试
   • 直接进程通信
   • 默认用于大多数 MCP 客户端
   • 非常适合在本地运行服务
   • 设置和使用简单

2. SSE 模式

   • 更适合生产环境部署
   • HTTP/SSE 通信
   • 可使用 npm 包转换为 STDIO（后文会介绍）
   • 支持远程访问你的服务
   • 可扩展性更强，更适合生产环境

本地开发请选择 STDIO；需要部署服务以便远程访问时，请选择 SSE。

STDIO 模式（直接进程通信）

此模式非常适合与 Cursor 或 Claude Desktop 等工具直接集成。

1. 配置服务

   • 在 src/index.ts 中：
     • 注释掉（底部的）Express/SSE 代码
     • 取消注释 STDIO 代码（上方部分）

2. 构建并运行

   pnpm build
   node dist/index.cjs
   

或

pnpm dev # starts the server and the inspector

3. 与 Claude Desktop 集成

   pnpm add-claude
   

   ⚠️ 注意：这会覆盖你现有的 Claude Desktop 配置。

   这是配置 Claude Desktop 的标准方式。生成的 json 也可用于 Cursor 等工具！

4. 手动集成 对于其他工具，请使用以下命令：

   node /path/to/your/project/dist/index.cjs
   

   或

   pnpm cmd # this gives you the node .../dist/index.cjs command directly with pwd
   

SSE 模式（HTTP/SSE 通信）

此模式非常适合基于 Web 的工具和远程部署。

1. 配置服务

   • 在 src/index.ts 中：
     • 保持 Express/SSE 代码启用（位于底部）
     • 注释掉 STDIO 代码（位于其上方）

2. 本地开发

   pnpm dev
   

   服务将在以下地址提供：

   • 主端点：http://127.0.0.1:3001
   • SSE 端点：http://127.0.0.1:3001/sse
   • 测试端点：http://127.0.0.1:3001/test
   • Inspector：http://127.0.0.1:6274

3. 本地 Docker 测试 需要使用 docker compose 覆盖配置才能实际公开这些端口。在 coolify 之类的平台上部署时则不需要，因为 traefik 会处理这些端口。

   docker compose -f docker-compose.yaml -f docker-compose.local.yaml up
   

4. 生产环境部署（例如 Coolify）

   • 让你的 IDE 更新 src/index.html，使其与服务描述相符。
   • 将服务部署到你首选的平台
   • 重要：在 Coolify 的高级设置中：
     • 禁用 GZIP 压缩（这会中断 SSE 流）
     • 确保正确公开端口 3001 -> 设置域名时，请按如下格式设置：https://your-domain.com:3001，这会告知 traefik 绑定到端口 3001。
     • 配置服务监听所有接口（0.0.0.0）（已完成）

5. 使用远程服务 部署后，你可以使用以下方式连接到服务：

   npx -y mcp-remote https://your-domain.com/sse
   

   你可以将其粘贴为命令，并将 "node .../dist/index.cjs" 替换为此内容。

项目结构

• src/index.ts - 主服务实现
• src/low-level-index.ts - 使用低级 API 的替代实现
• dist/ - 编译输出目录

服务功能

Echo 工具

一个简单的工具，可回显输入的消息：

server.tool("echo", { message: z.string() }, async ({ message }) => ({
  content: [{ type: "text", text: `Tool echo: ${message}` }],
}));

Echo 资源

一个可通过 URI 访问的资源：

server.resource(
  "echo",
  new ResourceTemplate("echo://{message}", { list: undefined }),
  async (uri, { message }) => ({
    contents: [
      {
        uri: uri.href,
        text: `Resource echo: ${message}`,
      },
    ],
  })
);

Echo 提示词

用于处理消息的提示词模板：

server.prompt("echo", { message: z.string() }, ({ message }) => ({
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: `Please process this message: ${message}`,
      },
    },
  ],
}));

实现建议

调试消息

可使用 server.server.sendLoggingMessage 方法发送调试消息，以便查看服务运行情况。

基本用法

server.server.sendLoggingMessage({
  level: "info",
  data: "Starting server...",
});

这有助于你：

• 实时跟踪服务运行情况
• 在开发过程中调试问题
• 在生产环境中监控服务状态

你可以在 Inspector 的右下角查看这些消息！

环境变量

对于服务端环境变量（由开发者提供，而非特定用户的变量）：

1. 使用 Docker Compose

   # docker-compose.yaml
   services:
     mmcp-server:
       environment:
         - API_KEY=${API_KEY}
         - DATABASE_URL=${DATABASE_URL}
   

   这使你能够：

   • 在 shell 中设置变量：export API_KEY=your-key
   • 使用 Docker Compose 会自动加载的 .env 文件

2. 在代码中访问

   const apiKey = process.env.API_KEY;
   const dbUrl = process.env.DATABASE_URL;
   

3. 本地开发

   • 在项目根目录创建 .env 文件：

     API_KEY=sk-123
     

   • 将 .env 添加到 .gitignore，以保护机密
   • 使用环境变量运行开发服务：

     pnpm dev
     

4. 生产环境部署

   • 在部署平台（例如 Coolify）中设置环境变量
   • 切勿将敏感值提交到版本控制系统

最佳实践

1. 错误处理

   • 始终为环境变量实现适当的错误处理
   • 为缺少必需变量的情况提供有意义的错误消息

2. 类型安全

   • 使用 TypeScript 定义环境变量类型
   • 考虑使用 zod 等验证库进行运行时检查

3. 安全性

   • 切勿向客户端公开敏感环境变量
   • 为开发环境和生产环境使用不同的变量集

许可证

MIT