rosentic-mcp 0.1.4

MCP server for Rosentic - cross-branch conflict detection for parallel AI coding agents: catches breaking signature changes, HTTP route breaks, and schema drift between agent branches before merge

Rosentic MCP Server

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. 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. For automatic protection before every git push, install the Rosentic pre-push hook 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 instantly.
• check_file marks sibling-branch index data stale after 300 seconds (stale_after_seconds to override) and reports freshness metadata in every response, so an agent always knows how old its sibling context is.
• 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, and list_branches are fully local and work with no network. get_policy and get_verdict 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 (repo detection uses git rev-parse, not a .git-directory test). One caveat: when the engine runs via Docker (no local checkout), scan the MAIN checkout rather than a linked worktree - a worktree's gitdir lives outside the mounted path. With a local engine (dev checkout / ROSENTIC_ENGINE_PATH), worktrees work everywhere.
• Call metering is a local counter at ~/.rosentic/mcp-usage.json. Nothing is billed and the counter never blocks a call.

Install

pip install 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"
  }
}

Tools

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)

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.

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.

Parameters:

• repo_path (required) — path to local git repository

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:

• org (required) — GitHub org/owner of the repository
• repo (required) — repository name
• head_sha — PR head SHA to look up; if omitted, returns the most recent gate verdicts for the repo

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

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_verdict, list_branches

Links

• Website
• GitHub
• GitHub Action