通用MCP服务器模板

这是一个模块化、可扩展的模型上下文协议（MCP）服务器模板，旨在方便定制和扩展。

特性

• 模块化架构：清晰的责任分离和良好的结构定义
• 小型、专注的文件：更好的可维护性和更易于AI处理
• 简单的扩展点：添加新工具和服务的简单模式
• 全面的错误处理：代码库中的强大错误管理
• 类型安全：完整的TypeScript支持和适当的类型定义

项目结构

generic-mcp-template/
├── src/
│   ├── services/       # 用于API交互的服务类
│   │   ├── base-service.ts        # 具有通用功能的抽象基础服务
│   │   └── example-service.ts     # 示例服务实现
│   ├── tools/          # MCP工具定义和处理器
│   │   ├── example-tools.ts       # 工具定义（名称、描述、模式）
│   │   └── example-tool-handlers.ts # 工具处理器实现
│   ├── types/          # TypeScript类型定义
│   │   └── example-types.ts       # 示例类型定义
│   ├── config.ts       # 配置管理
│   └── index.ts        # 主入口点
├── .env.example        # 环境变量示例
├── package.json        # 项目依赖和脚本
├── tsconfig.json       # TypeScript配置
└── README.md           # 项目文档

开始使用

前提条件

• Node.js 18或更高版本
• npm 或 yarn

安装

1. 克隆此仓库：

   git clone https://github.com/v4lheru/generic-mcp-template.git
   cd generic-mcp-template
   

2. 安装依赖项：

   npm install
   

3. 根据 .env.example 创建一个 .env 文件：

   cp .env.example .env
   

4. 使用您的API密钥和配置编辑 .env 文件。

构建和运行

1. 构建项目：

   npm run build
   

2. 运行服务器：

   npm start
   

扩展模板

添加新服务

1. 在 src/services/ 中创建一个新的服务文件：

   // src/services/my-service.ts
   import { BaseService } from './base-service.js';
   import config from '../config.js';
   
   export class MyService extends BaseService {
       // 实现您的服务...
   }
   

2. 在 src/types/ 中添加任何必要的类型。

添加新工具

1. 在 src/tools/ 中定义您的工具或扩展现有文件：

   // src/tools/my-tools.ts
   export const myTools = [
       {
           name: "my_tool",
           description: "我的工具描述",
           inputSchema: {
               // 工具输入的JSON模式
           }
       }
   ];
   

2. 实现您的工具处理器：

   // src/tools/my-tool-handlers.ts
   import { MyService } from '../services/my-service.js';
   
   export function createMyToolHandlers(myService: MyService) {
       return {
           my_tool: async (args: any) => {
               // 实现您的工具处理器
           }
       };
   }
   

3. 在 src/index.ts 中注册您的工具和处理器。

配置

该模板在 src/config.ts 中使用集中式的配置系统。配置可以通过以下方式提供：

• 环境变量
• 命令行参数（使用 --env KEY=VALUE）
• 代码中的默认值

错误处理

该模板包括全面的错误处理：

• 支持速率限制的服务级错误处理
• 具有适当错误消息的工具级错误处理
• MCP协议错误处理

许可证

MIT