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 許可證。