MCP Server Template

🚀 MCP 服務器模板

MCP 服務器模板是一個用 TypeScript 編寫的模板，用於創建模型上下文協議（MCP）服務器。它為構建兼容 MCP 的服務器提供了堅實基礎，具備完整的工具支持、類型安全性和最佳實踐，能幫助開發者高效搭建服務器。

✨ 主要特性

• 🚀 全面支持 TypeScript，保障代碼類型安全。
• 🏗️ 基於容器的依賴注入，優化代碼結構。
• 📦 採用服務導向架構，帶有 DataProcessor 接口，提升可維護性。
• 🛠️ 提供示例工具實現及測試，方便開發者參考。
• 🧪 集成 Vitest 測試框架，便於進行單元測試。
• 📝 具備類型定義，增強代碼可讀性。
• 🔌 集成 MCP SDK，簡化與 MCP 的交互。

📦 安裝指南

安裝依賴

npm install

啟動帶有熱重載的開發服務器

npm run dev

構建項目

npm run build

運行測試

npm test

啟動生產服務器

npm start

📚 詳細文檔

項目結構

src/
├── index.ts          # 入口點
├── interfaces/       # 接口定義
│   └── tool.ts      # DataProcessor 接口
└── tools/           # 工具實現
    └── example.ts   # 示例工具

創建工具

導出工具和處理程序

按照 src/tools/example.ts 中的例子，在 your-tool.ts 中導出您的工具和處理程序：

// 在 your-tool.ts 中
export const YOUR_TOOLS = [
  {
    name: "your-tool-name",
    description: "Your tool description",
    parameters: {
      // 您的工具參數模式
    },
  },
];

export const YOUR_HANDLERS = {
  "your-tool-name": async (request) => {
    // 您的工具處理程序實現
    return {
      toolResult: {
        content: [{ type: "text", text: "Result" }],
      },
    };
  },
};

註冊工具

在 src/index.ts 中註冊您的工具：

// 在 src/index.ts 中
import { YOUR_TOOLS, YOUR_HANDLERS } from "./tools/your-tool.js";

// 合併所有工具
const ALL_TOOLS = [...EXAMPLE_TOOLS, ...YOUR_TOOLS];
const ALL_HANDLERS = { ...EXAMPLE_HANDLERS, ...YOUR_HANDLERS };

服務器將自動完成以下操作：

• 列出您的工具為可用工具之一。
• 處理輸入驗證。
• 處理針對您工具的請求。
• 根據 MCP 協議格式化響應。

測試

使用 TestClient

TestClient 提供了一種簡便的方式測試您的工具：

import { TestClient } from "./utils/TestClient";

describe("YourTool", () => {
  const client = new TestClient();

  it("should process data correctly", async () => {
    await client.assertToolCall(
      "your-tool-name",
      { input: "test" },
      (result) => {
        expect(result.toolResult.content).toBeDefined();
      }
    );
  });
});

使用 MCP Inspector

該模板包含 MCP Inspector 用於調試工具：

1. 啟動 inspector：

npx @modelcontextprotocol/inspector node dist/index.js

2. 在 http://localhost:5173 打開 inspector 的 UI。

Inspector 提供了以下功能：

• 可視化界面用於測試工具。
• 即時請求/響應監控。
• 工具元數據檢查。
• 交互式測試環境。

使用 Cursor 進行本地測試

要在 Cursor 中測試您的 MCP 服務器：

1. 構建並鏈接包：

npm run build
npm run link

2. 驗證二進制文件是否正常工作：

npx example-mcp-tool

3. 在 Cursor 中添加服務器：
   • 打開 Cursor 設置。
   • 導航到功能選項卡。
   • 滾動到底部的 MCP 服務器部分。
   • 點擊“添加服務器”。
   • 選擇“命令”類型。
   • 輸入一個名稱（例如，“本地示例工具”）。
   • 輸入命令：npx example-mcp-tool。
   • 點擊確認。
4. 在 Cursor 中檢查 MCP 服務器部分，確保您的服務器顯示為運行狀態。

注意：如果更改了代碼，請記得重新構建並重新鏈接：

npm run build
npm run link

當不再需要時，可以卸載包：

npm uninstall example-mcp-tool
rm -rf ~/.node_modules_bins/example-mcp-link

更新日誌

v1.0.0

• 初始版本發佈