outline-mcp

outline-mcp

M C P サーバーとしてのツリー構造ナレッジベース。

LLM のセッションは一時的なものです。outline-mcp は、永続的で編集可能なナレッジツリーを提供します。セクションとコンテンツノードを閲覧（toc）したり、プロパティで注釈を付けたり、セッションをまたいで発展させたりできます。inject=true のノードは、セッションのコンテキストに自動的に含まれます。

クイックスタート

書籍は、自分で運用する Postgres データベースに保存されます。outline-mcp は現状のまま公開されている個人プロジェクトです。ホスト型のインスタンスや、同梱のデータベースはありません。

cargo install --path crates/outline-mcp

export OUTLINE_MCP_DATABASE_URL=postgres://user:pass@host:5432/outline
outline-mcp migrate          # create / update the schema; run once per upgrade
outline-mcp                  # stdio

データベースが設定されていない場合、データベースに接続できない場合（ホストに到達できない、ログインを拒否された、またはデータベースが存在しないことをメッセージで示します）、あるいはデータベースに対して migrate が実行されていない場合、サーバーは起動を拒否します。--database-url <url> は、すべてのサブコマンドで環境変数を上書きします。

Claude Code（~/.claude.json）

{
  "mcpServers": {
    "outline": {
      "command": "outline-mcp",
      "env": { "OUTLINE_MCP_DATABASE_URL": "postgres://user:pass@host:5432/outline" }
    }
  }
}

共有サーバー（複数のデバイス）

--mcp-http は、MCP のストリーム可能な HTTP トランスポートで同じツールを提供します。すべての書き込みは、書籍ごとのバージョンチェックを伴う単一のデータベーストランザクションとなるため、複数のサーバープロセスやデバイスで同じデータベースを共有できます。

outline-mcp --mcp-http                          # 127.0.0.1:8486
outline-mcp --mcp-http --bind 127.0.0.1:9000

そのアドレスの /mcp をクライアントの接続先に設定します。

{
  "mcpServers": {
    "outline": {
      "type": "http",
      "url": "http://127.0.0.1:8486/mcp"
    }
  }
}

ループバックアドレス以外にバインドするにはトークンが必要です。トークンがない場合、リスナーを開く前に起動を拒否します。

OUTLINE_MCP_HTTP_TOKEN=<token> outline-mcp --mcp-http --bind 0.0.0.0:8486

以降、すべてのリクエストに Authorization: Bearer <token> を含める必要があります。MCP クライアントでリクエストヘッダーを設定する場所に指定してください。TLS の終端処理はリバースプロキシ側の責務です。どちらのトランスポートでもログは stderr に出力され、stdout は stdio プロトコルチャネル専用です。

ブラウザー表示

--mcp-http は、読み取り専用のブラウザー表示も /ui/ で提供します。書棚、各書籍の目次（inject／ステータス／検証／保留中の改訂／リンクのマーカー。アーカイブ済みのサブツリーは指定がない限り非表示）、ノードページ（レンダリングされた本文、プロパティ、双方向のリンク、差分付きの保留中の改訂、履歴）、テキスト検索（8 文字以上の 16 進数からなる UUID の接頭辞にも一致し、#2-3 などの #<toc number> でそのノードを開きます。書棚の検索ボックスではすべての書籍を一度に検索でき、ノードページでは #n と 8 文字の ID が、それぞれクリックして選択できるスニペットとして表示されます）、および書籍の履歴を表示できます。書き込みは一切行わず、スクリプトを実行せず、ほかのホストから何も読み込みません。

OUTLINE_MCP_HTTP_TOKEN が設定されている場合、ブラウザーは HTTP Basic 認証情報を求めます。ユーザー名は任意で、パスワードにトークンを指定します。トークンがない場合（ループバックアドレスへのバインドのみ）、Host が localhost、127.0.0.1、または [::1] のリクエストにのみ応答します。stdio トランスポートにはブラウザー表示はありません。

デーモンとして実行するためのサービス用テンプレートは contrib/systemd/ と contrib/launchd/ にあります（どちらも環境ブロックからデータベース URL を取得します）。docs/runbooks/ には、管理対象外の Fly Postgres アプリを使った Fly.io でのホスティング（fly-io-deploy.md、設定は contrib/fly/fly.toml）、Postgres 導入前の書棚のインポート（data-migration.md）、およびエンドツーエンドのスモークチェックリスト（multi-device-smoke.md）について記載されています。

ワークフロー

shelf  →  select_book  →  toc  →  node_create / node_update / node_move
                                   node_batch_move / node_batch_update / node_query
                                   checklist / import / init / book_update / book_delete / gen_routing
                                   snapshot_create / snapshot_list / snapshot_restore / snapshot_delete
                                   node_history / dump
                                   book_lint / book_stats (read-only health)
                                   node_verify (curation: verification dates)
                                   link_add / link_remove / links (curation: typed links)
                                   revision_propose / revision_show / revision_approve /
                                   revision_reject / revisions_pending (curation: review)

1. init — 新しい空のブックを作成します
2. node_create — セクションとコンテンツノードを追加します（properties は任意）。結果には新しいノードの UUID が含まれ、バッチツールですぐに使用できます
3. toc — 番号付き ID（例：1、2-3）付きの目次を表示します。プロパティでの filter、ブックのルートからの深さを指定する max_depth（1 はルートレベルのみ）、および limit に対応しています。最後の行に省略されたノード数が表示されます。include_archived: true を指定しない限り、アーカイブ済みノードとそのサブツリーは非表示になり（件数は最後の行に表示）、指定すると [archived] の印を付けて表示されます
4. select_book — ブックを選択します。inject=true プロパティを持つノードの本文は自動的に追加されます（下書きノードとアーカイブ済みノード、およびアーカイブ済みセクション配下のすべてのノードは除外されます。出力される目次では、toc と同様にアーカイブ済みのサブツリーが非表示になります）
5. checklist — セクション（またはブック全体）を、チェックボックス付きの Markdown チェックリストとしてエクスポートします。include_archived: true を指定しない限り（または subtree_root 自体がアーカイブ済みの場合を除き）、アーカイブ済みのサブツリーは除外されます
6. node_update — ノードのタイトル、本文、タイプ、プレースホルダー、プロパティ、またはステータスを編集します。ステータスは active、draft（未執筆）、archived（廃止済み。読み取り可能な状態で保持されますが、追加対象にならず、指定がない限り toc / node_query では非表示）です
7. node_move — ノードを移動または削除します。子孫ノードも一緒に移動し、結果に一覧表示されます。dry_run: true を指定すると、変更を加えずに、移動または削除されるすべてのノードと移動前後の位置が表示されます。削除すると、そのノードと各子孫ノードについて履歴に削除が記録されます
8. node_batch_move — 複数のノードを1回のアトミックな呼び出しで移動します（UUID または UUID プレフィックス ID が必要です。ノードを削除するには、action: "remove" を指定して node_move を使用します）。dry_run にも対応しています
9. node_batch_update — 複数のノードのタイトル／本文／タイプ／プロパティ／ステータスをアトミックに更新します
10. node_query — プロパティ値、ステータス（active／draft／archived）、タイプ（section／content）、text（タイトルまたは本文に含まれる大文字と小文字を区別しない部分文字列。CJK を含み、本文で最初に一致した箇所の抜粋付き）、または verified_before（未検証、あるいは指定日時／日付／ミリ秒より前に最後に検証されたノード）でノードを検索します。結果に本文を含めることもできます。アーカイブ済みノードは status: "archived" または include_archived: true を指定した場合のみ返されます
11. import — 以前エクスポートした JSON ファイルからブックをインポートし、ステータス、検証情報、リンク、保留中の改訂を復元します。ファイル内のノード ID は維持されるため、ブック自身のエクスポートを再インポートした場合、変更されるのは差分がある箇所のみです。new_ids: true を指定すると、新しい ID でコピーをインポートします（インポートしたノード間のリンクも再マッピングされます）。ファイルに含まれないノードへのリンクと、改訂ルールに違反する保留中の改訂は破棄され、その旨が報告されます。結果には、作成、更新、削除されたノード数が表示されます（ファイルに含まれないブック内のノードは削除されます）。セクションからエクスポートされたファイルは、ファイル内のマーカー、またはマーカー以前のエクスポートの場合はノード ID から判別され、ブック全体を置き換えるため、force: true を指定しない限り拒否されます
12. gen_routing — すべてのブックから routing プロパティを持つノードを使用して、Markdown ルーティングテーブルを生成します
13. snapshot_create / snapshot_list / snapshot_restore / snapshot_delete — ブック全体のバージョン管理（スナップショットの作成、一覧表示、復元、削除。ラベル付きスナップショットを削除するには force: true が必要です）
14. node_history — ノードごとの変更ログを変更前／変更後の差分付きで表示します
15. dump — ブック全体を JSON ファイルとしてエクスポートします
16. book_delete — ブックとそのノード、履歴、スナップショットを削除します（取り消しできません）。slug が必須です。ノード、履歴、スナップショットのいずれかが存在するブックを削除するには force: true が必要です。dry_run: true を指定すると、削除対象のみが報告されます。確認から削除までの間にブックへの書き込みがあると、何も削除されずに処理が失敗します
17. book_update — ブックのタイトルおよび／または max_depth を変更します（slug が必須です）。既存ノードの深さを下回るように max_depth を引き下げることはできず、その場合は該当するノード名が表示されます。この変更は book_history に book_update エントリとして記録されます
18. book_lint — ブックの読み取り専用の構造チェックを行います（slug の既定値は選択中のブックです）。チェック項目は、ルートにあるコンテンツノード、類似したタイトル（タイトル内の単語に対する Jaccard 係数。CJK では文字ペアを使用。threshold の既定値は 0.6。両方のタイトルが単一トークンであるペアは、タイトルが同一でない限り除外）、大文字／小文字、_、-、スペースのみが異なるプロパティキー、子を持たないセクション、stale_days（既定値は 90）を超えて更新されていない下書き、およびリンク先がブック内にないリンク（dangling_links）です。アーカイブ済みノードとアーカイブ済みセクション配下のすべてのノードは、すべてのチェックで無視されます。checks で一部のチェックを実行できます。limit（既定値は 50）はチェックごとの検出数を制限し、残りの件数も表示します。プログラム用には format: "json" を指定します
19. book_stats — ブックの読み取り専用統計情報を表示します。ノード数、最大／平均深度、セクションあたりの子ノード数（最大、平均、ヒストグラム）、ステータス別の件数、追加対象ノード、更新時期、異なるプロパティキーの数、リンクが含まれます。プログラム用には format: "json" を指定します
20. node_verify — ノードが引き続き現状と一致していることを確認した記録を残します（node_ids、任意の by）。コンテンツや最終編集時刻には触れず、検証時刻を現在時刻に設定します。ノードごとに履歴エントリが1件作成され、コミットは1回です。node_query の verified_before と組み合わせると、最近確認されていないノードを一覧表示できます
21. link_add / link_remove / links — ブック内のノード間に型付きリンクを設定します（supersedes、superseded_by、see_also、merged_from などの rel を指定します。使用できる文字は a-z 0-9 _ - のいずれか1～40文字です）。リンクは対象ノードの ID に紐づくため、対象ノードを移動しても維持されます。ノードを削除すると、そのノードを指すリンクは削除されます（リンクを持つ各ノードには同じコミット内で更新が履歴に記録され、結果には削除されたリンク数が示されます）。links は送信リンクとバックリンクを一覧表示します。node_query では linked_to（および link_rel）を指定でき、JSON には links／backlinks が含まれます（各接続先のステータスも含み、アーカイブ済みかどうかも示されます）。リンクの変更は履歴に記録されますが、node_verify と同様にノードの updated_at は変更されません
22. revision_propose / revision_show / revision_approve / revision_reject / revisions_pending — レビュー中の変更を扱います。revision_propose は、提案するタイトル／本文／プロパティの変更を（任意の by、note とともに）ノードに紐づけますが、ノード自体は変更しません。承認されるまで、追加内容、toc、dump、その他すべての読み取り処理には現在のコンテンツが使用されます。1つのノードにつき保留中の改訂は1件です（replace: true を指定すると差し替えられます）。アーカイブ済みノードでは受け付けません。revision_show は現在のコンテンツとの差分（タイトル、本文の統合差分、追加／変更／削除されたプロパティ）を表示し、ノードが変更されている場合は警告します。revision_approve は改訂を適用し（node_update と同じように検証されます）、履歴エントリを1件作成します。古くなった改訂は force: true を指定しない限り拒否されます。revision_reject は改訂を破棄し、revisions_pending は保留中の改訂を一覧表示します。提案と却下は履歴に記録されますが、updated_at は変更されません。node_query は保留中の改訂の概要を表示し、book_lint は stale_proposals（stale_days より古いもの、古くなったもの、またはノードがアーカイブされた後も残っているもの。最後のケースでは却下のみ可能）を報告し、book_stats はその件数を集計します

ノード ID

toc は、人が読みやすい番号付き ID を割り当てます。

1. Coding Standards
  1-1. Naming Conventions
  1-2. Error Handling
2. Testing
  2-1. Unit Tests
  2-2. Integration Tests

これらの ID（1、1-2、2-1 など）は、ほとんどのツールで使用できます。フォールバックとして、完全な UUID とタイトルの部分一致もサポートされています。

注：node_batch_move と node_batch_update では、UUID または UUID のプレフィックス ID が必要です。ツリーの変更中に位置がずれるのを防ぐため、階層型の toc ID は意図的に拒否されます。

ノードのプロパティ

ノードには、メタデータとしてキーと値のプロパティを設定できます。

node_create  title="My Rule"  properties={"inject": "true", "scope": "rust"}

• inject=true — ノード本文が select_book の出力に自動的に含まれます（コンテキスト注入）
• routing=<scene> — gen_routing の出力対象としてノードを指定します。複数のシーンを指定するには | を使用します（例：routing="testing|TDD"）
• routing_ref=<text> — ルーティングテーブル内のデフォルトの §ID Title 参照を上書きします（例：routing_ref="select_book で全体参照"）
• 値が "true" のプロパティは、toc でタグとして表示されます：1. My Rule [inject]
• toc はフィルタリングをサポートしています：filter={"inject": "true"} を指定すると、一致するノードのみが表示されます
• プロパティは JSON のエクスポート／インポート時に保持されます

アーキテクチャ

このリポジトリは、3 つのクレートで構成される Cargo ワークスペースです。rmcp に依存しない SDK（outline-mcp-core）、MCP プロトコルレイヤー（outline-mcp-rmcp）、サーバーバイナリ（outline-mcp）です。

crates/
├── outline-mcp-core/     # SDK crate (library, no rmcp dependency)
│   └── src/
│       ├── domain/       # Core model (TemplateBook, TemplateNode, NodeId)
│       │   ├── model/    # Aggregate root + value objects
│       │   ├── error.rs  # Domain errors
│       │   └── store.rs  # BookStore / SnapshotStore ports
│       ├── application/  # Use cases
│       │   ├── service.rs # BookService (one commit per write)
│       │   └── eject.rs  # EjectService (Markdown/JSON export & import)
│       └── infra/        # Persistence
│           ├── pg_store.rs     # Postgres adapter (sqlx); migrations/ holds the schema
│           ├── memory_store.rs # In-memory adapter (tests)
│           └── shelf_import.rs # Reader for pre-Postgres shelves (import-shelf)
├── outline-mcp-rmcp/     # MCP layer (rmcp; stdio + streamable HTTP)
│   └── src/
│       ├── server.rs     # Transports (run / run_http) + server type
│       ├── tools.rs      # Tool handlers
│       └── resources.rs  # Resource handlers
└── outline-mcp/          # Binary crate (CLI entry point)
    └── src/
        ├── main.rs       # Flag parsing (--database-url / --mcp-http / --bind), transport dispatch
        ├── db.rs         # Database URL resolution and connection errors
        ├── migrate_db.rs # `migrate` subcommand
        └── import_shelf.rs # `import-shelf` subcommand

rmcp を取り込まずにツリー／スナップショット／変更履歴のロジックを組み込みたい下流アプリケーションは、outline-mcp-core に直接依存できます。

[dependencies]
outline-mcp-core = "0.12"

エクスポート形式

Markdown（デフォルト）

# My Runbook

## Design

- [ ] Define requirements
  > requirements list: ___
- [ ] API design
  REST endpoints

JSON

import で再インポートできる、ツリー構造の形式です。

{
  "title": "My Runbook",
  "max_depth": 4,
  "nodes": [
    {
      "id": "0b8c…-uuid",
      "title": "Design",
      "node_type": "section",
      "updated_at": "2026-10-19T08:00:00.000Z",
      "children": [...]
    },
    {
      "id": "5d1e…-uuid",
      "title": "Old design",
      "node_type": "content",
      "status": "archived",
      "verified_at": "2026-09-01T00:00:00.000Z",
      "verified_by": "alice",
      "links": [{ "rel": "superseded_by", "target": "0b8c…-uuid" }]
    }
  ]
}

タイトル、タイプ、本文、プレースホルダー、子ノード、プロパティに加え、各ノードには status（アクティブな場合は省略）、updated_at、verified_at／verified_by、links（リンク先は同じファイル内の id）、保留中の proposal が含まれます。これらは空の場合は省略されるため、以前のバージョンのファイルも引き続きインポートできます。完全なラウンドトリップを行うには、dump（または include_archived: true を指定した checklist）でエクスポートしてください。checklist はデフォルトでアーカイブ済みノードを省略するため、そのようなファイルをインポートすると、ブックからそれらのノードが削除されます（インポート結果に件数が表示されます）。1 つのセクションをエクスポートすると、そのセクションは subtree_root として記録されます。force: true を指定しない限り、import はそのようなファイルを拒否します。

アップグレード

シェルフディレクトリから（0.14 以前）

以前のバージョンでは、各ブックをシェルフディレクトリ内の {slug}.json として保存し、履歴を {slug}.changelog.json／{slug}.events.db に、スナップショットを {slug}.snap.*.json に保存していました。サーバーはこのディレクトリを読み込まなくなりました。データベースに一度インポートしてください。

outline-mcp migrate
outline-mcp import-shelf --shelf <shelf-dir>            # every book
outline-mcp import-shelf --shelf <shelf-dir> --slug rust  # one book

インポーターは各ブックについて、ツリー、変更履歴、元のタイムスタンプ付きのスナップショットをコピーします。その後、データベースからブックを読み戻し、ソースとデータベースを比較した行をブックごとに 1 行出力します。比較項目は、ノード数、すべてのノードの内容と位置に対するハッシュ、履歴エントリ、スナップショットです。いずれかのブックで失敗または差異がある場合は、ゼロ以外の終了コードで終了します。履歴はイベントログを再生するのではなく、エントリごとに読み込まれるため、イベントログを再生できなくなったブック（#2 で説明した警告が出るブック）も、履歴全体を含めてインポートされます。

データベースにすでに存在する slug は拒否されます。上書きするには --replace を指定します。シェルフディレクトリは読み込まれるだけで、変更されることはありません。レポートを確認するまで、そのディレクトリを保管してください。

ライセンス

以下のいずれかのライセンスの下でライセンスされています。

• Apache License, Version 2.0
• MIT License

ライセンスは任意で選択できます。