AI导哈

MCP服务器模板

一个用于构建Model Context Protocol (MCP)服务器的TypeScript启动项目，提供回声服务器实现和开发工具支持。

  • by ralfboltshauser
  • HTML
  • 本地部署
  • 更新于
在 GitHub 查看 ralf-boltshauser/mcp-typescript-server-starter

使用说明

MCP TypeScript服务器启动器

一个用TypeScript构建模型上下文协议（MCP）服务器的启动项目。该项目提供了一个简单的echo服务器实现，演示了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. 选择“回声”工具
    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. 在以下位置测试SSE连接 https://subdomain.yourdomain.com/sse

🔌 连接到已部署的服务器

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

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

Cursor/Claude桌面的示例配置：

{
  "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

  1. 与Claude Desktop集成

    pnpm add-claude

    ⚠️ 备注：这将覆盖您现有的Claude Desktop配置。

    这种配置claude桌面的方式是标准的。生成的json也可以在游标等中使用！

  2. 手动积分 对于其他工具，请使用以下命令：

    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
    • 检查员：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”替换为this。

项目结构

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

服务器功能

回声工具

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

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

回声资源

可以通过URI访问的资源：

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

回声提示

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

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...",
});

这使您能够：

  • 实时跟踪服务器操作
  • 开发过程中的调试问题
  • 监控生产中的服务器状态

你可以在右下角的检查器中看到它们！

环境变量

对于服务器端环境变量（开发人员提供，非用户特定）：

  1. 使用Docker Compose

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

    这使您能够：

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

  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. 安全

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

许可证

麻省理工学院

相关 MCP