任务 API 服务器 - MCP TypeScript 实现

一个用 TypeScript 编写的任务管理 API 的模型上下文协议 (MCP) 实现。该项目既可用作参考实现，也可用作功能性任务管理服务器。

概述

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

STDIO 模式：基于 CLI 的应用程序和 AI 代理的标准输入/输出通信
HTTP+SSE 模式：可通过 Web 访问的服务器，为浏览器和基于 HTTP 的客户端提供服务器发送事件

该服务器提供了一整套任务管理操作、广泛的验证和强大的错误处理。

特征

任务管理操作：
- 列出具有过滤功能的现有任务
- 创建具有可自定义属性的新任务
- 更新任务详细信息（描述、状态、类别、优先级）
- 完成或不再需要时删除任务
双接口模式：
- STDIO 协议支持命令行和 AI 代理集成
- HTTP+SSE 协议，带有 Web 界面，可基于浏览器访问
MCP 协议实现：
- 完整实现模型上下文协议
- 任务数据结构资源
- 任务操作工具
- 错误处理和信息消息
质量保证：
- 用于验证的综合测试客户端
- 测试完成后服务器自动关闭
- API 响应的详细验证

入门

先决条件

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

安装

克隆存储库：
git clone https://github.com/yourusername/mcp-template-ts.git cd mcp-template-ts
安装依赖项：
npm install
或者使用 pnpm：
pnpm install
使用您的任务 API 凭证创建一个.env文件：
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
构建项目：
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

这将：

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

使用 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>
  <!-- Your interface elements here -->
</body>
</html>

可用工具

列出任务

列出所有可用任务。

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

创建任务

创建新任务。

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

更新任务

更新现有任务。

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

删除任务

删除任务。

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

环境变量

多变的	描述	默认
任务管理器API基础URL	外部任务 API 的 URL	无（必填）
任务管理器API密钥	用于身份验证的 API 密钥	无（必填）
任务管理器HTTP端口	HTTP 服务器的端口	3000
港口	备用端口名称（优先）	没有任何

项目结构

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

发展

以监视模式启动 TypeScript 编译器：
npm run watch
运行测试来验证更改：
npm test

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

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

Task API Server

Integrations