TPC Server

A Node.js/Express API for AI-human collaboration, starting with JSON file storage for thoughts and plans.

Setup and Usage

1. Install dependencies: npm install

2. Start the server: node server.js

3. The server runs on http://localhost:3001

Changelog

See CHANGELOG.md for detailed release notes.

Testing

Run npm test (or npm run test:unit) to execute Jest API/integration tests.

Run npm run test:e2e for Playwright UI tests.

Run npm run smoke:mcp for deterministic MCP plan/thought lifecycle smoke validation.

Production Security

/tpc.db download is disabled in production by default.

To explicitly allow it, set EXPOSE_TPC_DB=true.

Operational Endpoints

• GET /health returns basic liveness info.
• GET /ready returns readiness info and DB path.

Data Contract (REST + MCP)

• IDs: integer autoincrement IDs from SQLite for plans/thoughts.
• Timestamps:
• thoughts.timestamp, plans.timestamp = ISO8601 string.
• plans.created_at, plans.last_modified_at = epoch milliseconds.
• Tags: JSON-encoded string arrays in DB columns.

Project Structure

• server.js: Main Express server with modular structure (db/, routes/, middleware/).
• mcp-server.js: MCP server for AI clients (stdio transport). Run with npm run mcp.
• data/tpc.db: SQLite database for persistent storage of thoughts and plans.
• tests/: Test files (Jest unit tests, MCP tests).
• public/: Static single-page UI.

Usage Examples

REST API

• Retrieve all thoughts: curl http://localhost:3001/thoughts
• Retrieve all plans: curl http://localhost:3001/plans
• Create a thought: curl -X POST http://localhost:3001/thoughts -H "Content-Type: application/json" -d '{"content": "My thought"}'
• Create a plan: curl -X POST http://localhost:3001/plans -H "Content-Type: application/json" -d '{"title": "My Plan", "description": "Plan details"}'
• Update plan status: curl -X PATCH http://localhost:3001/plans/1 -H "Content-Type: application/json" -d '{"status": "in_progress"}'
• Search across plans/thoughts: curl "http://localhost:3001/search?q=AI&type=plans&tags=urgent&limit=5"
• Add tags to a plan: curl -X PATCH http://localhost:3001/plans/1/tags -H "Content-Type: application/json" -d '{"tag": "ai"}' (appends) or {"tags": ["ai", "urgent"]} (replaces)
• Filter plans by tags: curl "http://localhost:3001/plans?tags=ai,urgent"
• View UI: Visit http://localhost:3001/index.html after starting the server.

MCP Server

• Start MCP server: npm run mcp
• Connects via stdio — configure your MCP client to use this
• Available tools: list_plans, get_plan, create_plan, update_plan, list_thoughts, create_thought, search_thoughts, get_context
• Available resources: tpc://plans, tpc://thoughts, tpc://context

Features

• MCP Server: Full MCP protocol implementation for AI clients. Run with npm run mcp (stdio transport).
• Modular server architecture: Organized into db/, routes/, and middleware/ for maintainable API development.
• SQLite persistence: Single data/tpc.db for thoughts and plans with idempotent schema migrations.
• Comprehensive testing: Jest for unit tests (endpoints, validation, integrations) and Playwright for E2E UI tests (rendering, interactions).
• AI collaboration focus: Endpoints like /context aggregate data for agent memory; supports human edits with review flags.
• Rich text support: Plan descriptions accept and display Markdown formatting (bold, lists, etc.) in the UI using marked.js.
• Search and organization: Full-text search API (/search?q=) with type/tags/limit filters; UI search input and tag-based filtering/editing.
• Tagging system: Add/edit/filter tags on plans/thoughts via API/UI for better categorization (e.g., ['ai', 'urgent']).

v2.7 - Search and Organization

Features Implemented

• Full-text search endpoint (GET /search?q=) with optional ?type=plans|thoughts, ?tags=tag1,tag2, ?limit=N for targeted results.
• Tagging system: tags column (JSON array) on plans/thoughts tables; manage via POST/PUT/PATCH /plans/:id/tags (and for thoughts).
• Tag filtering: ?tags=ai,urgent (AND logic) on list endpoints (/plans, /thoughts, /search).
• Enhanced /context with ?search= to filter aggregated data.
• UI: Global search input, tag editing in details, tag filtering dropdowns in lists.

Usage

• API search: curl "http://localhost:3001/search?q=collaboration&type=plans&tags=ai"
• Tag a plan: curl -X PATCH http://localhost:3001/plans/1/tags -H "Content-Type: application/json" -d '{"tags": ["ai", "urgent"]}' (replace) or {"tag": "new"} (append).
• Filter by tags: curl "http://localhost:3001/plans?tags=ai,urgent"
• UI: Enter query in search box; click tags to edit/filter in plan/thought views.

Notable Changes

• Schema addition: tags TEXT column (default '[]') to plans/thoughts tables; backward compatible migration with backfill.
• New route: /search for unified querying.
• Builds on v2.6 Markdown support and modular structure.