Task API Server - MCP TypeScript 实现

这是一个用TypeScript编写的任务管理API的Model Context Protocol (MCP)实现。该项目既是一个参考实现，也是一个功能齐全的任务管理服务器。

概述

此MCP服务器连接到外部的任务API服务，并提供一个标准化的任务管理接口。它支持两种运行模式：

1. STDIO模式：用于基于CLI的应用程序和AI代理的标准输入/输出通信。
2. HTTP+SSE模式：带有Server-Sent Events的Web可访问服务器，适用于浏览器和基于HTTP的客户端。

该服务器提供了完整的任务管理操作集、广泛的验证以及强大的错误处理机制。

特性

• 任务管理操作：

  • 列出现有任务并具有过滤能力
  • 创建具有自定义属性的新任务
  • 更新任务详情（描述、状态、类别、优先级）
  • 删除已完成或不再需要的任务

• 双接口模式：

  • 支持命令行和AI代理集成的STDIO协议
  • 带有Web界面的HTTP+SSE协议，用于浏览器访问

• MCP协议实现：

  • 完整实现了Model Context Protocol
  • 提供任务数据结构资源
  • 提供任务操作工具
  • 错误处理及信息提示

• 质量保证：

  • 全面测试客户端进行验证
  • 测试完成后自动关闭服务器
  • 对API响应进行详细的验证

快速开始

预备条件

• Node.js 16.x 或更高版本
• npm 或 pnpm 包管理器

安装

1. 克隆仓库：

   git clone https://github.com/yourusername/mcp-template-ts.git
   cd mcp-template-ts
   

2. 安装依赖：

   npm install
   

   或使用pnpm：

   pnpm install
   

3. 创建一个.env文件，包含您的任务API凭证：

   TASK_MANAGER_API_BASE_URL=https://your-task-api-url.com/api
   TASK_MANAGER_API_KEY=your_api_key_here
   TASK_MANAGER_HTTP_PORT=3000
   

4. 构建项目：

   npm run build
   

运行服务器

STDIO模式（用于CLI/AI集成）

npm start

或

node dist/index.js

HTTP模式（用于Web访问）

npm run start:http

或

node dist/http-server.js

默认情况下，HTTP服务器在3000端口运行。您可以通过设置TASK_MANAGER_HTTP_PORT环境变量来更改此端口。

测试

运行全面的测试套件以验证功能：

npm test

这将：

1. 构建项目
2. 启动一个服务器实例
3. 将测试客户端连接到服务器
4. 运行所有任务操作
5. 验证正确的响应
6. 自动关闭服务器

使用MCP客户端

STDIO客户端

要从您的应用程序连接到STDIO服务器：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import * as path from 'path';

// 创建传输
const transport = new StdioClientTransport({
  command: 'node',
  args: [path.resolve('path/to/dist/index.js')]
});

// 初始化客户端
const client = new Client(
  {
    name: "your-client-name",
    version: "1.0.