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=<query>) 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=<query> 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.