Merge pull request #10 from holive/holive/improve-mcp

feat: improve MCP server -- roam_ prefix, 13 new tools, structured errors, roam mcp command

Author: Cranot

.github/workflows/roam-ci.yml

@@ -49,4 +49,4 @@ jobs:
       - run: pip install -e .
       - run: roam index
       - run: roam fitness
-      - run: roam health --json
+      - run: roam --json health

.github/workflows/roam.yml

@@ -18,4 +18,4 @@ jobs:
       - run: pip install roam-code
       - run: roam index
       - run: roam fitness
-      - run: roam pr-risk --json
+      - run: roam --json pr-risk

CLAUDE.md

@@ -38,7 +38,7 @@ roam health
 ```
 src/roam/
   cli.py              # Click CLI entry point — LazyGroup, _COMMANDS dict, _CATEGORIES
-  mcp_server.py       # FastMCP server (48 tools, 2 resources)
+  mcp_server.py       # FastMCP server (61 tools, 2 resources) + `roam mcp` CLI command
   __init__.py          # Version string (reads from pyproject.toml via importlib.metadata)
   db/
     schema.py          # SQLite schema (CREATE TABLE statements)
@@ -106,7 +106,7 @@ src/roam/
     formatter.py       # Token-efficient text formatting, abbrev_kind(), loc(), format_table(), to_json(), json_envelope()
     sarif.py           # SARIF 2.1.0 output (--sarif flag on health/debt/complexity)
     schema_registry.py # JSON envelope schema versioning + validation
-tests/                 # 70 test files
+tests/                 # 71 test files
   # Core & legacy
   test_basic.py, test_comprehensive.py, test_fixes.py, test_performance.py,
   test_resolve.py, test_salesforce.py, test_v6_features.py,
@@ -130,7 +130,8 @@ tests/                 # 70 test files
   test_capsule.py, test_forecast.py, test_path_coverage.py,
   test_minimap.py, test_attest.py, test_annotations.py, test_budget.py,
   test_pr_diff.py, test_framework_detection.py, test_backend_fixes_round2.py,
-  test_backend_fixes_round3.py, test_exclude_patterns.py, test_math_tips.py
+  test_backend_fixes_round3.py, test_exclude_patterns.py, test_math_tips.py,
+  test_mcp_server.py
 ```
 
 ### Key patterns
@@ -223,7 +224,7 @@ tests/                 # 70 test files
 - tree-sitter >= 0.23 (AST parsing)
 - tree-sitter-language-pack >= 0.6 (165+ grammars)
 - networkx >= 3.0 (graph algorithms)
-- Optional: fastmcp (MCP server)
+- Optional: fastmcp >= 2.0 (MCP server — `pip install roam-code[mcp]`)
 - Dev: pytest >= 7.0, pytest-xdist >= 3.0, ruff >= 0.4
 
 ## Version bumping

README.md

@@ -722,73 +722,86 @@ Run `roam --help` for all commands. Use `roam --json <cmd>` for structured outpu
 Roam includes a [Model Context Protocol](https://modelcontextprotocol.io/) server for direct integration with tools that support MCP.
 
 ```bash
-pip install fastmcp
-fastmcp run roam.mcp_server:mcp
+pip install roam-code[mcp]
+roam mcp
 ```
 
-48 read-only tools and 2 resources. All tools query the index -- they never modify your code.
+61 tools and 2 resources. All tools are read-only and query the index -- they never modify your code.
 
-**Lite mode:** For smaller models or latency-sensitive setups, set `ROAM_MCP_LITE=1` to expose only 15 core tools:
+**Lite mode (default):** By default, 16 core tools are exposed to keep the tool list manageable for agents. Set `ROAM_MCP_LITE=0` to expose all 61 tools:
 
 ```bash
-ROAM_MCP_LITE=1 fastmcp run roam.mcp_server:mcp
+ROAM_MCP_LITE=0 roam mcp
 ```
 
-Core tools in lite mode: `understand`, `health`, `preflight`, `search_symbol`, `context`, `trace`, `impact`, `file_info`, `pr_risk`, `affected_tests`, `dead_code`, `complexity_report`, `diagnose`, `visualize`, `closure`.
+Core tools in lite mode: `roam_understand`, `roam_search_symbol`, `roam_context`, `roam_file_info`, `roam_deps`, `roam_preflight`, `roam_diff`, `roam_pr_risk`, `roam_affected_tests`, `roam_impact`, `roam_uses`, `roam_health`, `roam_dead_code`, `roam_complexity_report`, `roam_diagnose`, `roam_trace`.
 
 <details>
-<summary><strong>MCP tool list (all 48)</strong></summary>
+<summary><strong>MCP tool list (all 61)</strong></summary>
 
 | Tool | Description |
 |------|-------------|
-| `understand` | Full codebase briefing |
-| `health` | Health score (0-100) + issues |
-| `preflight` | Pre-change safety check |
-| `search_symbol` | Find symbols by name |
-| `context` | Files-to-read for modifying a symbol |
-| `trace` | Dependency path between two symbols |
-| `impact` | Blast radius of changing a symbol |
-| `file_info` | File skeleton with all definitions |
-| `pr_risk` | Risk score for pending changes |
-| `breaking_changes` | Detect breaking changes between refs |
-| `affected_tests` | Find tests affected by a change |
-| `dead_code` | List unreferenced exports |
-| `complexity_report` | Per-symbol cognitive complexity |
-| `repo_map` | Project skeleton with key symbols |
-| `tour` | Auto-generated onboarding guide |
-| `diagnose` | Root cause analysis for debugging |
-| `visualize` | Generate Mermaid or DOT architecture diagrams |
-| `algo` | Algorithm anti-pattern detection with language-aware tips |
-| `ws_understand` | Unified multi-repo workspace overview |
-| `ws_context` | Cross-repo augmented symbol context |
-| `pr_diff` | Structural PR diff: metric deltas, edge analysis, symbol changes |
-| `budget_check` | Check changes against architectural budgets |
-| `effects` | Side-effect classification (DB writes, network, filesystem) |
-| `attest` | Proof-carrying PR attestation with all evidence bundled |
-| `capsule_export` | Export sanitized structural graph (no code bodies) |
-| `path_coverage` | Find critical untested call paths (entry -> sink) |
-| `forecast` | Predict when metrics will exceed thresholds |
-| `simulate` | Counterfactual architecture simulator |
-| `orchestrate` | Multi-agent swarm partitioning |
-| `fingerprint` | Topology fingerprint comparison |
-| `mutate` | Graph-level code editing (move/rename/extract) |
-| `dark_matter` | Hidden co-change coupling detection |
-| `closure` | Minimal-change synthesis for rename/delete |
-| `adversarial_review` | Adversarial architecture review |
-| `generate_plan` | Agent work planner |
-| `get_invariants` | Architectural invariant discovery |
-| `bisect_blame` | Architectural git bisect |
-| `doc_intent` | Doc-to-code linking |
-| `cut_analysis` | Minimum graph cut analysis |
-| `annotate_symbol` | Attach persistent notes to symbols |
-| `get_annotations` | View stored annotations |
-| `relate` | Show relationship between two symbols |
-| `search_semantic` | Semantic search by meaning |
-| `rules_check` | Plugin DSL governance rules |
-| `vuln_map` | Vulnerability report ingestion |
-| `vuln_reach` | Vulnerability reachability paths |
-| `ingest_trace` | Ingest runtime trace data |
-| `runtime_hotspots` | Runtime hotspot analysis |
+| `roam_understand` | Full codebase briefing |
+| `roam_health` | Health score (0-100) + issues |
+| `roam_preflight` | Pre-change safety check |
+| `roam_search_symbol` | Find symbols by name |
+| `roam_context` | Files-to-read for modifying a symbol |
+| `roam_trace` | Dependency path between two symbols |
+| `roam_impact` | Blast radius of changing a symbol |
+| `roam_file_info` | File skeleton with all definitions |
+| `roam_pr_risk` | Risk score for pending changes |
+| `roam_breaking_changes` | Detect breaking changes between refs |
+| `roam_affected_tests` | Find tests affected by a change |
+| `roam_dead_code` | List unreferenced exports |
+| `roam_complexity_report` | Per-symbol cognitive complexity |
+| `roam_repo_map` | Project skeleton with key symbols |
+| `roam_tour` | Auto-generated onboarding guide |
+| `roam_diagnose` | Root cause analysis for debugging |
+| `roam_visualize` | Generate Mermaid or DOT architecture diagrams |
+| `roam_algo` | Algorithm anti-pattern detection with language-aware tips |
+| `roam_ws_understand` | Unified multi-repo workspace overview |
+| `roam_ws_context` | Cross-repo augmented symbol context |
+| `roam_pr_diff` | Structural PR diff: metric deltas, edge analysis, symbol changes |
+| `roam_budget_check` | Check changes against architectural budgets |
+| `roam_effects` | Side-effect classification (DB writes, network, filesystem) |
+| `roam_attest` | Proof-carrying PR attestation with all evidence bundled |
+| `roam_capsule_export` | Export sanitized structural graph (no code bodies) |
+| `roam_path_coverage` | Find critical untested call paths (entry -> sink) |
+| `roam_forecast` | Predict when metrics will exceed thresholds |
+| `roam_simulate` | Counterfactual architecture simulator |
+| `roam_orchestrate` | Multi-agent swarm partitioning |
+| `roam_fingerprint` | Topology fingerprint comparison |
+| `roam_mutate` | Graph-level code editing (move/rename/extract) |
+| `roam_dark_matter` | Hidden co-change coupling detection |
+| `roam_closure` | Minimal-change synthesis for rename/delete |
+| `roam_adversarial_review` | Adversarial architecture review |
+| `roam_generate_plan` | Agent work planner |
+| `roam_get_invariants` | Architectural invariant discovery |
+| `roam_bisect_blame` | Architectural git bisect |
+| `roam_doc_intent` | Doc-to-code linking |
+| `roam_cut_analysis` | Minimum graph cut analysis |
+| `roam_annotate_symbol` | Attach persistent notes to symbols |
+| `roam_get_annotations` | View stored annotations |
+| `roam_relate` | Show relationship between two symbols |
+| `roam_search_semantic` | Semantic search by meaning |
+| `roam_rules_check` | Plugin DSL governance rules |
+| `roam_vuln_map` | Vulnerability report ingestion |
+| `roam_vuln_reach` | Vulnerability reachability paths |
+| `roam_ingest_trace` | Ingest runtime trace data |
+| `roam_runtime_hotspots` | Runtime hotspot analysis |
+| `roam_diff` | Blast radius of uncommitted/committed changes |
+| `roam_symbol` | Symbol definition, callers, callees, metrics |
+| `roam_deps` | File-level import/imported-by relationships |
+| `roam_uses` | All consumers of a symbol by edge type |
+| `roam_weather` | Code hotspots: churn x complexity ranking |
+| `roam_debt` | Hotspot-weighted technical debt prioritization |
+| `roam_n1` | Detect N+1 I/O patterns in ORM code |
+| `roam_auth_gaps` | Find endpoints missing auth |
+| `roam_over_fetch` | Detect models serializing too many fields |
+| `roam_missing_index` | Find queries on non-indexed columns |
+| `roam_orphan_routes` | Detect dead backend routes |
+| `roam_migration_safety` | Detect non-idempotent migrations |
+| `roam_api_drift` | Backend/frontend model mismatch detection |
 
 **Resources:** `roam://health` (current health score), `roam://summary` (project overview)
 
@@ -798,17 +811,17 @@ Core tools in lite mode: `understand`, `health`, `preflight`, `search_symbol`, `
 <summary><strong>Claude Code</strong></summary>
 
 ```bash
-claude mcp add roam -- fastmcp run roam.mcp_server:mcp
+claude mcp add roam-code -- roam mcp
 ```
 
 Or add to `.mcp.json` in your project root:
 
 ```json
 {
   "mcpServers": {
-    "roam": {
-      "command": "fastmcp",
-      "args": ["run", "roam.mcp_server:mcp"]
+    "roam-code": {
+      "command": "roam",
+      "args": ["mcp"]
     }
   }
 }
@@ -824,9 +837,9 @@ Add to your `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
-    "roam": {
-      "command": "fastmcp",
-      "args": ["run", "roam.mcp_server:mcp"],
+    "roam-code": {
+      "command": "roam",
+      "args": ["mcp"],
       "cwd": "/path/to/your/project"
     }
   }
@@ -843,9 +856,9 @@ Add to `.cursor/mcp.json`:
 ```json
 {
   "mcpServers": {
-    "roam": {
-      "command": "fastmcp",
-      "args": ["run", "roam.mcp_server:mcp"]
+    "roam-code": {
+      "command": "roam",
+      "args": ["mcp"]
     }
   }
 }
@@ -861,10 +874,10 @@ Add to `.vscode/mcp.json`:
 ```json
 {
   "servers": {
-    "roam": {
+    "roam-code": {
       "type": "stdio",
-      "command": "fastmcp",
-      "args": ["run", "roam.mcp_server:mcp"]
+      "command": "roam",
+      "args": ["mcp"]
     }
   }
 }
@@ -1167,7 +1180,7 @@ Roam is **not** a replacement for your linter, LSP, or SonarQube. It fills a dif
 | **Aider repo map** | Tree-sitter + PageRank | Context selection for chat. Roam adds git signals, 95 architecture commands, CI gates, multi-agent orchestration |
 | **CodeScene** | Behavioral code analysis | Commercial SaaS ($20-60k/yr). Roam is free, local, uses peer-reviewed algorithms (Mann-Kendall, NPMI, Personalized PageRank) |
 | **SonarQube** | Code quality + security | Heavy server ($15-45k/yr). Roam's cognitive complexity follows SonarSource spec |
-| **Serena MCP** | LSP-based symbol navigation | 6 MCP tools for navigation. Roam has 48 MCP tools covering architecture, governance, simulation, and orchestration |
+| **Serena MCP** | LSP-based symbol navigation | 6 MCP tools for navigation. Roam has 61 MCP tools covering architecture, governance, simulation, and orchestration |
 | **Repomix / code2prompt** | Codebase packing for LLMs | Flat file packing with no graph intelligence. Roam gives structural queries, not raw file dumps |
 | **Augment Code** | Cloud context engine | Cloud-hosted, enterprise-priced. Roam is 100% local, air-gapped, MIT-licensed |
 | **grep / ripgrep** | Text search | No semantic understanding. Can't distinguish definitions from usage |
@@ -1254,7 +1267,7 @@ roam-code/
 ├── src/roam/
 │   ├── __init__.py                    # Version (from pyproject.toml)
 │   ├── cli.py                         # Click CLI (95 commands, 7 categories)
-│   ├── mcp_server.py                  # MCP server (48 tools, 2 resources)
+│   ├── mcp_server.py                  # MCP server (61 tools, 2 resources)
 │   ├── db/
 │   │   ├── connection.py              # SQLite (WAL, pragmas, batched IN)
 │   │   ├── schema.py                  # Tables, indexes, migrations
@@ -1333,7 +1346,7 @@ roam-code/
 | [tree-sitter-language-pack](https://github.com/nicolo-ribaudo/tree-sitter-language-pack) >= 0.6 | 165+ grammars |
 | [networkx](https://networkx.org/) >= 3.0 | Graph algorithms |
 
-Optional: [fastmcp](https://github.com/jlowin/fastmcp) (MCP server)
+Optional: [fastmcp](https://github.com/jlowin/fastmcp) >= 2.0 (MCP server — install with `pip install roam-code[mcp]`)
 
 ## Roadmap
 

llms-install.md

@@ -1,12 +1,13 @@
 # Installing roam-code
 
 roam-code provides instant codebase comprehension for AI coding agents.
-55 commands, 22 languages, 100% local, zero API keys.
+95 commands, 26 languages, 100% local, zero API keys.
 
 ## Quick install
 
 ```bash
 pip install roam-code
+pip install roam-code[mcp]  # optional: MCP server support
 ```
 
 Or with isolated environments:
@@ -71,4 +72,4 @@ Add to your MCP config:
 | `roam context <symbol>` | Files and line ranges to read |
 | `roam diff` | Blast radius of uncommitted changes |
 
-Run `roam --help` for all 55 commands.
+Run `roam --help` for all 95 commands.

pyproject.toml

@@ -44,6 +44,9 @@ Issues = "https://github.com/Cranot/roam-code/issues"
 roam = "roam.cli:cli"
 
 [project.optional-dependencies]
+mcp = [
+    "fastmcp>=2.0",
+]
 dev = [
     "pytest>=7.0",
     "pytest-xdist>=3.0",

src/roam/cli.py

@@ -109,11 +109,12 @@
     "schema":            ("roam.commands.cmd_schema",        "schema_cmd"),
     "search-semantic":   ("roam.commands.cmd_search_semantic", "search_semantic"),
     "relate":            ("roam.commands.cmd_relate",        "relate"),
+    "mcp":               ("roam.mcp_server",                 "mcp_cmd"),
 }
 
 # Command categories for organized --help display
 _CATEGORIES = {
-    "Getting Started": ["index", "init", "config", "understand", "tour", "describe", "minimap", "ws", "schema"],
+    "Getting Started": ["index", "init", "config", "understand", "tour", "describe", "minimap", "ws", "schema", "mcp"],
     "Daily Workflow": ["preflight", "pr-risk", "pr-diff", "attest", "adversarial", "diff", "context", "affected-tests", "diagnose", "digest", "annotate", "annotations", "plan"],
     "Codebase Health": ["health", "weather", "debt", "complexity", "algo", "n1", "over-fetch", "missing-index", "alerts", "trend", "fitness", "snapshot", "forecast", "bisect", "ingest-trace", "hotspots"],
     "Architecture": ["map", "layers", "clusters", "coupling", "dark-matter", "effects", "cut", "simulate", "orchestrate", "entry-points", "patterns", "safe-zones", "visualize", "x-lang", "fingerprint"],