MCP Server Implementation in TypeScript

TypeScript 中的 MCP 服务实现

这是一个 Model Context Protocol（MCP）服务的 TypeScript 实现。该服务提供一组工具，用于与数据库交互和执行网络搜索。

功能

• MCP 协议实现
• SQLite 数据库集成
• 网络搜索功能
• RESTful API 端点
• 使用 Swagger UI 的交互式 API 文档
• CORS 支持
• 会话管理
• 用于实时更新的服务器发送事件（SSE）

前提条件

• Node.js（v14 或更高版本）
• npm（v6 或更高版本）

安装

1. 克隆仓库：

git clone https://github.com/yourusername/mcp-typescript-workshop.git
cd mcp-typescript-workshop

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

运行服务

开发模式

npm run dev

生产模式

npm start

服务默认在端口 3000 上启动。你可以访问：

• API 文档：http://localhost:3000/api-docs
• MCP 端点：http://localhost:3000/mcp

测试服务

你可以使用 curl 命令测试服务。以下是测试所有功能的完整步骤：

1. 初始化新会话：

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

这将返回一个会话 ID，后续请求需要用到它。

2. 列出可用工具：

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"list_tools","params":{},"id":2}'

3. 获取所有员工：

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"get_employees","arguments":{}},"id":3}'

4. 按部门搜索员工：

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"search_employees","arguments":{"department":"Engineering"}},"id":4}'

5. 执行网络搜索：

curl -v -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"call_tool","params":{"name":"web_search","arguments":{"query":"Model Context Protocol"}},"id":5}'

6. 终止会话：

curl -v -X DELETE http://localhost:3000/mcp \
  -H "mcp-session-id: YOUR_SESSION_ID"

注意：将 YOUR_SESSION_ID 替换为初始化请求返回的会话 ID。

预期响应

1. 初始化响应：

{
  "jsonrpc": "2.0",
  "result": {
    "sessionId": "e6c389d7-e90a-4d09-a916-47bc5edd365e",
    "serverInfo": {
      "name": "workshop-typescript-server",
      "version": "1.0.0"
    }
  },
  "id": 1
}

2. 获取员工响应：

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "Employees:\nID: 1, Name: Alice Johnson, Department: Engineering, Salary: $85000\nID: 2, Name: Bob Smith, Department: Marketing, Salary: $62000\nID: 3, Name: Carol Davis, Department: Engineering, Salary: $92000\nID: 4, Name: David Wilson, Department: Sales, Salary: $58000\n"
    }]
  },
  "id": 3
}

API 文档

服务运行时，可通过 http://localhost:3000/api-docs 查看 API 文档。文档包括：

• 所有可用端点
• 请求/响应架构
• 交互式测试界面
• 请求和响应示例

可用端点

POST /mcp

MCP 通信的主端点，负责处理：

• 会话初始化
• 工具列表
• 工具执行

GET /mcp

用于实时更新的服务器发送事件（SSE）端点。

DELETE /mcp

用于终止 MCP 会话的端点。

可用工具

1. get_employees

   • 描述：从数据库获取所有员工
   • 无需输入参数

2. web_search

   • 描述：搜索网络信息
   • 输入参数：
     • query（字符串）：搜索查询

3. search_employees

   • 描述：按部门或姓名搜索员工
   • 输入参数：
     • department（字符串，可选）：要搜索的部门
     • name（字符串，可选）：要搜索的姓名

会话管理

服务使用会话 ID 在请求之间保持状态。会话 ID：

• 在初始化期间生成
• 后续请求需要在 mcp-session-id 标头中提供
• 会话终止时自动清理

错误处理

服务会按照以下格式返回详细的错误响应：

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description"
  },
  "id": null
}

开发

项目结构

src/
  ├── server.ts      # Main server implementation
  ├── swagger.ts     # API documentation configuration
  └── types/         # TypeScript type definitions

构建

npm run build

测试

npm test

许可证

本项目采用 ISC 许可证授权，详情请参阅 LICENSE 文件。

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request