MCP Server

🚀 MCP 服務器

這是一個統一的 MCP（模型上下文協議）服務器，支持可插拔工具。每個工具都有獨立的端點，允許客戶端選擇性地添加特定工具。

中文文檔

✨ 主要特性

• 帶路徑路由的統一端點：每個工具都有自己的 MCP 端點 (/mcp/{toolName})
• 松耦合工具：工具從 src/tools/ 目錄獨立加載
• 故障隔離：單個工具故障不會影響其他工具（超時保護 + 錯誤處理）
• 可流式傳輸的 HTTP 傳輸協議：現代 MCP 傳輸協議
• Bearer 令牌認證：安全的 API 訪問
• 支持 Docker：可進行容器化部署

📦 項目結構

mcp_server/
├── src/
│   ├── index.ts                    # 入口點
│   ├── core/
│   │   ├── tool-registry.ts        # 工具註冊表
│   │   ├── tool-loader.ts          # 動態工具加載器
│   │   └── tool-executor.ts        # 隔離執行器（超時 + 錯誤處理）
│   ├── server/
│   │   ├── app.ts                  # Express + 可流式傳輸的 HTTP
│   │   └── mcp-server.ts           # MCP 服務器實例
│   ├── middleware/
│   │   └── auth.ts                 # Bearer 令牌認證
│   ├── tools/                      # 松耦合工具目錄
│   │   ├── calculator/index.ts     # 計算器工具（加/減/乘/除）
│   │   ├── echo/index.ts           # 回顯工具（回顯/反轉/信息）
│   │   └── time/index.ts           # 時間工具（獲取當前時間/轉換時間/格式化時間）
│   ├── types/mcp.ts                # 類型定義
│   └── utils/logger.ts             # 終端日誌記錄器
├── Dockerfile                      # 多階段構建
├── docker-compose.yml
├── package.json
└── tsconfig.json

🚀 快速開始

本地開發

# 安裝依賴
npm install

# 創建 .env 文件
echo "AUTHORIZATION_KEY=your-secret-key" > .env

# 啟動開發服務器
npm run dev

Docker 部署

# 使用 docker-compose 構建並運行
docker-compose up -d --build

# 或者手動構建
docker build -t mcp-server .
docker run -e AUTHORIZATION_KEY=your-secret-key -p 3000:3000 mcp-server

📚 詳細文檔

API 端點

可用工具

計算器 (/mcp/calculator)

支持各種運算符和函數的數學表達式求值器。

支持的運算符：

• 算術運算符：+, -, *, /
• 整除運算符：//
• 取模運算符：%
• 冪運算符：** 或 ^

支持的常量： pi, e

支持的函數： sin, cos, tan, sqrt, abs, log, log10, exp, floor, ceil, round, pow, min, max

示例：

2 + 3 * 4        → 14
(2 + 3) * 4      → 20
2^10             → 1024
sqrt(16)         → 4
2 * pi           → 6.283...
sin(0)           → 0
pow(2, 8)        → 256
17 // 5          → 3
17 % 5           → 2

回顯 (/mcp/echo)

用於測試和調試的回顯工具。

時間 (/mcp/time)

用於時區轉換和格式化的時間工具。

客戶端配置

Claude 桌面版

編輯 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "calculator": {
      "url": "http://localhost:3000/mcp/calculator",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    },
    "time": {
      "url": "http://localhost:3000/mcp/time",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

Cursor / VS Code

在項目根目錄下創建 .cursor/mcp.json：

{
  "mcpServers": {
    "calculator": {
      "url": "http://localhost:3000/mcp/calculator",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

編程式使用（Node.js）

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({
  name: "my-client",
  version: "1.0.0",
});

const transport = new StreamableHTTPClientTransport(
  new URL("http://localhost:3000/mcp/calculator"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer your-secret-key",
      },
    },
  }
);

await client.connect(transport);

// 列出可用工具
const tools = await client.listTools();
console.log(tools);

// 調用工具
const result = await client.callTool({
  name: "add",
  arguments: { a: 10, b: 5 },
});
console.log(result);

添加新工具

1. 在 src/tools/ 下創建新目錄：

src/tools/my-tool/
└── index.ts

2. 實現 MCPTool 接口：

import { z } from "zod";
import { MCPTool, MCPMethodDefinition } from "../../types/mcp.js";

const myTool: MCPTool = {
  name: "my-tool",
  description: "Description of my tool",
  version: "1.0.0",

  getMethods(): MCPMethodDefinition[] {
    return [
      {
        name: "my-method",
        description: "Description of my method",
        inputSchema: {
          param1: z.string().describe("Parameter description"),
        },
        handler: async (params) => {
          const { param1 } = params as { param1: string };
          return { result: param1 };
        },
      },
    ];
  },

  async initialize() {
    // 初始化邏輯
  },

  async healthCheck() {
    return true;
  },
};

export default myTool;

3. 工具將在服務器啟動時自動加載。

腳本

npm run dev        # 啟動帶有熱重載的開發服務器
npm run build      # 為生產環境構建
npm start          # 啟動生產服務器
npm test           # 運行測試
npm run lint       # 檢查代碼風格
npm run lint:fix   # 自動修復代碼風格問題

📄 許可證

MIT