✨ TPC Server ✨

跟踪您的代理（或项目）的思考 🧠、计划 📝 和变更 ✅！

TPC Server 提供后端服务，用于记录、存储和检索 AI 代理或协作项目的推理过程、预期行动和执行步骤。使用 FastAPI、MCP-Server 和 SQLAlchemy 构建。

🤔 什么是 TPC？

核心思想是创建一个结构化且相互关联的日志：

• 思考 (🧠): 在决定行动之前，记录见解、想法、观察、考虑或原始数据点。
• 计划 (📝): 定义预期的行动路线、策略、目标或方法，通常从思考中得出。
• 变更 (✅): 记录采取的具体行动或所做的修改，通常与特定计划相关联，以帮助执行该计划。

此服务器有助于记录这些条目及其关系（思考 <-> 计划 -> 变更）。

🚀 功能

• 🧠 跟踪思考、📝 计划和 ✅ 变更： 每个概念都有专门的模型和存储。
• 🔗 相互关联的数据： 将思考链接到计划（多对多），并将变更链接回计划（多对一）。
• 🌐 网页界面： 简单的 HTML 视图浏览最近活动、思考、计划和变更。
• 🔌 JSON API： 用于程序化数据检索的端点（最近条目、所有思考/计划/变更）。
• 🤖 代理工具 (MCP)： 通过 mcp-server 暴露函数，供 AI 代理与 TPC 存储交互（add_thought、create_plan、log_change、get_...）。
• 💾 数据库后端： 使用 SQLAlchemy（默认为 SQLite，可通过 URL 配置）。
• ⚙️ 可配置性： 通过 .env 文件设置数据库 URL、主机、端口和代理通信传输方式 (SSE/stdio)。
• 🪄 自动表创建： 如果表不存在，在首次运行时会自动创建数据库表。

🛠️ 安装与设置

1. 克隆仓库：

   git clone [https://github.com/suttonwilliamd/tpc-server.git](https://github.com/suttonwilliamd/tpc-server.git)
   cd tpc-server
   

2. 创建并激活虚拟环境：

   # 创建环境
   python -m venv venv
   
   # 激活 (macOS/Linux)
   source venv/bin/activate
   
   # 激活 (Windows - Git Bash/WSL)
   source venv/Scripts/activate
   
   # 激活 (Windows - 命令提示符/PowerShell)
   .\venv\Scripts\activate
   

3. 安装依赖项：

   使用以下命令安装：
   ```bash
   pip install -r requirements.txt
   

4. 配置环境：
   在项目根目录下创建一个 .env 文件：

   # .env 文件
   
   # --- 数据库 ---
   # 默认: 项目根目录中的 SQLite。对于 PostgreSQL 等，请使用 postgresql://user:pass@host:port/db。
   DATABASE_URL="sqlite:///./tpc_server.db"
   
   # --- 服务器网络 ---
   HOST="0.0.0.0"     # 监听所有网络接口
   PORT="8050"        # FastAPI 和 MCP SSE 的端口
   
   # --- 代理通信 ---
   # 'sse' (HTTP 上的 Server-Sent Events) 或 'stdio' (标准输入/输出)
   TRANSPORT="sse"
   

▶️ 运行服务器

确保你的虚拟环境已激活，并且你位于项目根目录。

python main.py

服务器将启动，并显示来自 Uvicorn（用于 FastAPI）和可能的 MCP 服务器的日志。你应该会看到输出，指示服务器正在配置的 HOST 和 PORT 上运行。

💡 使用说明

🖥️ 网页界面

通过浏览器访问简单的网页 UI（默认：http://localhost:8050）：

• /: 显示最近10项活动的概览。
• /thoughts: 列出所有记录的想法。
• /plans: 列出所有记录的计划。
• /changes: 列出所有记录的变化（包括相关计划标题）。

💻 JSON API

以编程方式获取数据：

• GET /api/recent-activity: 最近10个想法、计划和变化的综合列表。
• GET /api/thoughts: 所有想法的列表。
• GET /api/plans: 所有计划的列表。
• GET /api/changes: 所有变化的列表（包括 plan_title）。

🤖 代理工具（通过 MCP）

AI 代理通过配置的 TRANSPORT 连接到 MCP 服务器来使用这些工具：

• add_thought(...): 记录一个新的想法。
• create_plan(...): 定义一个新的计划。
• log_change(...): 记录对某个计划采取的动作。
• get_recent_thoughts(...): 获取最新的想法。
• get_active_plans(): 获取所有“活跃”计划。
• get_changes_by_plan(...): 获取特定计划ID的变化。
• get_thought_details(...): 获取特定想法ID的详细信息（包括链接的计划）。
• get_plan_details(...): 获取特定计划ID的详细信息（包括链接的想法/变化）。

（有关工具参数和使用的详细代理指令，请参阅 LLM.txt。）

🗄️ 数据库

• 默认使用项目目录中的 SQLite 文件 (tpc_server.db) - 简单且不需要单独的数据库服务器。
• 通过更改 .env 中的 DATABASE_URL 并安装适当的驱动程序（例如，pip install psycopg2-binary），可以轻松切换到 PostgreSQL, MySQL 等。
• 如果在服务器启动时不存在表，则 SQLAlchemy 会自动创建它们。

🙌 贡献

欢迎贡献、问题报告和功能请求！请随时查看 issues 页面 或提交 pull request。