AI导哈

MCP服务器模板

一个基于TypeScript的、结构良好、可维护且可扩展的MCP服务器模板项目，旨在加速开发、促进一致性并整合最佳实践。

  • by Falkicon
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 falkicon/mcp-server-template

使用说明

MCP服务器模板（TypeScript）

一个结构良好、可维护和可扩展的样板项目，用于使用TypeScript构建模型上下文协议（MCP）服务器。此样板旨在加速开发，促进一致性，并纳入创建MCP集成的最佳实践。

特性

  • TypeScript： 现代、类型安全的JavaScript。
  • MCP-SDK： 使用官方 @modelcontextprotocol/sdk.
  • 重点实施： 简化了stdio传输支持，实现了简单性和可靠性。
  • 图元示例： 包括以下基本示例：
    • 工具： greet （带可配置前缀的问候语）和 add （简易计算器）
    • 资源： welcome （欢迎留言资源）
    • 提示： summarize （主题摘要提示）
  • 配置： 从加载配置 .env 文件和环境变量(src/config.ts).
  • 验证： 用途 zod 用于基元中的稳健参数验证。
  • 结构化日志记录： 用途 pino 用于结构化JSON日志记录(src/logger.ts).漂亮的打印日志正在开发中。
  • 错误处理： 自定义错误类(src/errors.ts)并且始终如一 try/catch 所有处理程序中的模式。
  • 集装箱化： 多级 Dockerfile 用于创建优化的生产图像。
  • 装订/格式化： 配置ESLint和Prettier。
  • 测试： 使用Vitest进行设置。包括配置加载的示例测试(tests/config.test.ts)以及 greet 工具操作员(tests/greet.test.ts).

先决条件

  • Node.js（建议使用v18或更高版本）
  • npm（通常包含在Node.js中）
  • Docker（可选，用于在容器中运行）

设置和安装

  1. 克隆存储库（或用作模板）：

    # If you cloned it
git clone <repository-url>
cd mcp-server-boilerplate

  2. 安装依赖项：

    npm install

  3. 配置环境（可选）：

    • 复制示例环境文件：
      cp .env.example .env
    • 编辑 .env 文件来设置所需的配置（请参阅 配置 部分）。

配置

配置是通过环境变量进行管理的，这些变量可以从 .env 本地开发文件。

  • LOG_LEVEL：日志记录的最低级别（例如。， trace, debug, info, warn, error, fatal).（默认值： info).
  • NODE_ENV：设置为 production 用于优化构建和标准JSON日志。默认为 development （启用漂亮的日志）。
  • CUSTOM_GREETING_PREFIX：问候工具的可选前缀（例如，“👋 “）。默认值为空。

运行服务器

开发模式（带热重载和漂亮日志）

此命令使用 tsx 直接运行TypeScript代码并通过管道传输输出 pino-pretty.

npm run dev

注： dev 脚本需要 pino-pretty 待安装(npm install --save-dev pino-pretty).

  • 日志将很好地打印到控制台上。

生产模式（编译JavaScript）

  1. 构建TypeScript代码：

    npm run build

    这将代码编译为 dist/ 目录。

  2. 运行服务器：

    # Example: Set custom greeting prefix with emoji
set CUSTOM_GREETING_PREFIX=👋 
set NODE_ENV=production
npm start

    日志将采用JSON格式。

使用Docker运行

  1. 构建Docker镜像：

    docker build -t mcp-server-boilerplate .

  2. 运行容器：

    # Run with stdio transport 
# (Needs an interactive terminal)
docker run -i --rm --name mcp-server-stdio mcp-server-boilerplate
    • 调整环境变量(-e)根据需要。

延长锅炉板

  1. 添加工具：

    • 为中的参数定义Zod模式 src/index.ts （或单独 src/tools/ 目录）。
    • 使用 server.tool(name, schemaDefinition, handler).
    • 实现处理程序逻辑，可能使用来自的自定义错误 src/errors.ts 为了保持一致性。
    • 重要： 仅使用简单名称注册工具（例如，“add”，而不是“mcp_minal_add”）。游标会自动为AI工具调用应用前缀。

  2. 添加资源：

    • 对于静态资源： server.resource(name, uri, metadata, handler).
    • 对于动态资源：定义 ResourceTemplate 和使用 server.resource(name, template, metadata, handler).
    • 实现处理程序逻辑。

  3. 添加提示：

    • 为参数定义Zod模式。
    • 使用 server.prompt(name, schemaDefinition, handler).
    • 实现处理程序逻辑以返回所需的消息结构。

  4. 添加配置：

    • 向添加新的环境变量 .env.example.
    • 从读取并导出验证值 src/config.ts.

MCP工具调用

使用MCP工具时，了解它们是如何调用的非常重要：

  1. AI工具调用： MCP工具旨在由AI助手调用，而不是由用户直接调用。AI可以使用前缀名称直接调用工具。

  2. 工具命名：

    • 用简单的名称注册工具（例如“添加”）
    • AI将看到带有前缀名称的工具（例如“mcp_mcp_minimal_add”）
    • 不要注册带有前缀名称的工具，因为这会造成重复

  3. 日志记录注意事项：

    • 在stdio模式下运行时，所有日志记录必须转到stderr，而不是stdout
    • Stout严格保留用于JSON-RPC消息
    • 使用console.log（）将破坏JSON-RPC协议-使用写入stderr的自定义记录器

  4. 用户界面：

    • 用户不能在聊天界面直接调用MCP工具
    • AI助手充当中介，代表用户调用工具

常见问题

根据我们开发此样板的经验，以下是一些需要注意的常见问题：

  1. JSON-RPC协议问题：

    • 发送到stdout的任何非JSON RPC消息（如console.log输出）都会破坏stdio传输机制。所有调试日志都必须写入stderr。
    • 在stdio模式下，只应将有效的JSON-RPC消息发送到stdout。

  2. 工具名称前缀：

    • 游标会自动为AI助手调用的工具名称添加前缀。例如，如果你的服务器名为“mcp_minal”，你注册了一个名为“add”的工具，人工智能会将其称为“mcp-mcp_minal_add”。
    • 避免使用简单名称和前缀名称注册工具，因为这会在AI的可用工具中创建重复条目。

  3. MCP工具调用：

    • MCP工具旨在由AI助手调用，而不是由聊天中的用户直接调用。用户无法在聊天界面中使用“@Tool”语法调用MCP工具。
    • AI会自动发现已注册的工具，并可以在没有用户配置的情况下调用它们。

客户端配置示例

以下是如何配置像Cursor这样的客户端以连接到此服务器的示例。

通过Stdio连接（建议用于当地开发）

此方法使用Cursor的 mcp.json 文件（通常 ~/.cursor/mcp.json 在Linux/macOS或 C:\Users\<username>\.cursor\mcp.json 在Windows上）。

  1. 确保你已经跑步了 npm run build 创建 dist/index.js 文件。

  2. 将脚本添加到您的 package.json 要显式运行编译后的stdio服务器：

    "scripts": {
  // ... other scripts
  "start:stdio": "cross-env NODE_ENV=production node dist/index.js --stdio"
}

  3. 安装 cross-env 如果你还没有： npm install --save-dev cross-env.

  4. 在中配置服务器 mcp.json （确保没有JSON注释 // 存在于文件中）：

    {
  "mcpServers": {
    "mcp_minimal": {
      "displayName": "MCP Minimal",
      "command": "node",
      "args": [
        "C:\\path\\to\\your\\project\\dist\\index.js",
        "--stdio"
      ],
      "env": {
        "NODE_ENV": "production"
      },
      "enabled": true
    }
  }
}
    • 重要提示： 替换 "C:\\path\\to\\your\\project\\dist\\index.js" 与正确 绝对路径 到 dist/index.js 文件在 你的 项目目录。使用双反睫毛(\\)作为Windows上的路径分隔符。
    • 此配置直接调用 node 使用绝对脚本路径，绕过潜在问题 npm 以及由Cursor启动时的相对路径。

基本安全注意事项

  • 输入验证： Zod模式用于基本验证。确保模式足够严格以满足您的需求。
  • 错误处理： 避免在发送回客户端的错误消息中泄露敏感信息。当前设置抛出错误，SDK会进行转换；查看SDK的错误格式。
  • 资源访问： 如果资源/工具处理程序访问敏感数据或执行受限操作（当前未实现），则在资源/工具处理器中实施授权检查。
  • 依赖关系： 定期审核漏洞的依赖关系(npm audit).
  • 集装箱安全： 这 Dockerfile 使用非root用户。保持基础图像更新。

测试

  • 使用Vitest运行测试：
    npm test
  • 在监视模式下运行测试：
    npm run test:watch
  • 生成覆盖率报告：
    npm run coverage
  • 在中添加新的测试文件 tests/ 目录后面 *.test.ts 图案。

装订和格式化

  • 检查格式： npm run format
  • 应用格式： npm run format:fix
  • 运行门楣： npm run lint
  • 修复过梁错误： npm run lint:fix

局限性

MCP是一种非常新的协议，目前仍在积极开发中。有一些已知的注意事项需要注意：

  • AI模型兼容性： Cursor AI代理能够自动使用或被提示使用自定义MCP工具 模型依赖一些模型可能难以启动对动态发现的工具的调用，即使它们在设置中正确列出。如果遇到AI工具调用问题，可能需要在Cursor中使用不同的AI模型进行测试。
  • 工具数量： 一些MCP服务器或有许多活动MCP服务器的用户可能有许多工具可供Cursor使用。目前，Cursor只会将前40个工具发送给代理。
  • 远程开发： Cursor直接通过本地计算机与MCP服务器通信 stdio 或通过网络使用 sse因此，当通过SSH或其他开发环境访问Cursor时，MCP服务器可能无法正常工作。我们希望在未来的版本中对此进行改进。
  • MCP功能支持： MCP服务器提供三种主要功能：工具、资源和提示。目前，Cursor仅支持工具。资源和提示在协议中定义并在此服务器中实现，但尚无法通过Cursor访问。我们希望在未来的Cursor版本中看到对这些附加功能的支持。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP