Generic MCP Server Template

🚀 通用 MCP 服务器模板

这是一个模块化、可扩展的模型上下文协议（MCP）服务器模板，能让你轻松对其进行定制和扩展，有效提升开发效率。

✨ 主要特性

• 模块化架构：实现了清晰的问题分离，具备明确的结构，便于开发与维护。
• 小型专注文件：更有利于维护，也更易于被 AI 获取相关信息。
• 简单的扩展点：提供了简单的模式，方便添加新工具和服务。
• 全面错误处理：在整个代码库中都有强大的错误管理机制。
• 类型安全：提供完整的 TypeScript 支持，并带有适当的类型定义。

📦 安装指南

先决条件

• 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

📚 详细文档

项目结构

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           # 项目文档

扩展模板

添加新服务

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 许可证。