`install --platform cursor` produces broken rules — Cursor prefixes MCP server identifier, docs use the raw name

[raulgad]

Summary

After running code-review-graph install --platform cursor, the generated .cursorrules / AGENTS.md instruct the AI agent to call tools on MCP server code-review-graph, but Cursor does not expose the server under that name. Cursor always applies a prefix:

• Project-level MCP (written to ./.cursor/mcp.json): server is exposed to the agent as project-0-<folder-name>-code-review-graph
• User-level MCP (written to ~/.cursor/mcp.json): server is exposed to the agent as user-code-review-graph

As a result, when the agent follows the injected instructions and calls call_mcp_tool(server="code-review-graph", ...), it fails with:

MCP server does not exist: code-review-graph

The installer never mentions the prefix, so end-users spend hours debugging why the tools don't work despite the MCP indicator turning green in Cursor's settings.

There's also a secondary issue: when Cursor launches code-review-graph serve, the cwd is not the project root, so serve cannot auto-detect .code-review-graph/graph.db and returns an empty graph (see "Secondary bug" below).

Environment

• code-review-graph: 2.3.2 (pipx install code-review-graph)
• Cursor: latest stable, macOS
• OS: macOS 26.4.1 (ARM)
• Python: 3.14.4 (pipx venv)
• MCP transport: stdio (FastMCP 2.14.7)

Steps to Reproduce

1. Install the tool and build a graph:

   pipx install code-review-graph
   cd ~/projects/my_project
   code-review-graph install --platform cursor    # answer "y" to inject rules
   code-review-graph build

2. Restart Cursor.
3. Open Cursor's agent chat in the same project and prompt:

   Use the code-review-graph MCP tools. Call list_graph_stats_tool.

4. Observe the agent failing with MCP server does not exist: code-review-graph.

The .cursorrules file written by the installer looks like this (abridged):

## MCP Tools: code-review-graph
**IMPORTANT: ... ALWAYS use the code-review-graph MCP tools ...**
...
| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
| `get_impact_radius` | Understanding blast radius of a change |
...

There is no mention of the Cursor-specific server identifier that the agent's call_mcp_tool wrapper actually recognises.

Expected Behavior

code-review-graph install --platform cursor should either:

1. Write the real Cursor server identifier (including prefix) into .cursorrules / AGENTS.md, so the agent can call tools successfully right out of the box, or
2. Explicitly document in the injected rules that Cursor prefixes MCP names (project-0-<folder>- for project-level, user- for user-level) and tell the agent to discover the server via the MCP filesystem schema files rather than by hardcoded name.

Actual Behavior

Installer writes the raw display name (code-review-graph). Cursor exposes the server under a prefixed identifier. The two never match. Every user has to manually patch .cursorrules themselves before the agent can use the graph at all.

Evidence

1. Cursor log confirms the server starts successfully:

   [info] CreateClient completed, connected: true, statusType: connected
   Starting MCP server 'code-review-graph' with transport 'stdio'
   

   (File path: ~/Library/Application Support/Cursor/logs/<session>/window1/exthost/anysphere.cursor-mcp/MCP user-code-review-graph.log — note Cursor itself already names the log after the prefixed identifier user-code-review-graph.)

2. Cursor's per-project MCP descriptor folder is created under the prefixed name:

   ~/.cursor/projects/<project>/mcps/project-0-<folder>-code-review-graph/
     SERVER_METADATA.json    # { "serverIdentifier": "project-0-<folder>-code-review-graph",
                             #   "serverName": "code-review-graph" }
     INSTRUCTIONS.md
     tools/                  # 30 JSON tool schemas
     prompts/
   

   The distinction between serverIdentifier and serverName is exactly what's missing from the injected rules.

3. Direct proof that the prefixed name works and the raw name doesn't:

   call_mcp_tool(server="code-review-graph", ...)          → "MCP server does not exist"
   call_mcp_tool(server="user-code-review-graph", ...)     → OK, returns graph stats
   

Root Cause

code_review_graph/install/* (whichever module generates the Cursor rules) uses "code-review-graph" as the literal server name in the templates. It doesn't consult Cursor's naming convention, which is:

MCP config location	Agent-visible identifier
./.cursor/mcp.json (project)	project-0-<folder>-<name>
~/.cursor/mcp.json (user/global)	user-<name>

Proposed Fix

Option A (quick, robust)

When --platform cursor is used and rules are injected, include the prefixed identifier explicitly:

## MCP Tools: code-review-graph

**Cursor server identifier:** `project-0-<folder>-code-review-graph`
(display name: `code-review-graph`; Cursor adds the `project-0-<folder>-` /
`user-` prefix automatically to MCP server names)

All tool calls MUST use:
  call_mcp_tool(server="project-0-<folder>-code-review-graph", toolName=..., arguments=...)
Tool JSON schemas live in:
  ~/.cursor/projects/<this-project>/mcps/project-0-<folder>-code-review-graph/tools/

The installer already knows --repo (project root), so deriving <folder> is a one-liner. For user-level installs (if/when added), it writes user-code-review-graph instead.

Option B (more resilient)

Don't rely on the server name at all in the rules. Instead tell the agent to discover the server dynamically:

This project exposes an MCP server named `code-review-graph` (may be prefixed
by Cursor as `project-0-<folder>-code-review-graph` or `user-code-review-graph`).
Before calling tools, list the available MCP servers in
`~/.cursor/projects/<this-project>/mcps/` and pick the one whose
`SERVER_METADATA.json` has `"serverName": "code-review-graph"`.

Option A is simpler and good enough for 99% of users. Option B is the cleanest long-term fix.

Secondary bug: serve cwd is wrong when invoked from a user-level mcp.json

This is related but independent.

When a user puts code-review-graph in ~/.cursor/mcp.json (user-level), Cursor launches the serve process with cwd=$HOME. code-review-graph serve (v2.3.2) auto-detects the repo from cwd, so it resolves to ~ and returns an empty graph:

call_mcp_tool(server="user-code-review-graph", toolName="list_graph_stats_tool", arguments={})
→ {
    "summary": "Graph statistics for mac:\n  Files: 0\n  Total nodes: 0 ...",
    "total_nodes": 0,
    "last_updated": null
  }

This makes user-level installs silently useless. Two options:

1. Have install --platform cursor write --repo <absolute_repo_root> into args automatically. It already has this info.
2. Make serve walk upwards from cwd looking for a .code-review-graph/ directory (similar to how git discovers the repo root).

A small UX improvement: if serve cannot find a graph and --repo wasn't provided, it could log a clear warning instead of silently serving an empty graph.

Impact

Every Cursor user who runs code-review-graph install --platform cursor today gets a setup that:

• Appears to work (green indicator in Cursor settings, FastMCP banner in logs)
• But the agent cannot use the graph because the rules reference a server name that doesn't exist at the agent's MCP layer
• Silently returns an empty graph if installed user-level (cwd bug)