Track your agent's (or project's) Thoughts 🧠, Plans 📝, and Changes ✅!
TPC Server provides a backend service to log, store, and retrieve the reasoning process, intended actions, and executed steps for AI agents or collaborative projects. Built with FastAPI, MCP-Server, and SQLAlchemy.
The core idea is to create a structured, interconnected log:
- Thoughts (🧠): Record insights, ideas, observations, considerations, or raw data points before action is decided.
- Plans (📝): Define intended courses of action, strategies, goals, or approaches, often derived from thoughts.
- Changes (✅): Log concrete actions taken or modifications made, usually linked to a specific plan they help execute.
This server facilitates recording these items and their relationships (Thoughts <-> Plans -> Changes).
- 🧠 Track Thoughts, 📝 Plans, and ✅ Changes: Dedicated models and storage for each concept.
- 🔗 Interconnected Data: Link thoughts to plans (many-to-many) and changes back to plans (many-to-one).
- 🌐 Web Interface: Simple HTML views for Browse recent activity, thoughts, plans, and changes.
- 🔌 JSON API: Endpoints for programmatic data retrieval (recent items, all thoughts/plans/changes).
- 🤖 Agent Tools (MCP): Exposes functions via
mcp-serverfor AI agents to interact with the TPC store (add_thought,create_plan,log_change,get_...). - 💾 Database Backend: Uses SQLAlchemy (defaults to SQLite, easily configurable via URL).
- ⚙️ Configurable: Set DB URL, host, port, and agent communication transport (SSE/stdio) via
.env. - 🪄 Auto Table Creation: Database tables are created automatically on first run if they don't exist.
-
Clone the Repository:
git clone [https://github.com/suttonwilliamd/tpc-server.git](https://github.com/suttonwilliamd/tpc-server.git) cd tpc-server -
Create & Activate Virtual Environment:
# 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
-
Install Dependencies:
Install using: ```bash pip install -r requirements.txt -
Configure Environment: Create a
.envfile in the project root:# .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"
Make sure your virtual environment is active and you're in the project root.
python main.pyThe server will start, displaying logs from Uvicorn (for FastAPI) and potentially the MCP server. You should see output indicating the server is running on the configured HOST and PORT.
Access the simple web UI through your browser (default: http://localhost:8050):
/: Overview of the 10 most recent activities./thoughts: List all recorded thoughts./plans: List all recorded plans./changes: List all recorded changes (with associated plan titles).
Fetch data programmatically:
GET /api/recent-activity: Combined list of the 10 most recent thoughts, plans, and changes.GET /api/thoughts: List of all thoughts.GET /api/plans: List of all plans.GET /api/changes: List of all changes (includingplan_title).
AI Agents connect to the MCP server (using the configured TRANSPORT) to use these tools:
add_thought(...): Record a new thought.create_plan(...): Define a new plan.log_change(...): Log an action taken against a plan.get_recent_thoughts(...): Retrieve latest thoughts.get_active_plans(): Retrieve all 'active' plans.get_changes_by_plan(...): Get changes for a specific plan ID.get_thought_details(...): Get details for a specific thought ID (incl. linked plans).get_plan_details(...): Get details for a specific plan ID (incl. linked thoughts/changes).
(Refer t
617C
o LLM.txt for detailed agent instructions on tool arguments and usage.)
- Defaults to a SQLite file (
tpc_server.db) in the project directory - simple and requires no separate DB server. - Easily switch to PostgreSQL, MySQL, etc., by changing
DATABASE_URLin.envand installing the appropriate driver (e.g.,pip install psycopg2-binary). - Tables are created automatically by SQLAlchemy if they don't exist upon server start.
Contributions, issues, and feature requests are welcome! Feel free to check the issues page or submit a pull request.