tpc-server

✨TPC 服务器 ✨

跟踪您的代理人（或项目）的想法🧠、计划📝和变化✅！

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

🤔 什么是 TPC？

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

• **想法（🧠）：**在决定采取行动之前记录见解、想法、观察、考虑或原始数据点。
• **计划（📝）：**定义预期的行动方针、策略、目标或方法，通常源于想法。
• **变化（✅）：**记录采取的具体行动或所做的修改，通常与它们帮助执行的特定计划相关联。

该服务器有助于记录这些项目及其关系（想法<->计划->变化）。

🚀 功能

• **🧠 跟踪想法、📝 计划和✅ 变化：**每个概念都有专用的模型和存储。
• **🔗 互连数据：**将想法与计划（多对多）联系起来，将变化联系起来，再回到计划（多对一）。
• **🌐 Web 界面：**用于浏览最近的活动、想法、计划和变化的简单 HTML 视图。
• **🔌 JSON API：**用于程序化数据检索的端点（最近的项目、所有想法/计划/变化）。
• **🤖 代理工具 (MCP)：**通过mcp-server公开功能，以便 AI 代理与 TPC 存储进行交互（ add_thought 、 create_plan 、 log_change 、 get_... ）。
• **💾 数据库后端：**使用 SQLAlchemy（默认为 SQLite，可通过 URL 轻松配置）。
• **⚙️ 可配置：**通过.env设置 DB URL、主机、端口和代理通信传输（SSE/stdio）。
• **🪄 自动表创建：**如果数据库表不存在，则在第一次运行时自动创建。

🛠️ 安装和设置

1. 克隆存储库：
   git clone [https://github.com/suttonwilliamd/tpc-server.git](https://github.com/suttonwilliamd/tpc-server.git) cd tpc-server
2. 创建并激活虚拟环境：
   # Create environment python -m venv venv # Activate (macOS/Linux) source venv/bin/activate # Activate (Windows - Git Bash/WSL) source venv/Scripts/activate # Activate (Windows - Command Prompt/PowerShell) .\venv\Scripts\activate
3. 安装依赖项：
   Install using: ```bash pip install -r requirements.txt
4. **配置环境：**在项目根目录中创建一个.env文件：
   # .env file # --- Database --- # Default: SQLite in project root. Use postgresql://user:pass@host:port/db for PostgreSQL, etc. DATABASE_URL="sqlite:///./tpc_server.db" # --- Server Network --- HOST="0.0.0.0" # Listen on all network interfaces PORT="8050" # Port for FastAPI and MCP SSE # --- Agent Communication --- # 'sse' (Server-Sent Events over HTTP) or 'stdio' (Standard Input/Output) TRANSPORT="sse"

▶️ 运行服务器

确保您的虚拟环境处于活动状态并且您位于项目根目录中。

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

💡 使用方法

🖥️ Web 界面

通过浏览器访问简单的 Web 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 代理连接到 MCP 服务器（使用配置的TRANSPORT ）以使用这些工具：

• 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 ） - 简单且不需要单独的 DB 服务器。
• 通过更改.env中的DATABASE_URL并安装适当的驱动程序（例如， pip install psycopg2-binary ），轻松切换到PostgreSQL、MySQL等。
• 如果服务器启动时表不存在，SQLAlchemy 会自动创建表。

🙌 贡献

欢迎贡献代码、提交问题和功能请求！欢迎查看问题页面或提交拉取请求。