Thoughtbox

herramienta de razonamiento MCP de próxima generación. sucesora de Clear Thought de Waldzell AI.

Documentación

Thoughtbox

Razonamiento colaborativo multiagente que es auditable. Thoughtbox es un servidor MCP para razonamiento estructurado multiagente, con una aplicación web complementaria para flujos de espacio de trabajo e inspección. Cada paso se registra como un pensamiento estructurado en un libro de razonamiento persistente que se puede visualizar, exportar y analizar.

Modos de ejecución: El desarrollo local puede usar almacenamiento en sistema de archivos o en memoria. El modo desplegado usa almacenamiento respaldado por Supabase, y el servidor MCP de producción actual se ejecuta en Cloud Run.

Thoughtbox Observatory Interfaz de Observatory mostrando una sesión de razonamiento con 14 pensamientos y una exploración de rama (nodos púrpura 13-14) que se bifurca desde el pensamiento 5.

Modo de Código

Thoughtbox expone exactamente dos herramientas MCP usando el patrón de Modo de Código:

thoughtbox_search — Escriba JavaScript para consultar el catálogo de operaciones/indicaciones/recursos. El LLM tiene pleno poder de filtrado programático sobre el catálogo.
thoughtbox_execute — Escriba JavaScript usando el SDK tb para encadenar operaciones. Acceda a pensamientos, sesiones, conocimiento, cuadernos, hub, observabilidad y herramientas de protocolo a través de un espacio de nombres unificado.

Flujo de trabajo: busque para descubrir operaciones disponibles, luego ejecute código contra ellas. Use console.log() para depuración: la salida se captura en los registros de respuesta.

Esto reemplaza el registro de herramientas por operación con una superficie de dos herramientas que escala sin inflar la ventana de contexto.

Colaboración Multiagente

El Hub es la capa de coordinación. Los agentes se registran con perfiles específicos de rol, se unen a espacios de trabajo compartidos y trabajan a través de un flujo de trabajo estructurado de resolución de problemas, todo a través de thoughtbox_execute.

El flujo de trabajo: registrar → crear espacio de trabajo → crear problema → reclamar → trabajar → proponer solución → revisión por pares → fusionar → consenso

Primitivas del espacio de trabajo:

Problema — Una unidad de trabajo con dependencias, subproblemas y seguimiento de estado (abierto → en progreso → resuelto → cerrado)
Propuesta — Una solución propuesta con referencia de rama fuente y flujo de trabajo de revisión
Consenso — Un marcador de decisión vinculado a una referencia de pensamiento para trazabilidad
Canal — Un flujo de mensajes limitado a un problema para discusión

Perfiles de agente: MANAGER, ARCHITECT, DEBUGGER, SECURITY, RESEARCHER, REVIEWER — cada uno proporciona modelos mentales específicos del dominio y preparación conductual.

28 operaciones en identidad, gestión de espacios de trabajo, problemas, propuestas, consenso, canales e informes de estado.

Razonamiento Auditable

Cada pensamiento es un nodo en un grafo: numerado, con marca de tiempo, vinculado a sus predecesores y persistido entre sesiones. Esto crea un rastro auditable de cómo se alcanzaron las conclusiones.

Los agentes pueden pensar hacia adelante, planificar hacia atrás, ramificarse en exploraciones paralelas y revisar conclusiones anteriores. Cada patrón es una operación de primera clase:

Patrón	Descripción	Caso de uso
Hacia adelante	Progresión secuencial 1→2→3→N	Exploración, descubrimiento, análisis abierto
Hacia atrás	Comenzar en la meta (N), trabajar hacia atrás hasta el inicio (1)	Planificación, diseño de sistemas, trabajar desde metas conocidas
Ramificación	Bifurcarse en exploraciones paralelas (A, B, C...)	Comparar alternativas, escenarios A/B
Revisión	Actualizar pensamientos anteriores con nueva información	Corrección de errores, comprensión refinada

Cada pensamiento lleva un thoughtType semántico (reasoning, decision_frame, action_report, belief_snapshot, assumption_update, context_snapshot, progress) que clasifica qué tipo de pensamiento es, ortogonal al patrón de proceso utilizado.

Consulte el Libro de recetas de patrones para ver ejemplos completos.

Observabilidad en Tiempo Real

El Observatory es una interfaz web integrada en http://localhost:1729 para ver el razonamiento desarrollarse en vivo.

Gráfico en vivo — los pensamientos aparecen como nodos en tiempo real vía WebSocket
Navegación de ramas — las ramas se colapsan en stubs clicables; profundizar y volver
Panel de detalles — haga clic en cualquier nodo para ver el contenido completo del pensamiento
Multi-sesión — cambiar entre sesiones de razonamiento activas
Análisis profundo — analizar sesiones para patrones de razonamiento, carga cognitiva y puntos de decisión

La pila de observabilidad completa incluye trazado OpenTelemetry, métricas Prometheus y paneles de Grafana.

Herramientas de Conocimiento y Razonamiento

Grafo de conocimiento — Memoria persistente entre sesiones. Capture ideas, conceptos, flujos de trabajo y decisiones como entidades tipadas con relaciones tipadas (BUILDS_ON, CONTRADICTS, SUPERSEDES, etc.) y controles de visibilidad (public, agent-private, team-private).

Cuadernos — Programación literaria interactiva que combina documentación con JavaScript/TypeScript ejecutable en entornos aislados.

Compatibilidad de Clientes

Thoughtbox está actualmente optimizado para Claude Code. Estamos trabajando activamente en soportar clientes MCP adicionales. Debido a la variación en el soporte de capacidades en el ecosistema MCP — características del servidor (prompts, recursos, herramientas), características del cliente (raíces, muestreo, elicitación) y comportamientos como notificaciones listChanged — implementamos adaptaciones personalizadas para muchos clientes.

Si está usando un cliente distinto de Claude Code y encuentra problemas, por favor abra un issue describiendo su cliente y el problema.

Instalación

Thoughtbox se ejecuta como un servidor MCP basado en Docker. Requiere Docker y Docker Compose.

Inicio Rápido

git clone https://github.com/Kastalien-Research/thoughtbox.git
cd thoughtbox
docker compose up --build

Esto inicia Thoughtbox y la pila de observabilidad completa. El servidor MCP escucha en el puerto 1731 y la interfaz de Observatory está disponible en http://localhost:1729.

Configuración del Cliente MCP

Dado que Thoughtbox usa transporte HTTP, configure su cliente MCP para conectarse vía URL.

Claude Code

Agregue a su ~/.claude/settings.json o proyecto .claude/settings.json:

{
  "mcpServers": {
    "thoughtbox": {
      "url": "http://localhost:1731/mcp"
    }
  }
}

Para conectarse a través del sidecar de observabilidad (agrega trazado OpenTelemetry):

{
  "mcpServers": {
    "thoughtbox": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

Cline / VS Code

Agregue a su configuración MCP o .vscode/mcp.json:

{
  "servers": {
    "thoughtbox": {
      "url": "http://localhost:1731/mcp"
    }
  }
}

Ejemplos de Uso

Pensamiento Hacia Adelante — Análisis de Problemas

Thought 1: "Users report slow checkout. Let's analyze..."
Thought 2: "Data shows 45s average, target is 10s..."
Thought 3: "Root causes: 3 API calls, no caching..."
Thought 4: "Options: Redis cache, query optimization, parallel calls..."
Thought 5: "Recommendation: Implement Redis cache for product data"

Pensamiento Hacia Atrás — Diseño de Sistemas

Thought 8: [GOAL] "System handles 10k req/s with <100ms latency"
Thought 7: "Before that: monitoring and alerting operational"
Thought 6: "Before that: resilience patterns implemented"
Thought 5: "Before that: caching layer with invalidation"
...
Thought 1: [START] "Current state: 1k req/s, 500ms latency"

Ramificación — Comparación de Alternativas

Thought 4: "Need to choose database architecture..."

Branch A (thought 5): branchId="sql-path"
  "PostgreSQL: ACID compliance, mature tooling, relational integrity"

Branch B (thought 5): branchId="nosql-path"
  "MongoDB: Flexible schema, horizontal scaling, document model"

Thought 6: [SYNTHESIS] "Use PostgreSQL for transactions, MongoDB for analytics"

Variables de Entorno

Variable	Descripción	Predeterminado
`DISABLE_THOUGHT_LOGGING`	Suprimir el registro de pensamientos en stderr	`false`
`THOUGHTBOX_DATA_DIR`	Directorio base para almacenamiento persistente	`~/.thoughtbox`
`THOUGHTBOX_PROJECT`	Alcance del proyecto para aislamiento de sesiones	`_default`
`THOUGHTBOX_TRANSPORT`	Tipo de transporte (`stdio` o `http`)	`http`
`THOUGHTBOX_STORAGE`	Backend de almacenamiento (`fs`, `memory`, o `supabase`)	`fs`
`THOUGHTBOX_OBSERVATORY_ENABLED`	Habilitar la interfaz web de Observatory	`false`
`THOUGHTBOX_OBSERVATORY_PORT`	Puerto de la interfaz de Observatory	`1729`
`THOUGHTBOX_OBSERVATORY_CORS`	Orígenes CORS para Observatory (separados por comas)	(ninguno)
`THOUGHTBOX_AGENT_ID`	ID de agente Hub preasignado	(ninguno)
`THOUGHTBOX_AGENT_NAME`	Nombre de agente Hub preasignado	(ninguno)
`SUPABASE_URL`	URL del proyecto Supabase (requerido para almacenamiento `supabase`)	(ninguno)
`SUPABASE_SERVICE_ROLE_KEY`	Clave de rol de servicio de Supabase (requerida para almacenamiento `supabase`)	(ninguno)
`PORT`	Puerto del servidor HTTP	`1731`
`HOST`	Dirección de enlace del servidor HTTP	`0.0.0.0`
`NODE_ENV`	Entorno de Node	(ninguno)
`PROMETHEUS_URL`	Endpoint de Prometheus (Docker)	`http://prometheus:9090`
`GRAFANA_URL`	Endpoint de Grafana (Docker)	`http://grafana:3000`

Desarrollo

Para desarrollo local (requiere Node.js 22+):

pnpm install
pnpm build
pnpm dev      # Development with hot reload

Pruebas

npx vitest run              # Unit tests
pnpm test                   # Full suite (build + vitest)
pnpm test:agentic           # Agentic tests — full suite (build + run)
pnpm test:agentic:tool      # Agentic tests — tool-level only
pnpm test:agentic:quick     # Agentic tests — quick (no build)
pnpm test:behavioral        # Behavioral contract tests

Docker Compose

docker compose up --build inicia la pila completa:

Servicio	Puerto	Descripción
thoughtbox	1731 (MCP), 1729 (Observatory)	Servidor MCP principal + interfaz de Observatory
mcp-sidecar	4000	Proxy de observabilidad con OpenTelemetry
otel-collector	4318 (HTTP), 8889 (métricas)	OpenTelemetry Collector
prometheus	9090	Almacenamiento de métricas + alertas
grafana	3001	Paneles y visualización

Los datos persistentes se almacenan en volúmenes con nombre: thoughtbox-data, prometheus-data, grafana-data.

Arquitectura

src/
├── index.ts                # Entry point (Streamable HTTP transport)
├── server-factory.ts       # MCP server factory with tool registration
├── thought-handler.ts      # Core thought recording logic
├── types.ts                # Shared type definitions
├── database.types.ts       # Supabase generated types
├── code-mode/              # Code Mode tool surface
│   ├── search-tool.ts      # thoughtbox_search — catalog query via JS
│   ├── execute-tool.ts     # thoughtbox_execute — operation chaining via tb SDK
│   ├── search-index.ts     # Frozen catalog of operations/prompts/resources
│   └── sdk-types.ts        # TypeScript definitions for the tb SDK
├── thought/                # Thought operations and tool definitions
├── sessions/               # Session management
├── persistence/            # Storage layer
│   ├── storage.ts          # InMemoryStorage with LinkedThoughtStore
│   ├── filesystem-storage.ts  # FileSystemStorage with atomic writes
│   └── supabase-storage.ts # SupabaseStorage for deployed/cloud usage
├── observatory/            # Real-time visualization
│   ├── ui/                 # Self-contained HTML/CSS/JS
│   └── ws-server.ts        # WebSocket server for live updates
├── hub/                    # Multi-agent collaboration
│   ├── identity.ts         # Agent registration
│   ├── workspace.ts        # Workspace management
│   ├── problems.ts         # Problem tracking with dependencies
│   ├── proposals.ts        # Solution proposals with reviews
│   ├── consensus.ts        # Decision recording
│   ├── channels.ts         # Problem-scoped messaging
│   ├── hub-handler.ts      # Hub operation dispatcher
│   └── operations.ts       # 28-operation catalog
├── channel/                # Hub event channels and SSE streaming
├── protocol/               # Ulysses and Theseus protocol tools
├── knowledge/              # Knowledge graph memory
├── auth/                   # API key authentication
├── audit/                  # Audit manifest generation
├── evaluation/             # LangSmith evaluation and online monitoring
├── notebook/               # Literate programming engine
├── events/                 # Event emission system
├── observability/          # Prometheus/Grafana integration
├── prompts/                # MCP prompt definitions
├── references/             # Anchor parsing and resolution
├── revision/               # Revision indexing
├── operations-tool/        # Operations tool handler
└── resources/              # Documentation and patterns cookbook

Almacenamiento

Thoughtbox soporta tres backends de almacenamiento:

InMemoryStorage: Almacenamiento volátil para pruebas, usa LinkedThoughtStore para búsquedas de pensamientos O(1)
FileSystemStorage: Almacenamiento persistente con escrituras atómicas y aislamiento de proyectos (predeterminado)
SupabaseStorage: Almacenamiento nativo en la nube respaldado por Supabase Postgres para instancias desplegadas

Los datos se almacenan en ~/.thoughtbox/ por defecto (FileSystemStorage):

~/.thoughtbox/
├── config.json           # Global configuration
└── projects/
    └── {project}/
        └── sessions/
            └── {date}/
                └── {session-id}/
                    ├── manifest.json
                    └── {thought-number}.json

Contribuciones

¡Damos la bienvenida a contribuciones! Consulte CONTRIBUTING.md para:

Configuración de desarrollo
Convenciones de commits (optimizadas para la comprensión de código thick_read)
Pruebas con vitest y scripts agénticos
Proceso de pull request

Licencia

Licencia MIT — libre de usar, modificar y distribuir.