使用说明

项目简介

TPC Server (Thoughts, Plans, Changelog Server) 是一个基于 Model Context Protocol (MCP) 构建的应用后端，专注于支持AI团队在软件开发过程中的协作和知识管理。它通过结构化的方式记录团队的想法 (Thoughts)、计划 (Plans) 和变更日志 (Changelog)，帮助团队跟踪决策过程、协调任务和管理项目进度。

主要功能点

结构化协作:
- 记录设计决策 ('Thoughts')、任务协调 ('Plans') 和开发进度 ('Changelog')。
- 支持计划的依赖关系管理，适用于复杂的开发流程。
- 标记设计决策中的不确定性。
性能优化:
- 使用异步 SQLAlchemy 2.0 和连接池，提高数据访问效率。
- 采用时间排序的 UUID (UUID7) 确保时间追踪的准确性。
- 具备查询缓存机制，提升常用数据获取速度。
开发者友好:
- 完全兼容 MCP 接口标准，方便集成 MCP 客户端。
- 提供 REST-like 资源端点，便于数据访问和管理。
- 使用 Pydantic 进行全面的数据验证，保证数据质量。

安装步骤

克隆仓库

git clone https://github.com/suttonwilliamd/tpc-server.git
cd tpc-server

安装依赖

pip install -r requirements.txt

服务器配置

TPC Server 可以通过 Uvicorn 启动。以下是 MCP 客户端连接 TPC Server 的服务器配置信息（JSON 格式）：

{
  "server name": "TPC Server",
  "command": "uvicorn",
  "args": [
    "main:mcp",  // main.py 文件中的 mcp 实例
    "--reload",  // 启用热重载，方便开发时修改代码自动重启 (生产环境建议移除)
    "--port",
    "8000"     // 指定服务器端口为 8000
  ]
}

配置参数说明:

'"server name"': 服务器名称，设置为 "TPC Server"。
'"command"': 启动服务器的命令，这里使用 "uvicorn" (需要已安装)。
'"args"': 传递给 'uvicorn' 命令的参数列表：
- '"main:mcp"': 指定 Uvicorn 运行 'main.py' 文件中的 'mcp' 实例。
- '"--reload"': 启用代码热重载，在开发环境下非常有用，修改代码后服务器会自动重启，生产环境不建议使用。
- '"--port"': 指定服务器监听的端口。
- '"8000"': 设置服务器端口为 8000。

启动服务器:

在项目根目录下，可以直接运行以下命令启动 TPC Server (开发环境，带热重载):

uvicorn main:mcp --reload --port 8000

生产环境启动命令 (移除 '--reload'):

uvicorn main:mcp --port 8000

基本使用方法

TPC Server 提供了 Tools (工具) 和 Resources (资源) 两种类型的 MCP 接口。

Tools (工具): 用于执行操作，例如创建 'Thoughts', 'Plans', 'Changelog'。
- 'create_thought': 创建新的想法记录，可以关联到计划和标记不确定性。
- 'bulk_create_thoughts': 批量创建多个想法记录。
- 'create_plan': 创建新的计划任务，可以设置依赖关系和状态。
- 'log_change': 记录变更日志，关联到计划和相关的想法。
- 'invalidate_caches': 手动清理服务器缓存。
Resources (资源): 用于获取数据，例如查询 'Thoughts', 'Plans', 'Changelog'。
- 'tpc://thoughts': 获取所有想法记录，支持分页查询。
- 'tpc://thoughts/{thought_id}': 根据 ID 获取特定想法记录。
- 'tpc://plans': 获取所有计划任务，支持分页查询，并包含依赖关系信息。
- 'tpc://plans/{plan_id}': 根据 ID 获取特定计划任务，包含依赖关系信息。
- 'tpc://changelog': 获取所有变更日志，支持分页查询，并包含关联的想法 ID。
- 'tpc://changelog/{change_id}': 根据 ID 获取特定变更日志，包含关联的想法 ID。

与 MCP 客户端交互:

MCP 客户端需要配置上述服务器信息，并使用 MCP 协议与 TPC Server 进行通信，调用 Tools 执行操作或访问 Resources 获取数据。具体调用方式请参考 MCP 客户端的文档和 MCP 协议规范。

示例 (MCP 客户端调用 'create_thought' Tool):

MCP 客户端需要构造符合 JSON-RPC 规范的请求，发送到 TPC Server。例如，调用 'create_thought' Tool 的请求可能如下 (简化示例):

{
  "jsonrpc": "2.0",
  "method": "create_thought",
  "params": {
    "content": "Example thought content",
    "plan_id": "pl_some_plan_id",
    "uncertainty_flag": true
  },
  "id": "request_id_1"
}

TPC Server 会处理该请求，并将结果以 JSON-RPC 响应的形式返回给客户端。

总结

TPC Server 提供了一个结构化的后端服务，用于管理软件开发过程中的关键信息，并通过 MCP 协议与客户端进行交互，是构建基于 LLM 的软件开发辅助工具的有效后端选择。

关键词