MCP Typescript Server Starter

🚀 MCP TypeScript 項目指南

MCP（可能指“Multi-Chat Protocol”或其他特定縮寫）是一個基於 TypeScript 的服務器框架，用於構建和管理複雜的聊天或通信系統。本指南將詳細介紹如何使用該框架實現一個功能完善的服務器。

🚀 快速開始

初始化項目

1. 創建新項目

   mkdir my-mcp-server && cd my-mcp-server
   

2. 安裝依賴

   npm init -y
   npm install mcp-server typescript --save-dev
   

3. 配置 TypeScript 在 tsconfig.json 中添加以下內容：

   {
     "compilerOptions": {
       "target": "ES2020",
       "module": "CommonJS",
       "outDir": "./dist",
       "rootDir": "./src",
       "strict": true,
       "esModuleInterop": true,
       "skipLibCheck": true
     }
   }
   

4. 編寫主文件 在 src/index.ts 中添加以下內容：

   import { MCPServer } from 'mcp-server';
   
   const server = new MCPServer({
     port: 3001,
     hostname: 'localhost',
   });
   
   // 註冊工具、資源和提示（見下文）
   server.start();
   

5. 運行項目

   npm run dev
   

✨ 主要特性

工具定義

在 src/index.ts 中，可以通過以下方式註冊一個簡單的回顯工具：

server.tool("echo", { message: z.string() }, async ({ message }) => ({
  content: [{ type: "text", text: `Tool echo: ${message}` }],
}));

資源定義

可以使用以下代碼實現基於 URI 的資源訪問：

server.resource(
  "echo",
  new ResourceTemplate("echo://{message}", { list: undefined }),
  async (uri, { message }) => ({
    contents: [
      {
        uri: uri.href,
        text: `Resource echo: ${message}`,
      },
    ],
  })
);

提示定義

在 src/index.ts 中，可以註冊一個提示模板：

server.prompt("echo", { message: z.string() }, ({ message }) => ({
  messages: [
    {
      role: "user",
      content: {
        type: "text",
        text: `Please process this message: ${message}`,
      },
    },
  ],
}));

📚 詳細文檔

服務器配置

端點和接口

• 默認端口：3001
• 默認主機名：localhost
• 監聽地址：0.0.0.0（允許外部訪問）

日誌和調試

通過以下方式啟用日誌記錄：

server.configure({
  logging: {
    enabled: true,
    level: 'debug',
  },
});

部署與擴展

使用 Docker 進行部署

1. 創建 Dockerfile

   FROM node:16
   
   WORKDIR /app
   
   COPY package.json ./
   RUN npm install
   
   COPY src/ ./src/
   
   EXPOSE 3001
   
   CMD ["npm", "run", "start"]
   

2. 構建鏡像

   docker build -t mcp-server .
   

3. 運行容器

   docker run -p 3001:3001 --name mcp-server mcp-server
   

環境變量

配置環境變量

在 src/index.ts 中，可以使用以下方式讀取環境變量：

const port = process.env.PORT || 3001;

示例配置文件

創建一個 .env 文件：

PORT=3001
NODE_ENV=development

調試信息

輸出調試日誌

在 src/index.ts 中，可以添加以下代碼以輸出調試信息：

server.on('debug', (message) => {
  console.log(`Debug: ${message}`);
});

捕獲錯誤

使用以下方式捕獲和處理錯誤：

server.on('error', (error) => {
  console.error(`Error: ${error.message}`);
});

最佳實踐

代碼結構

• 模塊化：將功能拆分成多個文件，例如 tools/, resources/, 和 prompts/。
• 依賴管理：使用 package.json 管理所有依賴項。
• 版本控制：使用 git 進行版本控制。

性能優化

1. 緩存：

   const cache = new Map();
   

2. 異步操作：

   async function handleRequest() {
     await someAsyncFunction();
   }
   

附錄

常見問題解答

1. 如何更改端口？

   server.configure({
     port: 3002,
   });
   

2. 如何禁用日誌？

   server.configure({
     logging: {
       enabled: false,
     },
   });
   

貢獻指南

歡迎貢獻！請 fork 本倉庫並在 gh-pages 分支中提交您的更改。

📄 許可證

本項目遵循 MIT 許可證，具體內容如下：

版權所有 (c) 2023 你的姓名/公司名。
本軟件以源代碼形式分發，任何人可以自由使用、複製、修改和分發，但需遵守以下條件：

• 在分發的衍生作品中必須保留版權聲明和許可聲明。

通過以上步驟，您可以輕鬆上手 MCP TypeScript 項目，並根據需求擴展和優化功能。