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();
   }
   

许可证

本项目遵循 MIT 许可证，具体内容如下：

版权所有 (c) 2023 你的姓名/公司名。
本软件以源代码形式分发，任何人可以自由使用、复制、修改和分发，但需遵守以下条件：

• 在分发的衍生作品中必须保留版权声明和许可声明。

附录

常见问题解答

1. 如何更改端口？

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

2. 如何禁用日志？

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

贡献指南

欢迎贡献！请 fork 本仓库并在 gh-pages 分支中提交您的更改。

通过以上步骤，您可以轻松上手 MCP TypeScript 项目，并根据需求扩展和优化功能。