outline-mcp

Tree-structured knowledge base as an MCP server.

LLM sessions are ephemeral. outline-mcp gives them a persistent, editable knowledge tree — sections and content nodes that can be browsed (toc), annotated with properties, and evolved across sessions. Nodes with inject=true are automatically included in session context.

Quick Start

cargo install --path .

Claude Code (~/.claude.json)

Native binary (after cargo install)

{
  "mcpServers": {
    "outline": {
      "command": "outline-mcp",
      "args": ["/path/to/your-book.json"]
    }
  }
}

Docker (no Rust toolchain required)

{
  "mcpServers": {
    "outline": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/data:/data",
        "ghcr.io/ynishi/outline-mcp:latest",
        "/data/your-book.json"
      ]
    }
  }
}

If the path argument is omitted, defaults to outline-book.json in the current directory.

Workflow

shelf  →  select_book  →  toc  →  node_create / node_update / node_move
                                   node_batch_move / node_batch_update / node_query
                                   checklist / import / init / gen_routing
                                   snapshot_create / snapshot_list / snapshot_restore
                                   node_history / dump

1. init — Create a new empty book
2. node_create — Add sections and content nodes (with optional properties)
3. toc — View the table of contents with numbered IDs (e.g. 1, 2-3). Supports filter by properties
4. select_book — Select a book. Nodes with inject=true property have their body auto-appended (draft nodes excluded)
5. checklist — Export a section (or the whole book) as a Markdown checklist with checkboxes
6. node_update — Edit title, body, type, placeholder, properties, or status (active/draft) of a node
7. node_move — Relocate or delete nodes (with descendants)
8. node_batch_move — Move or delete multiple nodes in a single atomic call (requires UUID or UUID-prefix IDs)
9. node_batch_update — Update title/body/type/properties/status on multiple nodes atomically
10. node_query — Search nodes by property values, status (active/draft), or type (section/content); optionally include body in results
11. import — Import a book from a previously exported JSON file
12. gen_routing — Generate a Markdown routing table from nodes with routing property across all books
13. snapshot_create / snapshot_list / snapshot_restore — Full book versioning (create, list, restore)
14. node_history — View per-node change log with before/after diffs
15. dump — Export full book as JSON file

Node IDs

toc assigns human-friendly numbered IDs:

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

These IDs (1, 1-2, 2-1, etc.) work in most tools. Full UUIDs and title substring matching are also supported as fallbacks.

Note: node_batch_move and node_batch_update require UUID or UUID-prefix IDs. Hierarchical toc IDs are intentionally rejected to prevent positional drift when the tree is modified mid-batch.

Node Properties

Nodes can have key-value properties for metadata:

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

• inject=true — Node body is automatically included in select_book output (context injection)
• routing=<scene> — Marks the node for gen_routing output. Use | to assign multiple scenes (e.g. routing="testing|TDD")
• routing_ref=<text> — Overrides the default §ID Title reference in the routing table (e.g. routing_ref="select_book で全体参照")
• Properties with value "true" appear as tags in toc: 1. My Rule [inject]
• toc supports filtering: filter={"inject": "true"} shows only matching nodes
• Properties are preserved in JSON export/import

Architecture

The repository is a Cargo workspace with two crates: an rmcp-independent SDK (outline-mcp-core) and the MCP server binary (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
│       │   └── repository.rs # BookRepository trait
│       ├── application/  # Use cases
│       │   ├── service.rs # BookService (CRUD)
│       │   └── eject.rs  # EjectService (Markdown/JSON export & import)
│       └── infra/        # Persistence
│           ├── json_store.rs # JSON file repository (atomic write)
│           ├── changelog_store.rs
│           └── snapshot.rs
└── outline-mcp/          # Binary crate (MCP server, depends on outline-mcp-core)
    └── src/
        ├── main.rs       # Entry point
        └── interface/
            └── mcp/      # MCP handlers (rmcp, stdio)

Downstream applications that want to embed the tree / snapshot / changelog logic without pulling rmcp can depend on outline-mcp-core directly:

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

Export Formats

Markdown (default)

# My Runbook

## Design

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

JSON

Tree-structured format that can be re-imported:

{
  "title": "My Runbook",
  "max_depth": 4,
  "nodes": [
    {
      "title": "Design",
      "node_type": "section",
      "children": [...]
    }
  ]
}

Upgrading

From 0.9.1 or earlier

The snapshot subsystem now persists to a per-book SQLite event log ({shelf_dir}/{slug}.events.db) in addition to the existing on-disk .snap.{millis}.json files. Existing installs must run the migrator once to fold pre-existing on-disk snapshots into the event log — until they do, those snapshots stay on disk but are not visible to snapshot_list / snapshot_restore.

1. Back up the shelf directory. The migrator is idempotent and does not delete files, but the shelf directory is the source of truth for your books; a copy is cheap insurance.

cp -a <shelf-dir> <shelf-dir>.bak

2. Run the migrator.

outline-mcp migrate-snapshots --shelf <shelf-dir>

The migrator scans every {slug}.snap.{millis}.json file under <shelf-dir>, imports each into {shelf-dir}/{slug}.events.db with its original timestamp preserved, and leaves the source .json file in place. Output looks like:

== rust ==
  scanned:  3
  imported: 3
  skipped:  0
  failed:   0

Pass --slug <slug> to migrate one book at a time.

3. Verify (optional). Re-running the migrator is a no-op — every file will report as skipped.

What the migrator does not do

• It does not delete the source .snap.*.json files. Keep them for a while as a second layer of backup.
• It will refuse a stream that already carries events from a different clock (e.g. a book that has been actively edited via snapshot_create between the upgrade and the migrator run). Run the migrator before doing new writes.
• The startup warning that steers you here is emitted via tracing::warn! on stderr. MCP clients that swallow server stderr (Claude Code included) will not surface it — treat the migrator command as the canonical way to check.

Known limitations

• Snapshots that were post-hoc labeled via snapshot_tag (as opposed to labeled at snapshot_create time) lose the "time the label was attached" value in their sidecar .meta.json's internal created_at field. The label text itself is preserved, and created_at is never exposed through the MCP surface — this is an internal-metadata drift, not user-visible.

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.