Integrations
Enables configuration of database connections, server network settings, and agent communication transport through environment variables.
Provides a web interface and JSON API endpoints for accessing the TPC data, allowing users to browse thoughts, plans, and changes via a simple HTML interface.
Supported as an optional alternative database backend that can be configured by changing the DATABASE_URL environment variable.
✨ TPC Server ✨
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.
🤔 What is TPC?
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).
🚀 Features
- 🧠 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-server
for 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.
🛠️ Installation & Setup
- Clone the Repository:Copy
- Create & Activate Virtual Environment:Copy
- Install Dependencies:Copy
- Configure Environment:
Create a
.env
file in the project root:Copy
▶️ Running the Server
Make sure your virtual environment is active and you're in the project root.
The 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
.
💡 Usage
🖥️ Web Interface
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).
💻 JSON API
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
).
🤖 Agent Tools (via MCP)
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 to LLM.txt
for detailed agent instructions on tool arguments and usage.)
🗄️ Database
- 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_URL
in.env
and installing the appropriate driver (e.g.,pip install psycopg2-binary
). - Tables are created automatically by SQLAlchemy if they don't exist upon server start.
🙌 Contributing
Contributions, issues, and feature requests are welcome! Feel free to check the issues page or submit a pull request.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
tpc-server
Related MCP Servers
- -securityAlicense-qualityThis server is a server that installs other MCP servers for you. Install it, and you can ask Claude to install MCP servers hosted in npm or PyPi for you. Requires npx and uv to be installed for node and Python servers respectively.Last updated -24,321624JavaScriptMIT License
- Python
- AsecurityAlicenseAqualityBrowserStack MCP serverLast updated -520347TypeScriptAGPL 3.0
- PythonMIT License