Omnispindle MCP server
2026년 11월 3일 커밋AI agent이 여러 프로젝트 생태계에서 작업을 관리하고, 지식을 캡처하며, 작업 세션을 추적하고, 시맨틱 검색을 수행할 수 있도록 지원합니다.
다른 이름 MadnessEngineering/Omnispindle
- 스타
- 10
- Tools
- 46
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 3일
- 라이선스
- —
Omnispindle MCP란?
Omnispindle은(는) MCP server입니다. AI agent이 여러 프로젝트 생태계에서 작업을 관리하고, 지식을 캡처하며, 작업 세션을 추적하고, 시맨틱 검색을 수행할 수 있도록 지원합니다. 46개 도구를 제공합니다. 예: add_todo, query_todos, update_todo.
프로젝트 README에서 생성된 요약
Omnispindle MCP server 정보
Omnispindle은 여러 프로젝트 생태계 내에서 작동하는 AI agent를 위한 조정 레이어 역할을 합니다. 작업 관리, 조직 지식 캡처, 그리고 상세한 계보 트리(genealogy tree)를 통한 작업 세션 추적을 위한 표준화된 인터페이스를 제공합니다. 이 시스템은 agent가 서로 다른 세션 전반에 걸쳐 학습한 교훈과 프로젝트 진행 상황을 지속적인 메모리로 유지하기를 원하는 개발자를 위해 설계되었습니다.
사용자는 이 server를 Claude Desktop을 위한 로컬 stdio 프로세스로 배포하거나 HTTP 웹 server로 배포할 수 있습니다. api, hybrid, local, auto를 포함한 다양한 운영 모드를 지원하여 클라우드 네이티브 설정이나 MongoDB를 이용한 오프라인 개발이 모두 가능합니다. 인증은 Auth0를 통해 처리되며, 첫 번째 도구 호출 시 브라우저를 열어 로그인하는 zero-config device flow 방식을 사용합니다.
server는 7개 카테고리에 걸쳐 38개의 도구를 제공하며, 토큰 예산 관리를 위해 basic, minimal, admin과 같은 특정 loadout을 사용하여 도구를 제한할 수 있습니다. 주요 기능으로는 find_relevant 도구를 통한 벡터 임베딩 기반의 시맨틱 검색, 복잡한 todo 쿼리, 그리고 quest 시스템을 이용한 epic goal 생성 기능이 있습니다.
활용 사례
- 1복잡한 작업 계층 관리agent가 개별 작업 대신 quest 시스템을 사용하여 다단계 목표를 생성할 수 있습니다.
- 2효율적인 프로젝트 컨텍스트 검색개발자가 단일 명령으로 agent에게 최근 프로젝트 데이터를 모두 수집하도록 지시할 수 있습니다.
- 3장기적인 프로젝트 메모리 유지agent가 단순 키워드가 아닌 시맨틱 의미를 사용하여 특정 기술적 교훈을 저장하고 검색할 수 있습니다.
- 4AI 작업 계보 추적사용자가 agent에게 다양한 작업 세션의 이력과 연결 관계를 매핑하도록 요청할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Omnispindle MCP 도구 46
README에서 감지됨add_todoquery_todosupdate_tododelete_todoget_todocomplete_todolist_todos_by_statussearch_todoslist_project_todosadd_lessonget_lessonupdate_lesson
| add_todo | — | |
| query_todos | — | |
| update_todo | — | |
| delete_todo | — | |
| get_todo | — | |
| complete_todo | — | |
| list_todos_by_status | — | |
| search_todos | — | |
| list_project_todos | — | |
| add_lesson | — | |
| get_lesson | — | |
| update_lesson | — |
도구 46개 모두 보기도구 수 줄이기
delete_lessonsearch_lessonsgrep_lessonslist_lessonsinventorium_sessions_listinventorium_sessions_getinventorium_sessions_createinventorium_sessions_spawninventorium_sessions_forkinventorium_sessions_genealogyinventorium_sessions_treeinventorium_todos_link_sessioncreate_questcheck_questlist_questslink_questupdate_questget_context_bundlefind_relevantpreflight_ragquery_todo_logslist_projectspoint_out_obviousbring_your_ownfullbasicminimallessonsadminwrite_onlyread_onlylightweightagent_preflightrefine
| delete_lesson | — | |
| search_lessons | — | |
| grep_lessons | — | |
| list_lessons | — | |
| inventorium_sessions_list | — | |
| inventorium_sessions_get | — | |
| inventorium_sessions_create | — | |
| inventorium_sessions_spawn | — | |
| inventorium_sessions_fork | — | |
| inventorium_sessions_genealogy | — | |
| inventorium_sessions_tree | — | |
| inventorium_todos_link_session | — | |
| create_quest | — | |
| check_quest | — | |
| list_quests | — | |
| link_quest | — | |
| update_quest | — | |
| get_context_bundle | — | |
| find_relevant | — | |
| preflight_rag | — | |
| query_todo_logs | — | |
| list_projects | — | |
| point_out_obvious | — | |
| bring_your_own | — | |
| full | — | |
| basic | — | |
| minimal | — | |
| lessons | — | |
| admin | — | |
| write_only | — | |
| read_only | — | |
| lightweight | — | |
| agent_preflight | — | |
| refine | — |
구성
MADNESS_AUTH_TOKENMCP_USER_EMAILMONGODB_DBMONGODB_URIMQTT_HOSTMQTT_PORTOMNISPINDLE_FALLBACK_ENABLEDOMNISPINDLE_MODEOMNISPINDLE_TOOL_LOADOUTOMNISPINDLE_VALIDATE_PROJECT_NAMES
| 이름 | 설명 | 유형 |
|---|---|---|
| MADNESS_AUTH_TOKEN | — | |
| MCP_USER_EMAIL | — | |
| MONGODB_DB | — | |
| MONGODB_URI | — | |
| MQTT_HOST | — | |
| MQTT_PORT | — | |
| OMNISPINDLE_FALLBACK_ENABLED | — | |
| OMNISPINDLE_MODE | — | |
| OMNISPINDLE_TOOL_LOADOUT | — | |
| OMNISPINDLE_VALIDATE_PROJECT_NAMES | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능madnessengineering/omnispindle is public and reachablegithub.com/madnessengineering/omnispindle ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)No license결함 발견
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-03github.com/madnessengineering/omnispindle ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음46 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기Omnispindle
A todo system that went wonderfully, intentionally wrong.
Omnispindle is the coordination spine of the Madness Interactive ecosystem — a Python FastMCP server with 38 tools that lets AI agents manage tasks, capture knowledge, coordinate sessions, track epic goals (quests), and navigate the whole workshop from a single, standardized interface. PyPI packaged. Auth0 integrated. Runs anywhere a MCP config lives.
It started as "let's do todos properly." It became the central nervous system for a multi-project AI-assisted development lab. Both of these things are fine.
What it actually does
Todo management — the boring part that enables everything else. Agents can create, query, update, complete, and audit tasks across any project in the ecosystem with full metadata, priority, target agent tracking, and change detection.
Knowledge capture — lessons learned get stored with language, topic, and tag metadata. Searchable by regex, text, or vector embedding. The institutional memory doesn't evaporate when the conversation ends.
Session tracking — AI work sessions in Inventorium can be forked, spawned, linked to todos, and traced through a full genealogy tree. Every thread of work has a parent and a lineage.
Semantic search — find_relevant uses vector embeddings to surface todos and lessons by meaning, not just keywords. get_context_bundle gives an agent the full project picture in one call.
Installation
pip install omnispindle
CLI commands available after install:
omnispindle-stdio— MCP stdio server for Claude Desktopomnispindle/omnispindle-server— HTTP web server for authenticated endpoints
Claude Desktop (zero config)
Add to claude_desktop_config.json:
{
"mcpServers": {
"omnispindle": {
"command": "omnispindle-stdio",
"env": {
"OMNISPINDLE_MODE": "api",
"OMNISPINDLE_TOOL_LOADOUT": "basic",
"MCP_USER_EMAIL": "you@example.com"
}
}
}
}
First tool call opens your browser for Auth0 login. Token saves locally. That's it.
Development
git clone https://github.com/DanEdens/Omnispindle.git
cd Omnispindle
pip install -r requirements.txt
python -m src.Omnispindle.stdio_server
Tools
Full loadout is 38 tools across 7 categories. Control what's available — and your agent's token budget — with OMNISPINDLE_TOOL_LOADOUT.
Todo Management (9 tools)
| Tool | What it does |
|---|---|
add_todo |
Create a task with project, priority, target agent, notes, and metadata |
query_todos |
MongoDB-style filter queries with projection, limit, offset, since change detection, and graph_root for dependency subgraph traversal |
update_todo |
Patch any fields; metadata is deep-merged. Supports $push/$pull on array fields (e.g. metadata.blockers) for dependency linking |
delete_todo |
Remove a task |
get_todo |
Fetch a single task by ID |
complete_todo |
Stage for review with optional comment; writes to audit log. Sets status to review, not completed |
list_todos_by_status |
Filter by status: pending initial in_progress blocked review completed |
search_todos |
Tokenized multi-word fuzzy text search |
list_project_todos |
Recent tasks for a specific project |
Knowledge / Lessons (7 tools)
| Tool | What it does |
|---|---|
add_lesson |
Capture a lesson with language, topic, and tags |
get_lesson |
Fetch by ID |
update_lesson |
Patch lesson content or metadata |
delete_lesson |
Remove |
search_lessons |
Text search across lesson fields |
grep_lessons |
Regex pattern search |
list_lessons |
Browse all lessons, with brief mode for summaries |
Inventorium Sessions (8 tools)
| Tool | What it does |
|---|---|
inventorium_sessions_list |
List sessions, optionally filtered by project |
inventorium_sessions_get |
Fetch a session by ID |
inventorium_sessions_create |
Start a new AI work session |
inventorium_sessions_spawn |
Spawn a child session from a parent, linked to a todo |
inventorium_sessions_fork |
Fork a session with optional message inheritance |
inventorium_sessions_genealogy |
Full ancestor/descendant trace for a session |
inventorium_sessions_tree |
Visual session tree for a project |
inventorium_todos_link_session |
Link a todo to a session |
Quest System (5 tools)
| Tool | What it does |
|---|---|
create_quest |
Create an epic goal container (Quest → Chains → Todos). Use instead of add_todo for multi-step objectives |
check_quest |
Progress report: % complete, per-chain status, next actions, blockers. Agent orientation tool |
list_quests |
List quests filtered by status/project |
link_quest |
Add an existing todo to a quest chain retroactively (creates chain on demand) |
update_quest |
Update quest fields: name, description, status, success_criteria, metadata |
Context & Search (4 tools)
| Tool | What it does |
|---|---|
get_context_bundle |
One call: recent todos, lessons, session state, project stats for an agent's working context |
find_relevant |
Semantic similarity search across todos and lessons. Returns honest empty when nothing clears the relevance threshold — no regex fallback noise |
preflight_rag |
Pre-task lessons check: call before starting work, classifies past solutions vs pitfalls |
write_agent_journal / read_agent_journal |
Persistent agent journal — leave notes readable by other agents for cross-agent coordination |
System / Admin (5 tools)
| Tool | What it does |
|---|---|
query_todo_logs |
Audit log queries: filter by type, project, date range |
list_projects |
Enumerate known projects from filesystem |
explain / add_explanation |
Topic explanation system: persistent knowledge cards |
point_out_obvious |
Logs an observation with configurable sarcasm. Useful for marking known issues during automated runs. |
Custom Code (1 tool)
| Tool | What it does |
|---|---|
bring_your_own |
Inject a Python, JavaScript, or shell function as a live MCP tool at runtime |
Tool Loadouts
Set OMNISPINDLE_TOOL_LOADOUT to control what's registered:
| Loadout | Tools | Use case |
|---|---|---|
full |
38 | Everything |
basic |
15 | Core todo CRUD + context + quest system |
minimal |
4 | Add, query, get, mark complete |
lessons |
8 | Knowledge management only |
admin |
16 | Admin tasks + session management |
write_only |
6 | Create/update/delete only |
read_only |
16 | Query/get only |
lightweight |
13 | Token-optimized core |
agent_preflight |
6 | Session startup: context bundle, RAG check, todo ops |
refine |
13 | Todo enrichment: audit + fill missing metadata |
Operation Modes
Set via OMNISPINDLE_MODE:
api— HTTP calls tomadnessinteractive.cc/api. No local database needed. Best for cloud-native or multi-user setups.hybrid(default) — API-first with MongoDB fallback. Reliable when the network isn't.local— Direct MongoDB connections only. Good for offline development.auto— Benchmarks both and picks the faster one.
Authentication
Zero-config device flow: On first tool call, a browser window opens for Auth0 login. Token is saved locally. All subsequent calls are authenticated without any configuration.
Manual token setup (optional):
python -m src.Omnispindle.token_exchange
Environment variables:
MADNESS_AUTH_TOKENorAUTH0_TOKEN— JWT from Auth0 device flowMCP_USER_EMAIL— required for per-user data isolationMADNESS_API_URL— override API base (default:https://madnessinteractive.cc/api)
All data is scoped per user at the database level. Your todos stay yours.
Configuration
# 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
Ecosystem
Omnispindle is the AI interface layer. The rest of the workshop:
Inventorium — React web dashboard and SwarmDesk 3D spatial workspace. Humans use this. It reads todos and sessions via the REST API directly — not MCP, which is strictly for AI agents. If you're clicking buttons, you're in Inventorium. If you're an agent, you're calling MCP tools.
cartogomancy — JS/TS codebase analysis tool (npm install -g @madnessengineering/cartogomancy). Point it at any JavaScript or TypeScript project; get back a rich JSON map of structure, complexity, git blame, and cross-references. Feed that map to SwarmDesk and your codebase becomes a 3D city you can walk through.
SwarmDesk — The 3D spatial visualization layer inside Inventorium. Todos, sessions, and cartogomancy code maps rendered as explorable architecture. Your project as a place, not a list.
MadnessVR — Quest 2 VR version of SwarmDesk. Put on the headset, walk through your codebase as actual geometry. This one is on the roadmap, not the release notes. But the plan exists and it's detailed.
MadQTT — Live terminal TUI for the workshop's MQTT + MongoDB event stream (pip install madqtt). Agent sessions, tool calls, and failures from every machine, readable in real time instead of a firehose.
Madness Desktop — GitHub Desktop fork wired into the workshop: composable git-hook loadouts, MQTT commit events shared across machines, and live workshop todos inside the git client.
Swarmonomicon — The core database layer. MongoDB, swarmonomicon database. Everything persistent lives here.
The architecture rule
UI (Inventorium, forms, dashboards) → REST API → Database
AI agents (Claude, any MCP client) → MCP tools → Backend → Database
Never route UI through MCP. Never call the REST API directly from an AI agent. The separation is intentional and load-bearing.
Development
# 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 Publishing
# Build and check
python -m build
python -m twine check dist/*
# Publish
python -m twine upload dist/*
Privacy & Security
This repo contains Auth0 configs and infrastructure-as-code for our ecosystem. It's open source for learning and forking — not for deploying as-is.
If you're actually running this for your own setup:
- Fork it
- Replace all auth providers and credentials
- Point it at your own domain and database
- Review tool permissions (we're permissive by default)
This is a working system for our lab. For yours, make it yours.
Philosophy
Working now:
- Todo management for AI agents — robust, audited, per-user
- Persistent knowledge capture across projects
- Session tracking with full lineage
- Semantic search via vector embeddings
- Zero-config Auth0 that doesn't require a setup guide
Coming:
- MadnessVR: SwarmDesk on Quest 2
- Teaching prompt engineering through Terraria-style inventory mechanics
- cartogomancy → SwarmDesk → VR as one continuous pipeline
We write careful code. We're not afraid to push the boundaries when it's practical.
"Over-engineered? Maybe. Under-ambitious? Never."
Omnispindle MCP 질문
Omnispindle MCP는 어떤 도구를 제공하나요?
46개 도구를 제공합니다. 예: add_todo, query_todos, update_todo, delete_todo, get_todo.
Omnispindle을 어떻게 설치하나요?
PyPI를 통해 pip install omnispindle 명령어로 설치할 수 있습니다.
인증은 어떻게 이루어지나요?
Zero-config device flow를 사용합니다. 첫 번째 도구 호출 시 Auth0 로그인을 위한 브라우저가 열리며, 토큰은 로컬에 저장됩니다.
agent가 사용할 수 있는 도구 수를 제한할 수 있나요?
네, OMNISPINDLE_TOOL_LOADOUT 환경 변수를 사용하여 도구 구성을 제어함으로써 토큰 예산을 관리할 수 있습니다.
운영 모드에는 어떤 것들이 있나요?
api (HTTP 호출), hybrid (API 우선 및 MongoDB 폴백), local (직접 MongoDB 연결), auto (두 방식 모두 벤치마킹) 모드를 지원합니다.