FastMCP Todo Server

Omnispindle

意図的に、見事なまでに間違った方向へ進んだ todo システムです。

Omnispindle は Madness Interactive エコシステムの連携を支える中核です。38 個のツールを備えた Python FastMCP サーバーで、AI エージェントがタスクを管理し、ナレッジを記録し、セッションを調整し、壮大な目標（クエスト）を追跡し、標準化された単一のインターフェースからワークショップ全体を操作できます。PyPI パッケージとして提供されています。Auth0 と連携済みです。MCP 設定が存在する場所ならどこでも動作します。

始まりは「todo をきちんとやろう」でした。そして、複数のプロジェクトからなる AI 支援開発ラボの中枢神経系になりました。どちらも問題ありません。

---

実際にできること

Todo 管理 — ほかのあらゆる機能を可能にする、地味な部分です。エージェントは、エコシステム内のあらゆるプロジェクトで、完全なメタデータ、優先度、対象エージェントの追跡、変更検知を含めて、タスクの作成、検索、更新、完了、監査を行えます。

ナレッジの記録 — 学んだ教訓を、言語、トピック、タグのメタデータとともに保存します。正規表現、テキスト、ベクトル埋め込みで検索できます。会話が終わっても、組織の記憶は失われません。

セッションの追跡 — Inventorium の AI 作業セッションを分岐、作成、todo へのリンク付けができ、完全な系譜ツリーをたどれます。すべての作業スレッドに親と系譜があります。

セマンティック検索 — find_relevant は、キーワードだけでなく意味に基づいて、ベクトル埋め込みを使って todo や教訓を表示します。get_context_bundle を使うと、エージェントはプロジェクト全体の状況を 1 回の呼び出しで把握できます。

---

インストール

pip install omnispindle

インストール後に使用できる CLI コマンド：

• omnispindle-stdio — Claude Desktop 用の MCP stdio サーバー
• omnispindle / omnispindle-server — 認証済みエンドポイント用の HTTP ウェブサーバー

Claude Desktop（設定不要）

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "omnispindle": {
      "command": "omnispindle-stdio",
      "env": {
        "OMNISPINDLE_MODE": "api",
        "OMNISPINDLE_TOOL_LOADOUT": "basic",
        "MCP_USER_EMAIL": "[email protected]"
      }
    }
  }
}

最初のツール呼び出し時に、ブラウザーが開いて Auth0 へのログインを求められます。トークンはローカルに保存されます。以上です。

開発

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

---

ツール

全 38 個のツールを 7 つのカテゴリに分類しています。OMNISPINDLE_TOOL_LOADOUT を使って、利用できる機能とエージェントのトークン予算を調整できます。

Todo 管理（9 個のツール）

ツール	機能
add_todo	プロジェクト、優先度、対象エージェント、メモ、メタデータを指定してタスクを作成します
query_todos	MongoDB 形式のフィルタークエリ。プロジェクション、上限、オフセット、変更検知用の since、依存関係サブグラフのたどり直しに使う graph_root を指定できます
update_todo	任意のフィールドをパッチします。メタデータはディープマージされます。依存関係のリンク付け用に、配列フィールド（例：metadata.blockers）で $push／$pull をサポートします
delete_todo	タスクを削除します
get_todo	ID を指定して単一のタスクを取得します
complete_todo	任意のコメントを付けてレビュー待ちにし、監査ログに記録します。ステータスは completed ではなく review に設定されます
list_todos_by_status	ステータスで絞り込みます：pending initial in_progress blocked review completed
search_todos	トークン化された複数語のあいまいテキスト検索を行います
list_project_todos	指定したプロジェクトの最近のタスクを表示します

ナレッジ／教訓（7 個のツール）

ツール	機能
add_lesson	言語、トピック、タグを指定して教訓を記録します
get_lesson	ID を指定して取得します
update_lesson	教訓の内容またはメタデータにパッチを適用します
delete_lesson	削除します
search_lessons	教訓の各フィールドを対象にテキスト検索します
grep_lessons	正規表現パターンで検索します
list_lessons	すべての教訓を一覧表示します。概要用の簡易モードもあります

Inventorium セッション（8 ツール）

ツール	機能
inventorium_sessions_list	セッションを一覧表示します。プロジェクトで絞り込むこともできます
inventorium_sessions_get	ID を指定してセッションを取得します
inventorium_sessions_create	新しい AI 作業セッションを開始します
inventorium_sessions_spawn	親セッションから子セッションを作成し、todo にリンクします
inventorium_sessions_fork	メッセージを引き継ぐかどうかを指定して、セッションをフォークします
inventorium_sessions_genealogy	セッションの祖先・子孫をすべてたどります
inventorium_sessions_tree	プロジェクトのセッションツリーを視覚的に表示します
inventorium_todos_link_session	todo をセッションにリンクします

クエストシステム（5 ツール）

ツール	機能
create_quest	大きな目標をまとめるコンテナを作成します（Quest → Chains → Todos）。複数ステップの目標には add_todo の代わりに使用します
check_quest	進捗レポート：完了率、チェーンごとのステータス、次のアクション、ブロッカーを表示します。エージェントの状況把握に役立つツールです
list_quests	ステータスやプロジェクトで絞り込んでクエストを一覧表示します
link_quest	既存の todo を後からクエストチェーンに追加します（必要に応じてチェーンを作成します）
update_quest	クエストのフィールド（name、description、status、success_criteria、metadata）を更新します

コンテキストと検索（4 ツール）

ツール	機能
get_context_bundle	1 回の呼び出しで、最近の todo、教訓、セッション状態、プロジェクト統計をエージェントの作業コンテキスト向けに取得します
find_relevant	todo と教訓を対象に、意味的類似性で検索します。関連性のしきい値を超えるものがない場合は、正直に空の結果を返します。正規表現によるノイズの多いフォールバックはありません
preflight_rag	タスク開始前の教訓チェックです。作業開始前に呼び出し、過去の解決策と落とし穴を分類します
write_agent_journal / read_agent_journal	エージェント用の永続的なジャーナルです。他のエージェントが読めるメモを残し、エージェント間の連携に使います

システム／管理（5 ツール）

ツール	機能
query_todo_logs	監査ログを照会します。タイプ、プロジェクト、日付範囲で絞り込めます
list_projects	ファイルシステムから既知のプロジェクトを列挙します
explain / add_explanation	トピック解説システムです。永続的なナレッジカードを管理します
point_out_obvious	皮肉の度合いを設定して所見を記録します。自動実行中に既知の問題を示すのに便利です

カスタムコード（1 ツール）

ツール	機能
bring_your_own	Python、JavaScript、またはシェルの関数を、実行時にライブ MCP ツールとして注入します

---

ツールの構成

OMNISPINDLE_TOOL_LOADOUT を設定して、登録するツールを制御します。

構成	ツール数	用途
full	38	すべて
basic	15	todo の基本的な CRUD、コンテキスト、クエストシステム
minimal	4	追加、照会、取得、完了済みとしてマーク
lessons	8	ナレッジ管理のみ
admin	16	管理タスクとセッション管理
write_only	6	作成／更新／削除のみ
read_only	16	照会／取得のみ
lightweight	13	トークン効率に優れた基本機能
agent_preflight	6	セッション開始時：コンテキストバンドル、RAG チェック、todo 操作
refine	13	todo の拡充：監査と不足しているメタデータの補完

---

動作モード

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 のベース URL を上書きします（デフォルト：https://madnessinteractive.cc/api）

すべてのデータは、データベースレベルでユーザーごとにスコープが設定されています。あなたの ToDo は、あなた専用です。

---

設定

# 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>
[email protected]

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

# Real-time events
MQTT_HOST=localhost
MQTT_PORT=1883

---

エコシステム

Omnispindle は AI インターフェースレイヤーです。ワークショップの他の構成要素は次のとおりです。

Inventorium — React ウェブダッシュボードと SwarmDesk 3D 空間ワークスペースです。人間が使用します。REST API を介して ToDo とセッションを直接読み込みます。MCP は使用しません。MCP は AI エージェント専用です。ボタンをクリックしているなら、Inventorium を使っています。エージェントなら、MCP ツールを呼び出しています。

cartogomancy — JS/TS コードベース分析ツール（npm install -g @madnessengineering/cartogomancy）です。任意の JavaScript または TypeScript プロジェクトを指定すると、構造、複雑さ、git blame、相互参照を網羅した JSON マップが得られます。そのマップを SwarmDesk に渡すと、コードベースが歩き回れる 3D の街になります。

SwarmDesk — Inventorium 内の 3D 空間ビジュアライゼーションレイヤーです。ToDo、セッション、cartogomancy のコードマップを、探索可能なアーキテクチャとして描画します。プロジェクトをリストではなく、場所として表現します。

MadnessVR — SwarmDesk の Quest 2 VR 版です。ヘッドセットを装着して、コードベースを実際のジオメトリとして歩き回ります。これはロードマップに載っており、リリースノートにはまだありません。ただし、計画は存在し、詳細まで詰められています。

MadQTT — ワークショップの MQTT + MongoDB イベントストリームをリアルタイムで表示するターミナル TUI（pip install madqtt）です。あらゆるマシンのエージェントセッション、ツール呼び出し、失敗を、情報の洪水ではなくリアルタイムで読み取れます。

Madness Desktop — ワークショップと連携する GitHub Desktop のフォークです。組み合わせ可能な git-hook ロードアウト、マシン間で共有される MQTT コミットイベント、git クライアント内に表示されるワークショップの ToDo を備えています。

Swarmonomicon — 中核となるデータベースレイヤーです。MongoDB の swarmonomicon データベースです。永続化されるデータはすべてここに保存されます。

アーキテクチャのルール

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

UI を MCP 経由でルーティングしてはいけません。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. ツールの権限を確認します（デフォルトでは寛容な設定です）

これは私たちのラボで稼働しているシステムです。あなたの環境では、あなた自身に合ったものにしてください。

---

哲学

現在利用できる機能：

• AI エージェント向けの ToDo 管理 — 堅牢で、監査済み、ユーザーごとに分離
• プロジェクトをまたいだ永続的なナレッジの記録
• 系譜を完全に追跡できるセッション管理
• ベクトル埋め込みによるセマンティック検索
• セットアップガイドが不要なゼロコンフィグの Auth0

今後の予定：

• MadnessVR：Quest 2 で動作する SwarmDesk
• Terraria 風のインベントリメカニクスを通じたプロンプトエンジニアリングの指導
• cartogomancy → SwarmDesk → VR をつなぐ、一貫したパイプライン

私たちは慎重にコードを書きます。実用性があるなら、限界を押し広げることもいといません。

---

「過剰設計？ そうかもしれません。志が低い？ そんなことは決してありません。」