MCP Chat with Claude

使用 Claude 进行 MCP 聊天

一个全栈应用，演示模型上下文协议（MCP）与 Anthropic 的 Claude 大模型集成，并提供一个可使用 MCP 工具的交互式聊天界面。

项目概述

本项目由三个主要组件构成：

1. 多个 MCP 服务：实现模型上下文协议的 Node.js 服务，为大模型提供各种专用工具。
2. 宿主应用：一个 Express 服务，作为用户、Claude AI 和 MCP 服务之间的中介。
3. Web 客户端：一个基于浏览器的聊天界面，与宿主应用通信。

功能

• 与 Claude AI 进行交互式聊天
• 双面板 UI，显示对话和工具执行详情
• 从多个 MCP 服务动态发现工具
• 支持来自各服务、参数各异的专用工具
• 通过 MCP 正确处理 Claude 的工具调用

项目结构

├── client/                 # Host app & web client
│   ├── dist/               # Compiled TypeScript
│   ├── host-app.ts         # Host application server
│   ├── chat.js             # Frontend chat interface logic
│   ├── index.html          # Main web interface
│   ├── styles.css          # Styling for web interface
│   ├── package.json        # Client dependencies
│   └── mcp-client-example.ts # Example MCP client for testing
│
├── server/                 # MCP servers
│   ├── dist/               # Compiled TypeScript
│   ├── mcp-server-todoplan.ts # TodoPlan MCP server implementation
│   ├── mcp-server-project.ts  # Project MCP server implementation
│   └── package.json        # Server dependencies
│
├── .gitignore              # Git ignore file
└── README.md               # Project documentation

前置条件

• Node.js 17 或更高版本
• npm 或 yarn
• Anthropic API 密钥

安装

1. 克隆仓库：

   git clone https://github.com/jiangyan/typescript-mcp-demo.git
   cd typescript-mcp-demo
   

2. 为客户端和服务端安装依赖：

   cd server
   npm install
   cd ../client
   npm install
   

3. 在客户端目录中创建 .env 文件，并填入你的 Anthropic API 密钥：

   ANTHROPIC_API_KEY=your-api-key-here
   MCP_SERVER_TODOPLAN_URL=http://localhost:8000/sse
   MCP_SERVER_PROJECT_URL=http://localhost:8001/sse
   PORT=3000
   

4. 在服务端目录中创建 .env 文件：

   MCP_SERVER_TODOPLAN_PORT=8000
   MCP_SERVER_PROJECT_PORT=8001
   

设置和运行

第 1 步：启动 MCP 服务

# Terminal 1: Start the TodoPlan MCP server
cd server
npm run build:todoplan
npm run start:todoplan

# Terminal 2: Start the Project MCP server
cd server
npm run build:project
npm run start:project

TodoPlan MCP 服务默认在端口 8000 启动，Project MCP 服务默认在端口 8001 启动。

第 2 步：启动宿主应用（Web 服务）

cd client
npm run build
npm start

Web 服务默认在端口 3000 启动。

第 3 步：访问聊天界面

打开浏览器并访问：

http://localhost:3000

可用的 MCP 工具

MCP 服务提供以下 Claude 可使用的工具：

1. todoplan-server_get-todo：获取指定类别的待办事项

   • 参数：
     • category：字符串（例如，“life”、“work”、“family”、“friends”）

2. todoplan-server_get-plan：获取总体计划

   • 参数：无

3. project-server_get-project-details：获取指定项目的详情

   • 参数：
     • project_name：字符串（例如，“Earth”、“Mars”、“Jupiter”、“Saturn”）

其他示例

本项目包含一个独立的 MCP 客户端示例（mcp-client-example.ts），演示如何在不使用 Web 界面的情况下，通过编程方式连接到 MCP 服务。

运行此示例：

cd client
npm run client

开发

MCP 服务开发

向 MCP 服务添加新工具：

1. 打开服务文件（例如，server/mcp-server-todoplan.ts）
2. 按照现有模式添加新的工具定义：

   server.tool("tool-name",
     { param1: z.string() },
     async ({ param1 }) => {
       // Tool implementation
       return {
         content: [{ type: "text", text: "Result" }]
       };
     }
   );
   

3. 重新构建并重启服务

宿主应用开发

宿主应用由以下部分构成：

• 后端（host-app.ts）：与 Claude 和多个 MCP 服务通信的 Express 服务
• 前端（chat.js、index.html、styles.css）：与后端通信的聊天界面

架构

┌─────────────┐       ┌────────────────┐       ┌───────────────┐
│             │       │                │       │               │
│  Web UI     │◄─────►│  Host App      │◄─────►│  MCP Servers  │
│  (Browser)  │       │  (Express)     │       │  (Node.js)    │
│             │       │                │       │               │
└─────────────┘       └───────┬────────┘       └───────────────┘
                              │
                              ▼
                      ┌───────────────┐
                      │               │
                      │  Claude API   │
                      │  (Anthropic)  │
                      │               │
                      └───────────────┘

多个 MCP 服务的实现

本项目采用多服务 MCP 架构，使 Claude 能够访问来自不同专用服务的工具。

服务配置

本项目包含两个不同的 MCP 服务：

1. TodoPlan MCP 服务（server/mcp-server-todoplan.ts）：提供用于管理待办事项和计划的工具

   • get-todo：获取指定类别的待办事项
   • get-plan：获取总体计划

2. Project MCP 服务（server/mcp-server-project.ts）：提供用于访问信息的工具

   • get-project-details：获取指定项目的详情

宿主应用集成

宿主应用（client/host-app.ts）的实现支持：

1. 同时连接到多个 MCP 服务
2. 使用下划线在工具名称前添加所属服务名称，以避免冲突（例如，todoplan-server_get-todo）
3. 根据前缀将工具调用路由到相应的服务
4. 向大模型提供统一的工具集

示例查询

尝试以下查询，测试多个服务器的集成：

• “告诉我关于项目 Earth 的信息”
• “工作类别中我的待办事项是什么？”
• “查找我工作类别中的待办事项，并告诉我与之相关的项目”
• “我的计划是什么？”

故障排除

1. 连接问题：确保两个 MCP 服务和主机应用都在运行，并检查控制台是否有错误消息。

2. 未找到工具：确保 MCP 服务正在运行，并且工具名称完全匹配。

3. API 密钥错误：确认客户端的 .env 文件中已正确设置 Anthropic API 密钥。

4. 工具使用错误：查看响应面板，获取详细的错误信息。

5. 工具名称格式无效：确保工具名称遵循 Anthropic 要求的格式（仅包含字母数字字符、下划线和连字符）。

许可证

MIT

致谢

• Model Context Protocol
• Anthropic Claude API