Things Cloud MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • Things Cloud MCP 是一个基于 MCP 的服务器端实现，连接 Things Cloud API，向 LLM 客户端提供标准化的上下文服务。核心能力包括托管和管理资源（如任务、区域、标签、项目等）、注册并执行工具（Tools）、以及渲染/返回 Prompt 模板，所有通信通过 JSON-RPC 进行。服务器支持多用户、OAuth 2.1 验证以及流式传输，目标是在 AI 助手与 Things Cloud 之间建立稳定、安全、可扩展的上下文服务。

• 主要功能点

  • MCP 核心能力：资源（Tasks/Projects/Areas/Tags 等）、工具（Tools）与 Prompts 的管理、执行与渲染
  • 多用户支持：基于内置 OAuth 2.1 + Basic 认证的多账户场景
  • 流式传输与扩展传输：提供流式 HTTP 传输能力，支持后续扩展为 SSE/WebSocket 等
  • JSON-RPC 通信：服务器以 MCP 的 JSON-RPC 协议与客户端交互
  • Things Cloud 集成：通过 Things Cloud SDK 与官方/逆向 API 实现对 Things Cloud 的读取和写入
  • 授权与安全：内置 OAuth2.1 服务器，JWT 风格的访问令牌机制，以及诊断/审计能力
  • 自带文档与演示页面： landing、文档、How-it-Works 等页面，方便使用与集成
  • 测试与示例覆盖：包含多项单元测试与模拟服务器，便于验证行为

• 安装步骤

  • 确认环境
    • 需要安装 Go 语言环境
  • 构建服务器
    • 在仓库根目录执行构建命令将生成可执行文件（things-mcp）
  • 启动服务器（默认端口 8080，可通过 PORT 指定）
    • 运行示例（环境变量可选）
      • PORT=8080 JWT_SECRET=你的32字节密钥 ./things-mcp
  • 运行后端服务
    • 服务器会监听网络请求，提供 MCP JSON-RPC 接口以及 OAuth 流程所需的鉴权端点
  • 客户端依赖
    • MCP 客户端（LLM）通过向 /mcp 端点发送 JSON-RPC 请求来调用服务端暴露的工具与资源
    • 客户端需要提前完成 OAuth 流程并获得访问令牌，或使用 Basic 认证头部进行请求

• 服务器配置（MCP 客户端所需信息，JSON 描述，不属于客户端代码）

  • serverName: "Things Cloud MCP"
  • command: "./things-mcp"
  • args: ["-port","8080"] // 端口参数（如需）
  • env:
    • JWT_SECRET: "your-32-byte-secret" // 用于签发/验证 JWT 的密钥
    • DATA_DIR: "data" // OAuth 数据与诊断报告等的本地持久化目录
  • 说明：该配置仅用于客户端参考如何启动与连接服务器，实际客户端不需要此文件去运行，仅需知道服务器地址与鉴权方式

• 基本使用方法

  • 连接与鉴权
    • 客户端通过 JSON-RPC 调用时应携带合适的鉴权信息（Bearer Token 或 Basic 认证头），以访问对应的用户数据和操作权限
  • 调用方式
    • 通过 MCP 的 JSON-RPC 接口请求服务器暴露的工具（Tools）来查询、创建、修改 Things Cloud 上的项目信息、任务、区域、标签等
  • 安全性与会话
    • 服务器维护会话和能力声明，支持多用户场景，适配不同客户端（Claude.ai、ChatGPT、Cursor 等）的使用模式
  • 诊断与监控
    • 服务器内置诊断工具，提供详细的步骤、日志与摘要，便于排错和性能评估