Task API Server - MCP TypeScript Implementation

任务 API 服务 - MCP TypeScript 实现

使用 TypeScript 编写的任务管理 API 的 Model Context Protocol（MCP）实现。本项目既是一个参考实现，也是一个功能完善的任务管理服务。

概述

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

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

该服务提供一套完整的任务管理操作、全面的验证和可靠的错误处理。

功能

• 任务管理操作：

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

• 双接口模式：

  • 支持 STDIO 协议，可与命令行和 AI Agent 集成
  • 支持 HTTP+SSE 协议，并提供 Web 界面，方便通过浏览器访问

• 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';

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

// Initialize client
const client = new Client(
  {
    name: "your-client-name",
    version: "1.0.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

// Connect to server
await client.connect(transport);

// Example: List all tasks
const listTasksResult = await client.callTool({
  name: "listTasks",
  arguments: {}
});

// Example: Create a new task
const createTaskResult = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete project documentation",
    category: "Documentation",
    priority: "high"
  }
});

// Clean up when done
await client.close();

HTTP 客户端

要从浏览器连接到 HTTP 服务：

<!DOCTYPE html>
<html>
<head>
  <title>Task Manager</title>
  <script type="module">
    import { Client } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/dist/esm/client/index.js';
    import { SSEClientTransport } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk/dist/esm/client/sse.js';

    document.addEventListener('DOMContentLoaded', async () => {
      // Create transport
      const transport = new SSEClientTransport('http://localhost:3000/mcp');
      
      // Initialize client
      const client = new Client(
        {
          name: "browser-client",
          version: "1.0.0"
        },
        {
          capabilities: {
            prompts: {},
            resources: {},
            tools: {}
          }
        }
      );

      // Connect to server
      await client.connect(transport);
      
      // Now you can use client.callTool() for tasks
    });
  </script>
</head>
<body>
  <h1>Task Manager</h1>
  
</body>
</html>

可用工具

listTasks

列出所有可用任务。

const result = await client.callTool({
  name: "listTasks",
  arguments: {
    // Optional filters
    status: "pending", // Filter by status
    category: "Work",  // Filter by category
    priority: "high"   // Filter by priority
  }
});

createTask

创建新任务。

const result = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete the project report",  // Required: task description
    category: "Work",                     // Optional: task category
    priority: "high"                      // Optional: low, medium, high
  }
});

updateTask

更新已有任务。

const result = await client.callTool({
  name: "updateTask",
  arguments: {
    taskId: 123,                       // Required: ID of task to update
    task: "Updated task description",  // Optional: new description
    status: "done",                    // Optional: pending, started, done
    category: "Personal",              // Optional: new category
    priority: "medium"                 // Optional: low, medium, high
  }
});

deleteTask

删除任务。

const result = await client.callTool({
  name: "deleteTask",
  arguments: {
    taskId: 123  // Required: ID of task to delete
  }
});

环境变量

变量	描述	默认值
TASK_MANAGER_API_BASE_URL	外部任务 API 的 URL	无（必填）
TASK_MANAGER_API_KEY	用于身份验证的 API 密钥	无（必填）
TASK_MANAGER_HTTP_PORT	HTTP 服务的端口	3000
PORT	备用端口名称（优先级更高）	无

项目结构

mcp-template-ts/
├── dist/               # Compiled JavaScript files
├── src/                # TypeScript source files
│   ├── index.ts        # STDIO server entry point
│   ├── http-server.ts  # HTTP+SSE server entry point
│   ├── test-client.ts  # Test client implementation
├── .env                # Environment variables
├── package.json        # Project dependencies
├── tsconfig.json       # TypeScript configuration
└── README.md           # Project documentation

开发

1. 以监视模式启动 TypeScript 编译器：

   npm run watch
   

2. 运行测试以验证更改：

   npm test
   

许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

致谢

• 本项目使用 @modelcontextprotocol/sdk 实现 MCP 协议
• 为与 AI 工具和 Web 应用集成而构建