Omnispindle

一个运行得非常出色，且刻意走偏了的待办事项系统。

Omnispindle 是 Madness Interactive 生态系统的协调脊梁——一个拥有 33 个工具的 Python FastMCP 服务器，让 AI 智能体能够通过单一的标准化接口管理任务、捕获知识、协调会话并导航整个工作区。已打包至 PyPI。集成了 Auth0。可在任何支持 MCP 配置的地方运行。

它最初的初衷是“让我们把待办事项做好”。后来它成为了一个多项目 AI 辅助开发实验室的中枢神经系统。这两者都没问题。

它实际上做了什么

待办事项管理 —— 这是支撑其他一切的枯燥部分。智能体可以在生态系统中的任何项目中创建、查询、更新、完成和审计任务，并具备完整的元数据、优先级、目标智能体跟踪和变更检测功能。

知识捕获 —— 经验教训会连同语言、主题和标签元数据一起存储。支持通过正则表达式、文本或向量嵌入进行搜索。机构记忆不会在对话结束后消失。

会话跟踪 —— Inventorium 中的 AI 工作会话可以被分叉、生成、链接到待办事项，并通过完整的谱系树进行追踪。每一个工作线程都有一个父级和血缘关系。

语义搜索 —— find_relevant 使用向量嵌入来根据含义（而非仅仅是关键词）呈现待办事项和经验教训。get_context_bundle 让智能体可以在一次调用中获取完整的项目概况。

Related MCP server: Todo MCP Server

安装

pip install omnispindle

安装后可用的 CLI 命令：

• omnispindle-stdio — 用于 Claude Desktop 的 MCP stdio 服务器

• omnispindle / omnispindle-server — 用于已认证端点的 HTTP Web 服务器

Claude Desktop (零配置)

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "omnispindle": {
      "command": "omnispindle-stdio",
      "env": {
        "OMNISPINDLE_MODE": "api",
        "OMNISPINDLE_TOOL_LOADOUT": "basic",
        "MCP_USER_EMAIL": "you@example.com"
      }
    }
  }
}

首次工具调用会打开浏览器进行 Auth0 登录。令牌会保存在本地。仅此而已。

开发

git clone https://github.com/DanEdens/Omnispindle.git
cd Omnispindle
pip install -r requirements.txt
python -m src.Omnispindle.stdio_server

工具

完整配置包含 6 个类别的 33 个工具。使用 OMNISPINDLE_TOOL_LOADOUT 控制可用工具以及智能体的令牌预算。

待办事项管理 (9 个工具)

知识 / 经验教训 (7 个工具)

Inventorium 会话 (8 个工具)

上下文与搜索 (2 个工具)

系统 / 管理 (5 个工具)

自定义代码 (1 个工具)

工具配置 (Loadouts)

设置 OMNISPINDLE_TOOL_LOADOUT 以控制注册内容：

运行模式

通过 OMNISPINDLE_MODE 设置：

• api — 对 madnessinteractive.cc/api 的 HTTP 调用。无需本地数据库。最适合云原生或多用户设置。

• hybrid (默认) — API 优先，带有 MongoDB 后备。在网络不稳定时非常可靠。

• local — 仅直接连接 MongoDB。适合离线开发。

• auto — 基准测试两者并选择较快的一个。

身份验证

零配置设备流：首次工具调用时，会打开浏览器窗口进行 Auth0 登录。令牌保存在本地。后续所有调用均无需任何配置即可完成身份验证。

手动令牌设置 (可选)：

python -m src.Omnispindle.token_exchange

环境变量：

• MADNESS_AUTH_TOKEN 或 AUTH0_TOKEN — 来自 Auth0 设备流的 JWT

• MCP_USER_EMAIL — 用户数据隔离必需

• MADNESS_API_URL — 覆盖 API 基础地址 (默认: https://madnessinteractive.cc/api)

所有数据在数据库层面按用户进行范围划分。你的待办事项永远属于你。

配置

# Operation mode
OMNISPINDLE_MODE=hybrid          # api | hybrid | local | auto
OMNISPINDLE_TOOL_LOADOUT=basic   # see loadouts table above
OMNISPINDLE_FALLBACK_ENABLED=true
OMNISPINDLE_VALIDATE_PROJECT_NAMES=false  # optional: enable slower DB-backed project validation

# Authentication
MADNESS_AUTH_TOKEN=<jwt>
MCP_USER_EMAIL=you@example.com

# Local/hybrid database
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=swarmonomicon

# Real-time events
MQTT_HOST=localhost
MQTT_PORT=1883

生态系统

Omnispindle 是 AI 接口层。工作区的其余部分：

Inventorium — React Web 仪表板和 SwarmDesk 3D 空间工作区。人类使用此工具。它直接通过 REST API 读取待办事项和会话 — 而非 MCP（MCP 仅供 AI 智能体使用）。如果你在点击按钮，你就在 Inventorium 中。如果你是智能体，你就在调用 MCP 工具。

cartogomancy — JS/TS 代码库分析工具 (npm install -g @madnessengineering/cartogomancy)。指向任何 JavaScript 或 TypeScript 项目；获取结构、复杂度、git blame 和交叉引用的丰富 JSON 地图。将该地图输入 SwarmDesk，你的代码库就会变成一座你可以漫步其中的 3D 城市。

SwarmDesk — Inventorium 内部的 3D 空间可视化层。待办事项、会话和 cartogomancy 代码地图被渲染为可探索的架构。你的项目是一个场所，而不是一个列表。

MadnessVR — SwarmDesk 的 Quest 2 VR 版本。戴上头显，以实际几何形状漫步于你的代码库中。这在路线图中，不在发布说明中。但计划已经存在且非常详细。

Cogwyrm — 集成到生态系统中的 AI 聊天伴侣。在对话期间使用 Omnispindle MCP 工具读取和写入共享上下文。

Swarmonomicon — 核心数据库层。MongoDB，swarmonomicon 数据库。所有持久化内容都存在这里。

架构规则

UI (Inventorium, forms, dashboards) → REST API → Database
AI agents (Claude, Cogwyrm, any MCP client) → MCP tools → Backend → Database

永远不要通过 MCP 路由 UI。永远不要从 AI 智能体直接调用 REST API。这种分离是刻意的且具有承载意义。

开发

# Tests
pytest tests/

# Stdio server (Claude Desktop)
python -m src.Omnispindle.stdio_server

# Web server
python -m src.Omnispindle

# Check tool count
python -c "from src.Omnispindle.tool_loadouts import _BASE_LOADOUTS; print(len(_BASE_LOADOUTS['full']), 'tools in full loadout')"

PyPI 发布

# Build and check
python -m build
python -m twine check dist/*

# Publish
python -m twine upload dist/*

隐私与安全

此仓库包含我们生态系统的 Auth0 配置和基础设施即代码。它是开源的，供学习和分叉使用 — 而非直接部署。

如果你确实要为自己的设置运行此系统：

1. 分叉它

2. 替换所有身份验证提供商和凭据

3. 指向你自己的域名和数据库

4. 审查工具权限（我们默认是宽松的）

这是我们实验室的一个工作系统。对于你的系统，请将其变成你自己的。

哲学

大多数人构建的待办事项应用只有 5 个功能。我们构建了一个拥有 33 个 MCP 工具、三种运行模式、会话谱系树、向量嵌入、零配置 OAuth 以及包含在 VR 中漫步代码的路线图的应用。

这是恰到好处的复杂性。每一部分都是承载性的。

当前功能：

• AI 智能体的待办事项管理 — 健壮、可审计、按用户划分

• 跨项目的持久化知识捕获

• 具有完整血缘关系的会话跟踪

• 通过向量嵌入进行语义搜索

• 无需设置指南的零配置 Auth0

即将推出：

• MadnessVR: Quest 2 上的 SwarmDesk

• 通过泰拉瑞亚风格的库存机制教授提示词工程

• cartogomancy → SwarmDesk → VR 作为一条连续的流水线

我们编写严谨的代码。当实用时，我们不惧怕突破界限。

“过度设计？也许吧。缺乏野心？绝不。”