通用 MCP 服务器模板

一个模块化、可扩展的模型上下文协议 (MCP) 服务器模板，设计用于轻松定制和扩展。

特性

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

项目结构

generic-mcp-template/
├── src/
│   ├── services/       # Service classes for API interactions
│   │   ├── base-service.ts        # Abstract base service with common functionality
│   │   └── example-service.ts     # Example service implementation
│   ├── tools/          # MCP tool definitions and handlers
│   │   ├── example-tools.ts       # Tool definitions (name, description, schema)
│   │   └── example-tool-handlers.ts # Tool handler implementations
│   ├── types/          # TypeScript type definitions
│   │   └── example-types.ts       # Example type definitions
│   ├── config.ts       # Configuration management
│   └── index.ts        # Main entry point
├── .env.example        # Example environment variables
├── package.json        # Project dependencies and scripts
├── tsconfig.json       # TypeScript configuration
└── README.md           # Project documentation

入门指南

前提条件

• 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