AI导哈

MCP协议服务器

一个基于Model Context Protocol (MCP)的服务器，用于定义工具、处理输入验证和格式化响应，支持业务逻辑和API编排。

  • by arthursmuller
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 arthursmuller/mcp-template

使用说明

示例mcp项目名称mcp服务器

这是一个 模型上下文协议（MCP） 服务器。..

特性

  • 示例_工具：此处为工具说明。

1.建筑层次

您必须尊重项目结构中定义的关注点分离。这些界限是 通过ESLint严格执行:

  • 入口点(index.ts)：初始化服务器，连接传输，并处理主进程循环。

  • MCP层(src/mcp/)：处理工具定义、输入验证（Zod）和响应格式。

    • src/mcp/tools.ts：将工具输入映射到域函数的注册表。
    • 边界：无法直接从导入 src/api、域客户端或域实用程序。它必须访问功能 仅 通过域服务。
    • src/mcp/utils/：有助于标准化响应(toolSuccessResponse, toolErrorResponse)以及包装功能。

  • 域层(src/domain/)：包含业务逻辑和API编排。

    • 边界：该层受到保护；它 不能 从进口 src/mcp 层。
    • src/domain/**/services/：逻辑所在的主要服务类。
    • 边界：服务不能直接从导入 src/api。他们必须通过域客户端访问外部数据。
    • src/domain/dtos/：TypeScript接口定义了流入和流出服务的数据的形状。

  • 基础设施层(src/api/):

    • src/api/client.ts：一个围绕axios的包装器，用于向外部API发出HTTP请求。

  • 配置(src/env.ts):

    • 集中式环境变量管理。 永远不要硬编码机密或URL；在这里添加它们。

  • 工具说明(src/tools.metadata.ts):

    • 集中式工具文本描述。

2.安装和初始化

先决条件

  • Node.js （v18或更高版本）
  • npm
  • （身份验证要求、运行所需的工具等）

设置步骤

  1. 安装依赖项：

    npm install

  2. 初始化项目： 运行启动脚本重命名项目，配置域，并设置初始工具结构。此脚本有效地“解析”了特定用例的代码。

    npm run scaffold:startup

    按照交互式提示设置项目名称、域名、服务方法和工具名称。

  3. 构建项目：

    npm run build

  4. 运行项目：

    npm run start

3.开发工作流程

CLI生成器（推荐）

此模板包括交互式CLI脚本，用于自动化日常任务并确保架构一致性。在终端中运行这些命令并按照提示操作：

  • npm run scaffold:domain
    • 创建新的域模块结构（客户端、服务、DTO的文件夹）。
    • 在添加不同功能区域时使用此功能（例如。， weather, user-management).
  • npm run scaffold:service
    • 将新的业务逻辑服务类添加到现有域中。
  • npm run scaffold:client
    • 在域内生成HTTP或数据库客户端包装器。
    • 确保一致的错误处理和连接注入。
  • npm run scaffold:tool
    • 自动化整个“添加新工具”过程。
    • 它提示使用域/服务，生成DTO，将方法注入service类，更新 tools.metadata.ts，并在中注册该工具 src/mcp/tools.ts.

如何添加新工具

要向此服务器添加新功能，请遵循以下5个步骤以保持一致性：

  1. 定义元数据： 将工具的名称和描述添加到 src/tools.metadata.ts。使用常量键作为工具名称。

  2. 创建DTO： 在中定义请求参数和预期响应形状 src/domain/dtos/.

  3. 实施业务逻辑：

    • 向中添加新方法 DomainService 类在 src/domain/service.ts.
    • 使用 HttpClient 提出请求。
    • 确保该方法返回 Promise 结果DTO或 null 失败。

  4. 注册工具和架构： 更新 src/mcp/tools.ts:

    • 导入元数据和服务。
    • 定义 inputSchema 使用 zod.
    • 使用包装服务回调 buildTool(DomainService.yourMethod)。此包装器自动处理JSON格式的成功/错误。

  5. 启用工具： 将工具定义添加到 TOOLS_ENABLED 数组in src/env.ts这允许通过环境变量切换工具（例如。， process.env.EXAMPLE_TOOL === "false").

如何修改API客户端

如果身份验证或基本URL需要更改：

  1. 更新 src/env.ts 解析新的环境变量。
  2. 更新 src/domain/utils/api.ts 如果需要动态注入自定义头（如API键）。

4.编码标准和惯例

  • 错误处理：
    • 领域层：捕获错误，记录并返回 null 或者抛出可管理的错误。
    • MCP层：依靠 newTool 包装。它捕获异常并将其转换为标准 toolErrorResponse 格式。
  • 类型安全：
    • 对于所有API交互，严格使用TypeScript接口/类型(src/domain/dtos/).
    • 不要使用 any 除非绝对必要（例如在通用HTTP客户端包装器内）。
  • 格式：
    • 工具输出始终是文本块内的JSON字符串： content: [{ type: "text", text: JSON.stringify(...) }]。这由以下人员处理 toolSuccessResponse.ts.

5.测试

  • 同一地点：测试文件(*.test.ts)必须立即驻留在它们正在测试的源文件旁边（例如。， src/domain/service.ts -> src/domain/service.test.ts).这使测试可见且易于维护。
  • 助手目录：The tests/ 该目录严格保留用于辅助方法、模拟和全局测试配置。应该 不 包含实际的测试套件或规范文件。

用法

认证步骤

解释如何获取身份验证并将其配置为运行mcp工具。

配置VS代码

  1. 打开MCP配置文件:
    • 全局（用户级）:
      • 在Windows上，按 Win+R，粘贴 %APPDATA%\Code\User\mcp.json，然后按Enter键。
      • 或者，在VS Code Copilot Chat中，单击工具/附件图标（在提示输入的底部菜单中），将鼠标悬停在任何MCP服务器上，然后单击齿轮图标。
    • 工作空间级别:
      • 创建 .vscode 如果项目根目录中不存在该文件夹。
      • 在其中，创建一个名为 mcp.json.
      • 添加以下json结构以添加配置：
{
   "settings": {
      // paste the example-mcp-proj-name config here
   }
}
  1. 在服务器下，添加:
"example-mcp-proj-name": {
  "command": "node",
  "args": [
    "{yourFullLocalPathToProject}\\{example-mcp-proj-name}\\dist\\index.js"
  ],
  "env": {
    "API_URL": "PLACEHOLDER",
    "EXAMPLE_TOOL": "true",
  }
}

备注：具体说明

相关 MCP