rebar-mcp

MCP server for Rebar -- project intelligence for any AI editor.

No Claude Code required. This MCP server gives Cursor, Windsurf, VS Code Copilot, and any MCP-compatible editor full access to rebar's knowledge system: expertise files, wiki, observations, and the self-learn loop.

Quick Start

Auto-install (recommended): If you already have rebar-mcp connected to any editor, ask your AI to run:

rebar_install

This auto-detects all installed AI editors (Claude Desktop, Cursor, VS Code, Windsurf, Claude Code) and writes the correct MCP config for each one. Use dry_run: true to preview first.

Manual setup (Cursor example):

# In your project directory:
mkdir -p .cursor
cat > .cursor/mcp.json << 'EOF'
{
  "mcpServers": {
    "rebar": {
      "command": "npx",
      "args": ["@spotcircuit/rebar-mcp"]
    }
  }
}
EOF

Then in any editor, ask your AI to:

1. rebar_install — auto-configure all your other editors too
2. rebar_discover my-app — scan your codebase, generate expertise.yaml
3. Fill in the expertise based on the scan results
4. rebar_improve my-app — validate observations over time

That's it. Your AI now has persistent project memory that compounds.

Install

npm install -g @spotcircuit/rebar-mcp

Or run directly with npx (recommended):

npx @spotcircuit/rebar-mcp

What it exposes

Resources (read-only data)

| URI | Description | |---|---| | rebar://expertise/{project} | Full expertise.yaml for a project | | rebar://brief/{project} | Structured summary of a project's current state | | rebar://wiki | Wiki index (list of all pages with summaries) | | rebar://wiki/{page} | A specific wiki page | | rebar://observations/{project} | Unvalidated observations from expertise.yaml | | rebar://commands | List all available slash commands with descriptions | | rebar://gotchas/{project} | API gotchas from a project's expertise.yaml |

Tools — 6 Actions

Your AI calls these directly. Five verbs cover everything:

🔧 Setup — Get rebar running

| Tool | Description | |---|---| | rebar_install | Auto-detect editors and write MCP config for each | | rebar_config | Generate the MCP config snippet for a specific editor (read-only) | | rebar_init | Scaffold rebar into the current project |

📖 Learn — Build project knowledge

| Tool | Description | |---|---| | rebar_quickstart | One-call onboarding — scans codebase, generates expertise.yaml, produces brief, extracts gotchas, suggests first plan. The full first-run experience. | | rebar_session_start | Load project context for a warm start (expertise, observations, recent changes) | | rebar_session_end | Summarize session accomplishments, auto-append observations | | rebar_discover | Scan codebase, generate expertise.yaml with project analysis | | rebar_observe | Append an observation to unvalidated_observations | | rebar_improve | Review unvalidated observations — promote, discard, or defer | | rebar_validate | Check if a single observation should be promoted, discarded, or deferred | | rebar_review | Compare code changes against expertise — flag deviations where code contradicts docs | | rebar_resolve_observation | Resolve an observation: promote to a section, discard, or defer | | rebar_promote | (alias) Promote an observation into a target section | | rebar_discard | (alias) Discard a stale observation with a reason |

🛠 Work — Plan, build, and write

| Tool | Description | |---|---| | rebar_plan | Create an implementation plan, saved to specs/ | | rebar_build | Read a plan from specs/ and return it as build instructions | | rebar_write_expertise | Write or update a project's expertise.yaml (validates YAML) | | rebar_wiki_ingest | Read a raw/ file and return contents for wiki processing | | rebar_wiki_write | Write a wiki page to wiki/{category}/{page}.md | | rebar_wiki_move_processed | Move a processed raw file to raw/processed/ | | rebar_read_file | Read any file in the project | | rebar_write_file | Write any file in the project |

🔍 Know — Search and summarize

| Tool | Description | |---|---| | rebar_search | Search across all expertise files and wiki | | rebar_brief_tool | Generate a standup/handoff summary | | rebar_list_projects | List all projects (apps/ + clients/ + tools/) | | rebar_ingest | List files in raw/ ready for ingestion |

📊 Admin — Track, debug, and automate

| Tool | Description | |---|---| | rebar_stats | Dashboard: projects, observations, wiki pages, last updated | | rebar_diff | Show what changed in expertise.yaml since last session (git diff) | | rebar_install_hooks | Install rebar post-commit git hook (auto-appends observations on commit) | | rebar_uninstall_hooks | Remove the rebar post-commit git hook | | rebar_ingest_paperclip | Ingest Paperclip agent run history into expertise.yaml and optionally wiki |

Editor Setup

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "rebar": {
      "command": "npx",
      "args": ["@spotcircuit/rebar-mcp"]
    }
  }
}

Then in Cursor Settings > MCP, verify the server appears and is connected.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "rebar": {
      "command": "npx",
      "args": ["@spotcircuit/rebar-mcp"]
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "rebar": {
      "command": "npx",
      "args": ["@spotcircuit/rebar-mcp"]
    }
  }
}

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "rebar": {
      "command": "npx",
      "args": ["@spotcircuit/rebar-mcp"]
    }
  }
}

Claude Code

Claude Code users get slash commands natively via .claude/commands/. The MCP server is optional for Claude Code but useful if you want the same knowledge available in other tools too.

How it finds your project

The server walks up from the current working directory looking for a Rebar project root (a directory with CLAUDE.md and apps/ or clients/). If it cannot find one, run rebar_init to scaffold one.

You can also set the REBAR_ROOT environment variable to point at your project explicitly.

The Self-Learn Loop (without Claude Code)

The same loop works via MCP tools:

1. rebar_init                → scaffold rebar into the project
2. rebar_discover my-app     → scan codebase, create expertise.yaml
3. rebar_plan my-app         → create implementation plan in specs/
4. rebar_build my-app        → read plan, build it, observe what you learn
5. rebar_observe my-app      → capture gotchas and patterns during work
6. rebar_improve my-app      → validate observations, promote or discard
7. rebar_brief_tool my-app   → next session starts with full context

Every session, your AI reads expertise.yaml (via rebar://expertise/my-app) and starts with full project context. Observations compound. Stale facts get discarded. Your AI gets smarter about your project over time.

Development

git clone https://github.com/spotcircuit/rebar-mcp.git
cd rebar-mcp
npm install
node index.js

Test with the MCP inspector:

npx @modelcontextprotocol/inspector node index.js

How it works

The server reads and writes directly to the Rebar filesystem:

• apps/{project}/expertise.yaml, clients/{project}/expertise.yaml, and tools/{project}/expertise.yaml for project knowledge
• wiki/ for synthesized knowledge pages
• raw/ for file ingestion intake

No database, no config files, no API keys needed. It reads the same files Claude Code reads, making the knowledge available to every AI tool.

Paperclip Integration

The rebar_ingest_paperclip tool queries the Paperclip orchestration database to ingest agent run history. This closes the full loop: agents build → Paperclip tracks → rebar learns → /improve validates.

rebar_ingest_paperclip({ since: "2026-04-10", project: "paperclip", write_wiki: true })

Requires: A running Paperclip instance with PostgreSQL (default: localhost:54329). Connection params are configurable via tool arguments.

License

MIT