OCD - Organized Context Datastore (MCP)

日本語版はこちら (README_jp.md)

Give your AI persistent, structured memory — and let humans see it too.

OCD is an MCP server that stores project knowledge as Markdown files in a hierarchical tree. LLMs read and write via MCP tools; humans browse and edit via a built-in Web UI or any text editor. Both share the same source of truth.

Why OCD?

• No more lost context — Project knowledge persists across sessions in a Git-backed store
• Token-efficient — Fetch only the branches you need with tree-text format, not entire documents
• Human-friendly — Plain Markdown + frontmatter. Edit in VS Code, review on GitHub, or use the built-in Web UI
• One command — npx github:teamstove/organized-context-datastore-mcp starts both the MCP server and the Web UI

---

Quick Start

One-Liner (stdio + Web UI enabled by default)

# Cursor connects via stdio + humans browse http://localhost:38291/viewer
npx github:teamstove/organized-context-datastore-mcp

# Read-only mode
npx github:teamstove/organized-context-datastore-mcp --readonly

HTTP Server Mode

# Local dev mode (with Web UI)
npx github:teamstove/organized-context-datastore-mcp --http --port 38291

# Remote server mode
npx github:teamstove/organized-context-datastore-mcp --http --mode remote-server --config ./config.json

---

How It Works

┌──────────────┐   MCP (stdio / HTTP)   ┌─────────────────┐
│  LLM / IDE   │ ◄───────────────────► │   OCD Server    │
│  (Cursor…)   │                        │                 │
└──────────────┘                        │  Markdown files │
                                        │  + frontmatter  │
┌──────────────┐   HTTP + Web UI        │  + Git history  │
│    Human     │ ◄───────────────────► │                 │
│  (Browser)   │                        └─────────────────┘
└──────────────┘

For LLMs	For Humans
Persistent memory across sessions	Plain Markdown — edit anywhere
Hierarchical tree with pattern queries	Built-in Web UI with tree view & search
Token-efficient tree-text retrieval	Git-backed history & diffs
6 MCP tools: list, get, tree, search, mutate, commit	Review and refine what the AI writes

---

CLI Options

Option	Description
(none)	stdio mode (default) + Web UI on port 38291
--http	HTTP server mode
--readonly	Disable write tools
--port <port>	HTTP port number (default: 38291)
--web-ui-port <port>	Web UI port in stdio mode (default: 38291)
--disable-web-ui	Disable the Web UI
--mode <mode>	HTTP only: local-dev / remote-server
--config <path>	Config file for remote-server mode

Duplicate launch behavior: If OCD is already running on the same port, subsequent launches log "OCD is already running on this port" and exit cleanly (exit 0). An error exit only occurs when the port is occupied by a different process. The server identity check uses GET /whois — if the response is OCD, it is recognized as an existing OCD instance.

CLI tool subcommands (same logic as MCP tools)

Run read/write operations without starting the MCP server. Results are printed as JSON on stdout (pipe to jq, etc.).

ocd-mcp tool --help
ocd-mcp tool --cwd . list-roots
ocd-mcp tool --cwd . get-contexts --patterns 'docs/**'
ocd-mcp tool --cwd . search --query "auth"

Context	Flag	Meaning
Project (usual)	--cwd <dir>	Resolve .ocd.config.js upward from this directory (same as MCP cwd).
Fixed storage	--storage <dir>	loadConfig root — not the HTTP remote-server JSON config file.

• --readonly: blocks mutate and commit.
• Do not run mutate / commit against the same Git repo while the stdio MCP server is writing — risk of lock/conflict.
• get-contexts --include-content can produce very large JSON.

---

Cursor / IDE Configuration

One-Liner (stdio + Web UI)

{
  "mcpServers": {
    "ocd-mcp": {
      "command": "npx",
      "args": [
        "--package", "github:teamstove/organized-context-datastore-mcp",
        "tsx", "src/cli.ts"
      ]
    }
  }
}

• Cursor connects via stdio
• Humans browse http://localhost:38291/viewer

stdio Only (Web UI disabled)

"args": [
  "--package", "github:teamstove/organized-context-datastore-mcp",
  "tsx", "src/cli.ts",
  "--disable-web-ui"
]

Via bin Entry (after package install)

{
  "mcpServers": {
    "ocd-mcp": {
      "command": "npx",
      "args": ["github:teamstove/organized-context-datastore-mcp"]
    }
  }
}

HTTP Mode

# Start the server in a terminal
npx github:teamstove/organized-context-datastore-mcp --http --port 38291

{
  "mcpServers": {
    "ocd-mcp": {
      "url": "http://localhost:38291/api/mcp"
    }
  }
}

Web UI is available at http://localhost:38291/viewer.

Context Roots Filtering (HTTP Mode)

{
  "mcpServers": {
    "ocd-pj-alpha": {
      "url": "http://localhost:38291/api/mcp?roots=project-alpha,core-docs"
    },
    "ocd-pj-beta-readonly": {
      "url": "http://localhost:38291/api/mcp?roots=project-beta,shared&readonly=shared"
    }
  }
}

Parameter	Description	Example
roots	Context Root IDs to include (comma-separated)	?roots=A,B,C
readonly	Context Root IDs to make read-only	?readonly=C

---

Configuration

Local Config (.ocd.config.js)

Place in the project root. OCD searches upward from cwd automatically.

export default {
  contextRoots: [
    {
      path: './organized-context',
      git: 'auto-commit'
    },
    {
      path: './CORE/docs',
      name: 'CORE Docs',
      readOnly: true
    }
  ],
  inheritGlobal: true
}

Global Config (~/.ocd/config.js)

Define Context Roots shared across all projects.

Git Modes

Value	Description
'auto-commit'	Automatically commit after each operation
'manual'	Commit explicitly via the ocd_commit tool (default)
'none'	Do not use Git

---

MCP Tools

Tool	Description
ocd_list_context_roots	List all Context Roots
ocd_get_contexts	Retrieve contexts by pattern and filters
ocd_get_context_tree	Get the context tree (table of contents)
ocd_search_contexts	Search contexts by keyword
ocd_mutate_context	Mutate a context (create / update / delete / move)
ocd_commit	Commit changes (for git: 'manual' mode)

ocd_mutate_context — Performance Notes

• Serialization: Within the same Context Root (same cwd), ocd_mutate_context and ocd_commit execute one at a time. When called in rapid succession, subsequent calls wait for the previous one to complete — this is a queue, not a freeze. This prevents Git operation conflicts.
• Move cost: A move operation scans all .md files under the Context Root to update internal links and prevent broken references. If the root contains many files, a single move may take noticeable time.

---

Directory Structure Example

my-context-store/
├── .ocd.config.js
├── project-a/
│   ├── index.md
│   ├── features/
│   │   ├── feature-1.md
│   │   └── feature-2.md
│   └── decisions/
│       └── adr-001.md
└── project-b/
    └── ...

---

Markdown Format

---
title: Feature Specification
status: draft
priority: high
---

# User Authentication

## Overview

Details about the user authentication implementation...

All frontmatter fields other than title are treated as attrs.

---

Installation

git clone https://github.com/teamstove/organized-context-datastore-mcp.git
cd organized-context-datastore-mcp
npm install

The Web UI is built automatically on first launch. To build manually: npm run build:web-ui.

---

For Developers

See docs/DEVELOPMENT.md for local development, testing, and build instructions.

---

License

MIT