rosentic-mcp

Rosentic MCP Server 0.2.2

CI checks each PR against main. It doesn't check open PRs against each other.

Rosentic does. Install one package, then ask your coding agent to check for cross-branch conflicts before you merge.

One agent changes a function signature. Another agent still calls the old version. Both pass CI. Git merges the text cleanly. Main breaks.

Rosentic compares active branches against each other. Deterministic static analysis across 13 languages (Python, JavaScript, TypeScript, Go, Java, Rust, Swift, C++, Kotlin, C#, Ruby, PHP, Dart). No LLM. In local MCP mode, code and scan metadata stay on your machine.

MCP gives your editor or coding agent access to Rosentic tools on demand. It is not a hard automatic gate by itself: a CLAUDE.md instruction is advisory, and an agent can forget or ignore it. For a gate that BLOCKS, run rosentic-mcp install-hooks and commit the result (see Enforce below), or use the GitHub Action as a CI backstop.

Freshness and offline behavior

• Scan results are cached for 60 seconds per (repo, base, branch-set); a repeat call inside that window returns the cached result only while the scanned refs still match. Cached answers identify themselves as CACHED.
• check_file marks sibling-branch index data stale after 300 seconds (stale_after_seconds to override). Stale, skipped, moved, or newly unindexed sibling coverage is DEGRADED, never SAFE by implication.
• Sibling context comes from your local git refs: run git fetch to pick up new sibling work; the server never fetches for you.
• Offline: check_file, check_conflicts, explain_conflict, list_branches, run_status, and which_lane are fully local and work with no network. get_policy, get_verdict, and get_remediation_queue read the dashboard API and degrade gracefully offline - they return an explanatory payload (never raise), and get_policy reports the built-in default (advisory, UNSAFE fails), which is exactly what the CI gate falls back to.
• Linked git worktrees are supported with both local and Docker engines. Docker mode resolves the worktree's external Git metadata on the host and mounts the shared Git directory read-only alongside the writable worktree. If that metadata cannot be resolved, the tool returns NOT_EXECUTED instead of incorrectly reporting branches as absent.
• Call metering is a local counter at ~/.rosentic/mcp-usage.json. Nothing is billed and the counter never blocks a call.

Every answer names whether its check was EXECUTED, served from a validated CACHED result, DEGRADED, or NOT_EXECUTED. A degraded answer says in its model-facing message that it is not a clear result; nested metadata is evidence, not the only warning.

Install

pip3 install --upgrade rosentic-mcp

Use --upgrade even on a machine that already has the package: a plain pip install is a no-op for returning users and silently keeps stale code. If pip3 is not on PATH, use python3 -m pip install --upgrade rosentic-mcp.

Configure

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "rosentic": {
      "command": "rosentic-mcp"
    }
  }
}

Add this instruction to your repo's CLAUDE.md:

Before running git push, call the Rosentic check_conflicts MCP tool to verify your branch is compatible with other active branches.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.rosentic]
command = "rosentic-mcp"
args = []

Add the same push-boundary instruction to AGENTS.md.

Cursor / VS Code

Add to MCP settings:

{
  "rosentic": {
    "command": "rosentic-mcp"
  }
}

Enforce (make the gate block, not advise)

The steps above give agents the tools and an instruction. Nothing yet blocks a bad push. One command installs the committed enforcement path:

cd your-repo
rosentic-mcp install-hooks
git add .githooks .claude/settings.json
git commit -m "Add Rosentic enforcement gate"

What it installs:

• .githooks/pre-push - a committed git hook that runs rosentic-mcp gate and exits nonzero on UNSAFE findings. The gate fails closed: if the scan cannot run, the push is blocked with an explanation. Bypass one push with ROSENTIC_SKIP=1 git push; make WARNING findings block too with ROSENTIC_STRICT=1.
• git config core.hooksPath .githooks - the per-clone wiring. git config cannot be committed, so each fresh clone runs rosentic-mcp install-hooks once (it is idempotent).
• .claude/settings.json - committed Claude Code hooks: PreToolUse blocks an UNSAFE write before it lands, and Stop keeps the agent working while UNSAFE cross-branch findings exist. Because this file is committed, every fresh clone gates Claude Code sessions immediately, with zero per-user setup. If the file already exists, install-hooks appends the Rosentic entries and never removes yours.

You can also run the gate directly, in CI or by hand:

rosentic-mcp gate --repo . --base main   # exit 0 clean, 1 UNSAFE, 2 scan error

Tools

The rosentic-mcp 0.2.2 local server exposes all nine tools below. Six answer from the checkout and work offline; the three dashboard lookups are API-backed and report degradation explicitly when the network is unavailable.

Tool	Local answer
check_file	Checks proposed file content against sibling branches.
check_conflicts	Scans active branches for deterministic compatibility conflicts.
explain_conflict	Explains one finding from a recent scan.
list_branches	Lists local branches by last commit.
run_status	Reads manifest lanes, local heads, merge state, sequence, and landing readiness.
which_lane	Resolves declared path ownership without guessing.
get_verdict	Reads a recorded gate verdict for a checkout and SHA.
get_policy	Reads the effective merge-gate policy.
get_remediation_queue	Reads the ranked remediation queue.

check_conflicts

Scan a git repo for cross-branch conflicts affecting your current branch.

Parameters:

• repo_path (required) - path to local git repository
• branch - branch to check (defaults to current branch)
• base - base branch to compare against (defaults to main)
• format - "summary" (natural language) or "json" (structured findings)

Every response carries a discrete execution_status and model-facing message. Summary responses put the unchanged prose under summary; JSON responses put structured findings under findings. An empty result is meaningful only when the status is EXECUTED or CACHED.

Example response:

Rosentic found 4 unique conflict(s) for feature/auth-refactor: 2 UNSAFE, 2 WARNING. Layer breakdown: 3 L1 signature, 1 L2 route. Most critical: createUser() in src/auth/users.ts - changed from 2 to 3 required params. Recommendation: inspect the UNSAFE findings first and update the stale branch before merging.

check_file

Check proposed complete file content against active sibling branches before writing.

Parameters:

• repo_path (required) - path to local git repository
• file (required) - repository-relative file path being edited
• content (required) - proposed complete post-edit file content
• branch - current branch to use as the proposed-content overlay
• base - base branch to compare against (defaults to main)
• stale_after_seconds - mark branch index data stale after this many seconds

The response includes SAFE/WARNING/UNSAFE verdict, conflict direction, consumers with branch attribution, checked branches, skipped branches with reasons, and index freshness metadata.

explain_conflict

Get detailed explanation of a specific finding, including affected branches, consumer locations, and remediation steps. The prose is returned under summary beside execution_status and message.

Parameters:

• repo_path (required) - path to local git repository
• finding_id (required) - ID from a previous check_conflicts result

list_branches

List local branches sorted by most recent commit date. The rows are returned under branches beside the common execution status and message.

Parameters:

• repo_path (required) - path to local git repository

run_status

Read .rosentic/run.yaml plus local Git branch heads and merge state. Returns each lane's sequence position, whether it is merged into the manifest's base branch, the lane currently clear to land, and old branches still ahead of base. Checkout state is current by definition, so the Remote-only RESCAN_REQUIRED staleness case does not apply here.

Parameters:

• repo (required) - path to local git repository
• cursor - pagination cursor from a prior response
• limit - number of lanes to return (default 25, maximum 100)

which_lane

Match repository-relative paths against the manifest's declared protected_paths. Missing or ambiguous ownership is returned explicitly; the tool never guesses.

Parameters:

• repo (required) - path to local git repository
• paths (required) - one to 100 repository-relative paths

get_verdict

Look up recorded gate verdicts in the Rosentic audit ledger by SHA (append-only gate ledger via the dashboard API). Requires ROSENTIC_API_KEY (a ros_live_ workspace key) for the org's workspace. Degrades gracefully offline - returns an explanatory payload instead of raising.

Parameters:

• repo (required) - path to local git repository
• sha (required) - branch head SHA to look up

get_policy

Fetch the effective Rosentic gate policy (repo > org default > built-in): gate mode, severity threshold, per-layer enforce/advisory, branch-pattern rules, and the stamped policy version. Public read - no key needed. Degrades gracefully offline with the built-in default and a notice.

Parameters:

• org (required) - GitHub org/owner of the repository
• repo - repository name; omit for the org default policy

Troubleshooting

A source checkout is answering instead of the installed package

On developer machines an MCP entry often points at a source checkout rather than an installed rosentic-mcp. A checkout follows whatever branch is checked out, so the engine behind your results moves every time you switch branches, and nothing about the output looks different.

The server keys this off the process actually answering, not off what any config entry is named. When the answering server is a checkout, or the engine resolved to something other than an explicit path or an installed package, the first tool result per repo opens with ROSENTIC ENGINE SOURCE UNEXPECTED, naming the checkout root, commit, and branch. The same condition appears on every result as engine_source.unexpected.

Renaming an entry does not change this either way: an entry called rosentic-dev is not itself a problem, and renaming one will not silence a checkout that is genuinely answering.

Ask directly at any time:

rosentic-mcp doctor          # which server answered, which engine, and whether that is supported
rosentic-mcp doctor --json   # same, machine readable; exits 1 when unsupported

Remedy, once doctor shows a checkout is answering:

claude mcp list                                    # find the entry that launches the checkout
claude mcp remove <that-entry-name> -s user
claude mcp add rosentic -s user -- uvx --from rosentic-mcp rosentic-mcp

Then restart the MCP client so the old server process is replaced, and re-run rosentic-mcp doctor.

What it detects

Layer	What	Example
L1	Function signature mismatches	Branch A adds required param, Branch B still calls with old arity
L2	HTTP route contract breaks	Route path or method changes, consumers still call old endpoint
L3	Schema incompatibilities	Proto field removed, GraphQL type changed, OpenAPI contract broken

How it works

• Deterministic - no LLM in the scan path. Tree-sitter AST parsing + evidence-gated verdicts.
• Fast - scans 30 branches in under 30 seconds for most repos.
• Evidence-based - every finding includes proof: which symbol changed, where it's called, why it's linked.

Requirements

• Python 3.11+
• Git repository with branches to scan
• Works on macOS, Linux, Windows (WSL)

Verify

From a checkout that has this repository's helper scripts:

python3 scripts/mcp-smoke-test.py

Expected output:

Rosentic MCP OK: check_conflicts, check_file, explain_conflict, get_policy, get_remediation_queue, get_verdict, list_branches, run_status, which_lane

Links

• Website
• GitHub
• GitHub Action