Thoughtbox MCP

Thoughtbox

可审计的多代理协作推理。 Thoughtbox是一个基于Docker的MCP服务器，AI代理通过共享工作区进行协调——提出问题、提出解决方案、审查彼此的工作并达成共识。每一步都被记录在一个持久的推理分类账中，作为一个结构化的思想，可以可视化、导出和分析。

本地优先： 完全在您的机器上运行。所有数据保持不变 ~/.thoughtbox/ --没有什么离开你的网络。

Thoughtbox Observatory *Observatory UI显示了一个包含14个想法的推理会话和一个从想法5分叉的分支探索（紫色节点13-14）。*

代码模式

Thoughtbox完全暴露了 两个MCP工具 使用代码模式模式：

• thoughtbox_search --编写JavaScript来查询操作/提示/资源目录。LLM对目录具有完全的编程过滤能力。
• thoughtbox_execute --使用以下代码编写JavaScript tb SDK到链操作。通过统一的命名空间访问想法、会话、知识、笔记本、中心、可观察性和协议工具。

工作流程： 搜索以发现可用的操作，然后对它们执行代码。使用 console.log() 对于调试，输出被捕获在响应日志中。

这将用一个无上下文窗口膨胀的双工具曲面替换每个操作的工具注册。

多Agent协作

Hub是协调层。代理使用特定角色的配置文件注册，加入共享工作区，并通过结构化的问题解决工作流工作——所有这些都是通过 thoughtbox_execute.

工作流程： 注册→ 创建工作区→ 产生问题→ 声称→ work → 提出解决方案→ 同行评审→ 合并→ 共识

工作空间图元：

• 问题 --一个包含依赖关系、子问题和状态跟踪的工作单元（打开→ 进行中→ 解决→ 关闭）
• 提案 --一种具有源分支参考和审查工作流的解决方案
• 共识 --与思想参考相关的决策标记，用于可追溯性
• 频道 --针对问题进行讨论的消息流

代理配置文件： MANAGER, ARCHITECT, DEBUGGER, SECURITY, RESEARCHER, REVIEWER --每个都提供了特定领域的心理模型和行为启动。

28次操作 跨身份、工作空间管理、问题、建议、共识、渠道和状态报告。

可审计推理

每个想法都是图中的一个节点——有编号、有时间戳、与前一个想法链接，并在会话中持久存在。这创建了一个可审计的线索，说明结论是如何得出的。

代理人可以向前思考，向后规划，分支到并行探索，修改早期结论，并通过MCP抽样请求自主批评。每种模式都是一流的操作：

每个想法都有一个语义 thoughtType (reasoning, decision_frame, action_report, belief_snapshot, assumption_update, context_snapshot, progress)分类 *哪种* 它与所使用的工艺模式正交。

看 模式食谱 为了获得全面的示例。

实时可观测性

这 天文台 是一个内置的web UI http://localhost:1729 观看推理过程的实况。

• 实时图表 --思想通过WebSocket实时显示为节点
• 分支导航 --树枝坍塌成可点击的短截线；钻入和钻出
• 详情面板 --单击任何节点查看完整的思想内容
• 多会话 --在主动推理会话之间切换
• 深入分析 --分析会话的推理模式、认知负荷和决策点

完整的可观察性堆栈包括OpenTetry跟踪、Prometheus指标和Grafana仪表板。

知识和推理工具

知识图谱 --跨会话的持久内存。将见解、概念、工作流程和决策作为具有类型化关系的类型化实体进行捕获(BUILDS_ON, CONTRADICTS, SUPERSEDES等）和能见度控制(public, agent-private, team-private).

笔记本 --在隔离环境中将文档与可执行JavaScript/TypeScript相结合的交互式文学编程。

客户端兼容性

Thoughtbox目前已针对以下方面进行了优化 克劳德代码。我们正在积极支持更多的MCP客户。由于MCP生态系统中功能支持的差异——服务器功能（提示、资源、工具）、客户端功能（根、采样、启发）和行为 listChanged 通知——我们为许多客户端实现了自定义调整。

如果您使用的客户端不是Claude Code，并且遇到问题，请 打开一个问题 描述你的客户和问题。

安装

Thoughtbox作为基于Docker的MCP服务器运行。它需要Docker和Docker Compose。

快速开始

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

这将启动Thoughtbox和完整的可观察性堆栈。MCP服务器监听端口 1731 天文台用户界面可在 http://localhost:1729.

MCP客户端配置

由于Thoughtbox使用HTTP传输，请将MCP客户端配置为通过URL连接。

克劳德代码

添加到您的 ~/.claude/settings.json 或项目 .claude/settings.json:

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

要通过可观察性sidecar进行连接（添加了OpenTetry跟踪）：

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

Cline/VS代码

添加到MCP设置或 .vscode/mcp.json:

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

使用示例

前瞻性思维——问题分析

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"

逆向思维——系统设计

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"

分支——比较备选方案

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"

环境变量

发展

对于本地开发（需要Node.js 22+）：

pnpm install
pnpm build
pnpm dev      # Development with hot reload

测试

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 启动完整堆栈：

持久数据存储在命名卷中： thoughtbox-data, prometheus-data, grafana-data.

建筑

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
├── init/                   # Init workflow and state management
│   ├── tool-handler.ts     # Init tool operations
│   └── state-manager.ts    # Session state persistence
├── sessions/               # Session management
├── sampling/               # Autonomous critique via MCP sampling
│   └── handler.ts          # SamplingHandler for LLM critique requests
├── 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
├── multi-agent/            # Agent attribution, content hashing, conflict detection
├── 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

存储

Thoughtbox支持三种存储后端：

• 内存存储：用于测试的易失性存储，用途 LinkedThoughtStore 用于O（1）思想查找
• 文件系统存储：具有原子写入和项目隔离的持久存储（默认）
• Supabase存储：由Supabase Postgres支持的云原生存储，用于部署实例

数据存储在 ~/.thoughtbox/ 默认情况下（FileSystemStorage）：

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

贡献

我们欢迎捐款！看 贡献.md 用于：

• 开发设置
• 提交约定（针对 thick_read 代码理解）
• 使用vitest和agent脚本进行测试
• 拉取请求流程

许可证

MIT许可证——免费使用、修改和分发。