Stevennevins MCP Server Template

🚀 MCP 服務器模板

本項目是一個用於創建 Model Context Protocol (MCP) 服務器的 TypeScript 模板。它為構建兼容 MCP 的服務器提供了堅實基礎，具備完整的工具支持、類型安全和最佳實踐，能幫助開發者更高效地搭建服務器。

✨ 主要特性

• 🚀 完全支持 TypeScript，保障代碼類型安全。
• 🏗️ 基於容器的依賴注入，提升代碼可維護性。
• 📦 採用服務導向架構，帶有 DataProcessor 接口，便於功能擴展。
• 🛠️ 提供工具實現示例及測試，方便開發者參考。
• 🧪 集成 Vitest 測試框架，可對代碼進行全面測試。
• 📝 包含類型定義文件，增強代碼可讀性。
• 🔌 整合 MCP SDK，與 MCP 協議無縫對接。

🚀 快速開始

開發步驟

1. 安裝依賴：

npm install

2. 啟動開發服務器（帶熱重載）：

npm run dev

3. 構建項目：

npm run build

4. 運行測試：

npm test

5. 啟動生產服務器：

npm start

📦 安裝指南

按照上述快速開始中的開發步驟，依次執行命令即可完成項目的安裝與啟動。

💻 使用示例

基礎用法

項目結構

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

創建工具

1. 按照 src/tools/example.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" }],
      },
    };
  },
};

2. 在 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 用於本地測試和 MCP Inspector 用於可視化調試。

使用 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. 打開 inspector UI 界面：http://localhost:5173 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

📚 詳細文檔

注意事項

⚠️ 重要提示

• 確保所有依賴項已正確安裝。
• 在生產環境中使用前，請進行充分的測試。
• 查看 MCP 文檔以獲取更多信息。