MCP 服务器

Task API Server - MCP TypeScript Implementation

镜子 (jìng zi)

MCP-Mirror

开发者工具

访问服务器

README

任务 API 服务器 - MCP TypeScript 实现

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

概述

此 MCP 服务器连接到外部任务 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
```

创建一个包含您的 Task 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';

// 创建传输
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.0"
  },
  {
    capabilities: {
      prompts: {},
      resources: {},
      tools: {}
    }
  }
);

// 连接到服务器
await client.connect(transport);

// 示例：列出所有任务
const listTasksResult = await client.callTool({
  name: "listTasks",
  arguments: {}
});

// 示例：创建一个新任务
const createTaskResult = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete project documentation",
    category: "Documentation",
    priority: "high"
  }
});

// 完成后清理
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 () => {
      // 创建传输
      const transport = new SSEClientTransport('http://localhost:3000/mcp');
      
      // 初始化客户端
      const client = new Client(
        {
          name: "browser-client",
          version: "1.0.0"
        },
        {
          capabilities: {
            prompts: {},
            resources: {},
            tools: {}
          }
        }
      );

      // 连接到服务器
      await client.connect(transport);
      
      // 现在你可以使用 client.callTool() 来处理任务
    });
  </script>
</head>
<body>
  <h1>Task Manager</h1>
  <!-- 你的界面元素在这里 -->
</body>
</html>

可用工具

listTasks

列出所有可用任务。

const result = await client.callTool({
  name: "listTasks",
  arguments: {
    // 可选过滤器
    status: "pending", // 按状态过滤
    category: "Work",  // 按类别过滤
    priority: "high"   // 按优先级过滤
  }
});

createTask

创建一个新任务。

const result = await client.callTool({
  name: "createTask",
  arguments: {
    task: "Complete the project report",  // 必需：任务描述
    category: "Work",                     // 可选：任务类别
    priority: "high"                      // 可选：low, medium, high
  }
});

updateTask

更新现有任务。

const result = await client.callTool({
  name: "updateTask",
  arguments: {
    taskId: 123,                       // 必需：要更新的任务的 ID
    task: "Updated task description",  // 可选：新描述
    status: "done",                    // 可选：pending, started, done
    category: "Personal",              // 可选：新类别
    priority: "medium"                 // 可选：low, medium, high
  }
});

deleteTask

删除一个任务。

const result = await client.callTool({
  name: "deleteTask",
  arguments: {
    taskId: 123  // 必需：要删除的任务的 ID
  }
});

环境变量

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

项目结构

mcp-template-ts/
├── dist/               # 编译后的 JavaScript 文件
├── src/                # TypeScript 源文件
│   ├── index.ts        # STDIO 服务器入口点
│   ├── http-server.ts  # HTTP+SSE 服务器入口点
│   ├── test-client.ts  # 测试客户端实现
├── .env                # 环境变量
├── package.json        # 项目依赖项
├── tsconfig.json       # TypeScript 配置
└── README.md           # 项目文档