thoughtbox

Thoughtbox is a Docker-based MCP server that enables multi-agent collaboration with auditable reasoning. Agents register with role-specific profiles, join shared workspaces, and work through a structured workflow that moves from problem creation to consensus. All thoughts and actions are persisted in a reasoning ledger, and the Observability stack lets you watch live reasoning unfold in the built-in Observatory UI. To interact with Thoughtbox, connect an MCP client (e.g., Claude Code or other MCP-compatible clients) to the server URL and start issuing workspace, problem, claim, work, and review operations through the thoughtbox_hub interface. The system supports branches, proposals, and a centralized consensus mechanism so teams can compare alternatives, trace how conclusions were reached, and audit every step of the process.

The server exposes an HTTP transport on port 1731 by default and provides an observability layer at port 1729. Typical usage flows include: register a hub agent, create a workspace, introduce a problem, claim ownership, iteratively propose solutions, conduct peer reviews, merge changes, and reach a consensus. The Knowledge Graph stores persistent entities and relationships (e.g., BUILDS_ON, CONTRADICTS, SUPERSEDES) with visibility controls to manage who can see what. For monitoring and tracing, enable OpenTelemetry, Prometheus metrics, and Grafana dashboards via the Observability stack, and use the Observability UI to navigate thoughts, branches, and details of each node.

Prerequisites:\n- Docker and Docker Compose installed on your machine.\n- Git installed to clone the repository.\n\nInstall and run Thoughtbox:\n1) Clone the repository:\nbash\ngit clone https://github.com/Kastalien-Research/thoughtbox.git\ncd thoughtbox\n\n2) Start the MCP server with Docker Compose (build images if needed):\nbash\ndocker compose up --build\n\n3) Verify the server is running:\n- MCP HTTP endpoint should be available at http://localhost:1731/mcp\n- Observatory UI at http://localhost:1729 (when enabled in environment)\n\nOptional: If you want to install and run a single container without docker-compose, you would need to adapt to a compatible image and run command, but the project is designed for the compose-based setup as shown above.

Environment variables you may encounter or want to configure:\n- THOUGHTBOX_DATA_DIR: Base directory for persistent storage (default: ~/.thoughtbox).\n- THOUGHTBOX_TRANSPORT: Transport type (stdio or http).\n- THOUGHTBOX_OBSERVATORY_ENABLED: Enable the Observatory web UI.\n- THOUGHTBOX_OBSERVATORY_PORT: Port for the Observatory UI (default 1729).\n- PORT: HTTP server port (default 1731).\n- HOST: Bind address for the HTTP server (default 0.0.0.0).\n- THOUGHTBOX_AGENT_ID / THOUGHTBOX_AGENT_NAME: Pre-assigned hub agent details if you want to seed identities.\n- DISABLE_THOUGHT_LOGGING: Suppress thought logging to stderr.\n- THOUGHTBOX_EVENTS_ENABLED / THOUGHTBOX_EVENTS_DEST: Enable and direct event emission.\n- THOUGHTBOX_STORAGE: Storage backend (fs or memory).\n- THOUGHTBOX_OBSERVATORY_CORS: CORS origins for the Observatory (comma-separated).\n\nCommon issues:\n- If the Observatory UI does not appear, verify that THOUGHTBOX_OBSERVATORY_ENABLED is true and that the port is not blocked.\n- Ensure Docker permissions and that your user is in the docker group to avoid permission errors when running docker-compose.\n- When upgrading, re-build with docker compose up --build to ensure you’re running the latest images.