rosentic-mcp 0.1.0__tar.gz

rosentic_mcp-0.1.0/.gitignore

@@ -0,0 +1,245 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+SESSION-SUMMARY*.md
+
+.rosentic/
+
+# macOS
+.DS_Store
+
+# Node / local browser tooling
+/node_modules/
+
+# Cloudflare Wrangler local state
+/.wrangler/
+api/.wrangler/
+daily-digest/.wrangler/
+email-capture/.wrangler/
+
+# Local scan artifacts
+/scans/*.json
+/scans/*/
+/scans-before-identity/
+/rosentic-report-*.html
+
+# Outreach pipeline generated data
+/outreach/*.jsonl
+/outreach/engine-observations.uploaded-lines.txt
+/outreach/drafts/
+/outreach/logs/
+/outreach/*.csv
+/outreach/*.docx
+/outreach-log.csv
+/maintainer-emails.csv
+
+# Prospecting notes / local research archives
+/research/
+/issues/
+
+# Separate GitHub Action checkout; do not commit as a nested repo.
+/rosentic-action/

rosentic_mcp-0.1.0/LICENSE

@@ -0,0 +1,8 @@
+Business Source License 1.1
+
+Copyright (c) 2026 Rosentic. All rights reserved.
+
+Rosentic is licensed under the Business Source License 1.1 unless a separate
+written agreement with Rosentic says otherwise.
+
+For licensing inquiries, visit https://rosentic.com or contact hello@rosentic.com.

rosentic_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: rosentic-mcp
+Version: 0.1.0
+Summary: MCP server for Rosentic — deterministic cross-branch conflict detection for AI coding agents
+Project-URL: Homepage, https://rosentic.com
+Project-URL: Repository, https://github.com/Rosentic/rosentic-engine
+Project-URL: Issues, https://github.com/Rosentic/rosentic-engine/issues
+Author-email: Rosentic <hello@rosentic.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,code-review,git,mcp,merge-conflicts,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3.1.0
+Description-Content-Type: text/markdown
+
+# Rosentic MCP Server
+
+CI checks each PR against main. It doesn't check open PRs against each other.
+
+Rosentic does. Install one package. Your coding agent checks 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 every open PR against every other open PR. Deterministic static analysis. No LLM. 12 languages. Code never leaves your machine.
+
+## Install
+
+```bash
+pip install rosentic-mcp
+```
+
+## Configure
+
+### Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "rosentic": {
+      "command": "rosentic-mcp"
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Add to MCP settings:
+
+```json
+{
+  "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.
+
+### `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
+
+## 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)
+
+## Links
+
+- [Website](https://rosentic.com)
+- [GitHub](https://github.com/Rosentic/rosentic-engine)
+- [GitHub Action](https://github.com/Rosentic/rosentic-engine#github-action)

rosentic_mcp-0.1.0/README-mcp.md

@@ -0,0 +1,99 @@
+# Rosentic MCP Server
+
+CI checks each PR against main. It doesn't check open PRs against each other.
+
+Rosentic does. Install one package. Your coding agent checks 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 every open PR against every other open PR. Deterministic static analysis. No LLM. 12 languages. Code never leaves your machine.
+
+## Install
+
+```bash
+pip install rosentic-mcp
+```
+
+## Configure
+
+### Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "rosentic": {
+      "command": "rosentic-mcp"
+    }
+  }
+}
+```
+
+### Cursor / VS Code
+
+Add to MCP settings:
+
+```json
+{
+  "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.
+
+### `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
+
+## 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)
+
+## Links
+
+- [Website](https://rosentic.com)
+- [GitHub](https://github.com/Rosentic/rosentic-engine)
+- [GitHub Action](https://github.com/Rosentic/rosentic-engine#github-action)

rosentic_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rosentic-mcp"
+version = "0.1.0"
+description = "MCP server for Rosentic — deterministic cross-branch conflict detection for AI coding agents"
+readme = "README-mcp.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Rosentic", email = "hello@rosentic.com" }]
+keywords = ["mcp", "git", "merge-conflicts", "ai-agents", "code-review", "tree-sitter"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+    "fastmcp>=3.1.0",
+]
+
+[project.scripts]
+rosentic-mcp = "rosentic.mcp_server:main"
+
+[project.urls]
+Homepage = "https://rosentic.com"
+Repository = "https://github.com/Rosentic/rosentic-engine"
+Issues = "https://github.com/Rosentic/rosentic-engine/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rosentic"]
+
+[tool.hatch.build.targets.sdist]
+include = ["rosentic/", "LICENSE", "README-mcp.md"]

rosentic_mcp-0.1.0/rosentic/__init__.py

@@ -0,0 +1 @@
+"""Rosentic — deterministic cross-branch conflict detection."""

rosentic_mcp-0.1.0/rosentic/mcp_server.py

@@ -0,0 +1,577 @@
+"""Rosentic MCP server - cross-branch conflict detection for coding agents.
+
+Runs the Rosentic engine via Docker (ghcr.io/rosentic/rosentic-engine).
+No engine source is distributed with this package.
+
+Install: pip install rosentic-mcp
+Run:     rosentic-mcp
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import urllib.parse
+import urllib.request
+from typing import Annotated, Any, Literal
+
+from fastmcp import FastMCP
+from pydantic import Field
+
+_DOCKER_IMAGE = "ghcr.io/rosentic/rosentic-engine:latest"
+_SCAN_TIMEOUT_SECONDS = 300
+_CACHE_TTL_SECONDS = 60
+
+mcp = FastMCP(
+    name="rosentic",
+    instructions=(
+        "Use Rosentic to check a git repository for deterministic cross-branch "
+        "merge conflicts across function signatures, HTTP routes, and schemas."
+    ),
+)
+
+_scan_cache: dict[str, dict[str, Any]] = {}
+
+
+def _find_docker() -> str:
+    for cmd in ("docker", "podman"):
+        if shutil.which(cmd):
+            return cmd
+    raise RuntimeError(
+        "Docker is required but not found on PATH. "
+        "Install Docker Desktop (https://docker.com/products/docker-desktop) "
+        "or Podman, then try again."
+    )
+
+
+def _run_git(repo_path: str, args: list[str], timeout: int = 20) -> str:
+    try:
+        proc = subprocess.run(
+            ["git", "-C", repo_path, *args],
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError("git executable was not found on PATH") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise TimeoutError(f"git command timed out after {timeout}s") from exc
+    if proc.returncode != 0:
+        detail = proc.stderr.strip() or proc.stdout.strip() or f"git exited {proc.returncode}"
+        raise ValueError(detail)
+    return proc.stdout
+
+
+def _require_repo(repo_path: str) -> str:
+    path = os.path.abspath(os.path.expanduser(repo_path))
+    if not os.path.isdir(path):
+        raise ValueError(f"repo_path does not exist: {path}")
+    if not os.path.isdir(os.path.join(path, ".git")):
+        raise ValueError(f"repo_path is not a git repository: {path}")
+    return path
+
+
+def _current_branch(repo_path: str) -> str:
+    return _run_git(repo_path, ["rev-parse", "--abbrev-ref", "HEAD"]).strip()
+
+
+def _require_branch(repo_path: str, branch: str, label: str = "branch") -> None:
+    try:
+        _run_git(repo_path, ["rev-parse", "--verify", "--quiet", branch])
+    except ValueError as exc:
+        raise ValueError(f"{label} does not exist in this repository: {branch}") from exc
+
+
+def _repo_name(repo_path: str) -> tuple[str, str]:
+    try:
+        url = _run_git(repo_path, ["config", "--get", "remote.origin.url"]).strip()
+    except Exception:
+        return "local", os.path.basename(repo_path.rstrip(os.sep)) or "repo"
+
+    name = url.rstrip("/")
+    if name.endswith(".git"):
+        name = name[:-4]
+    if ":" in name and "/" in name and not name.startswith("http"):
+        name = name.split(":", 1)[1]
+    else:
+        name = urllib.parse.urlparse(name).path.lstrip("/")
+    parts = [p for p in name.split("/") if p]
+    if len(parts) >= 2:
+        return parts[-2], parts[-1]
+    return "local", parts[-1] if parts else (os.path.basename(repo_path) or "repo")
+
+
+def _branch_count(repo_path: str) -> int:
+    try:
+        out = _run_git(repo_path, ["branch", "--list"])
+        return len([line for line in out.splitlines() if line.strip()])
+    except Exception:
+        return 0
+
+
+def _cache_key(repo_path: str, base: str, target_branch: str | None,
+               branch_list: list[str] | None = None) -> str:
+    bl = ",".join(sorted(branch_list)) if branch_list else ""
+    return f"{os.path.abspath(repo_path)}::{base}::{target_branch or '*'}::{bl}"
+
+
+def _cached_scan(repo_path: str, base: str, target_branch: str | None,
+                 branch_list: list[str] | None = None) -> dict[str, Any] | None:
+    entry = _scan_cache.get(_cache_key(repo_path, base, target_branch, branch_list))
+    if not entry:
+        return None
+    if time.time() - entry.get("timestamp", 0) > _CACHE_TTL_SECONDS:
+        return None
+    return entry.get("data")
+
+
+def _store_scan(repo_path: str, base: str, target_branch: str | None, data: dict[str, Any],
+                branch_list: list[str] | None = None) -> None:
+    _scan_cache[_cache_key(repo_path, base, target_branch, branch_list)] = {
+        "timestamp": time.time(),
+        "data": data,
+    }
+
+
+def _pair_involves_branch(pair_key: str, branch: str) -> bool:
+    parts = [p.strip() for p in pair_key.split("<>")]
+    if len(parts) != 2:
+        return False
+    short = branch.split("/", 1)[-1]
+    return any(part == branch or part.split("/", 1)[-1] == short for part in parts)
+
+
+def _filter_scan_to_branch(data: dict[str, Any], branch: str) -> dict[str, Any]:
+    pairs = data.get("pairs", {})
+    filtered_pairs = {
+        pair: conflicts
+        for pair, conflicts in pairs.items()
+        if _pair_involves_branch(pair, branch)
+    }
+
+    if not filtered_pairs and pairs:
+        return {
+            **data,
+            "pairs": {},
+            "unique_findings": [],
+            "unique_summary": {
+                "unique_total": 0,
+                "unique_unsafe": 0,
+                "unique_warning": 0,
+                "by_layer": {},
+            },
+            "mcp_note": f"No scanned branch pair involved '{branch}'.",
+        }
+
+    finding_ids = {
+        c.get("finding_id")
+        for conflicts in filtered_pairs.values()
+        if isinstance(conflicts, list)
+        for c in conflicts
+        if c.get("finding_id")
+    }
+    unique = [
+        f for f in data.get("unique_findings", [])
+        if f.get("finding_id") in finding_ids
+        or any(inst.get("pair") in filtered_pairs for inst in f.get("instances", []))
+    ]
+
+    return {
+        **data,
+        "pairs": filtered_pairs,
+        "unique_findings": unique,
+        "unique_summary": _summarize_unique(unique),
+    }
+
+
+def _summarize_unique(findings: list[dict[str, Any]]) -> dict[str, Any]:
+    by_layer: dict[str, int] = {}
+    unsafe = 0
+    warning = 0
+    for finding in findings:
+        verdict = finding.get("verdict")
+        if verdict == "UNSAFE":
+            unsafe += 1
+        elif verdict == "WARNING":
+            warning += 1
+        layer = _finding_layer(finding)
+        by_layer[layer] = by_layer.get(layer, 0) + 1
+    return {
+        "unique_total": len(findings),
+        "unique_unsafe": unsafe,
+        "unique_warning": warning,
+        "by_layer": by_layer,
+    }
+
+
+def _run_scan(repo_path: str, base: str, target_branch: str | None,
+              branch_list: list[str] | None = None) -> dict[str, Any]:
+    cached = _cached_scan(repo_path, base, target_branch, branch_list)
+    if cached is not None:
+        return cached
+
+    docker = _find_docker()
+    output_file = f"rosentic-mcp-{hashlib.sha256(f'{repo_path}:{time.time()}'.encode()).hexdigest()[:12]}.json"
+    output_path = os.path.join(repo_path, ".rosentic", output_file)
+
+    scan_args = [
+        "scan-all", "/repo",
+        "--base", base,
+        "--format", "json",
+        "--timeout", str(_SCAN_TIMEOUT_SECONDS),
+        "--output", f"/repo/.rosentic/{output_file}",
+    ]
+    if branch_list:
+        scan_args.extend(["--branch-list", ",".join(branch_list)])
+    else:
+        scan_args.extend(["--max-branches", "30"])
+
+    cmd = [
+        docker, "run", "--rm",
+        "--entrypoint", "python3",
+        "-v", f"{repo_path}:/repo",
+        _DOCKER_IMAGE,
+        "/rosentic/detect.py", *scan_args,
+    ]
+
+    start = time.time()
+    try:
+        proc = subprocess.run(
+            cmd,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=_SCAN_TIMEOUT_SECONDS + 60,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise TimeoutError(
+            f"Rosentic scan timed out after {_SCAN_TIMEOUT_SECONDS}s. "
+            "Try a narrower branch set or run again after the repo index is warm."
+        ) from exc
+    duration = time.time() - start
+
+    if not os.path.exists(output_path):
+        detail = proc.stderr.strip() or proc.stdout.strip() or f"docker exited {proc.returncode}"
+        raise RuntimeError(f"Rosentic scan did not produce JSON output: {detail}")
+
+    with open(output_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    try:
+        os.remove(output_path)
+    except OSError:
+        pass
+
+    data["_mcp"] = {
+        "repo_path": repo_path,
+        "base": base,
+        "target_branch": target_branch,
+        "scan_duration_seconds": round(duration, 3),
+        "stderr_tail": "\n".join(proc.stderr.splitlines()[-20:]),
+    }
+
+    if target_branch:
+        data = _filter_scan_to_branch(data, target_branch)
+        data.setdefault("_mcp", {})
+        data["_mcp"].update({
+            "repo_path": repo_path,
+            "base": base,
+            "target_branch": target_branch,
+            "scan_duration_seconds": round(duration, 3),
+        })
+
+    _store_scan(repo_path, base, target_branch, data, branch_list)
+    _post_telemetry_async(repo_path, data, duration)
+    return data
+
+
+def _post_telemetry_async(repo_path: str, data: dict[str, Any], duration: float) -> None:
+    def _send() -> None:
+        try:
+            org, repo = _repo_name(repo_path)
+            summary = data.get("summary", {}) or {}
+            unique_summary = data.get("unique_summary", {}) or {}
+            payload = {
+                "schema_version": "mcp-v1",
+                "org": org,
+                "repo": repo,
+                "branch_count": str(_branch_count(repo_path)),
+                "conflict_count": str(unique_summary.get("unique_total", 0)),
+                "scan_duration_seconds": f"{duration:.2f}",
+                "agent": "mcp",
+                "engine_version": "docker",
+                "pairs_scanned": str(summary.get("total_pairs", 0)),
+                "pairs_with_conflicts": str(summary.get("pairs_with_conflicts", 0)),
+            }
+            body = urllib.parse.urlencode(payload).encode("utf-8")
+            req = urllib.request.Request(
+                "https://email-capture.rosentic.com/telemetry",
+                data=body,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                method="POST",
+            )
+            urllib.request.urlopen(req, timeout=3).read()
+        except Exception:
+            pass
+
+    threading.Thread(target=_send, daemon=True).start()
+
+
+def _finding_layer(finding: dict[str, Any]) -> str:
+    layer = finding.get("layer", "")
+    if layer.startswith("L2"):
+        return "L2 route"
+    if layer.startswith("L3"):
+        return "L3 contract"
+    if layer.startswith("L1"):
+        return "L1 signature"
+    ctype = finding.get("type")
+    if ctype == "api_contract":
+        return "L2 route"
+    if ctype in {"graphql_schema", "typed_contract", "proto_contract"}:
+        return "L3 contract"
+    return "L1 signature"
+
+
+def _finding_title(finding: dict[str, Any]) -> str:
+    route = finding.get("route")
+    method = finding.get("http_method") or finding.get("method", "")
+    if route:
+        return f"{method.strip()} {route}".strip() if method else str(route)
+    if finding.get("function"):
+        return f"{finding['function']}()"
+    if finding.get("gql_type") and finding.get("gql_field"):
+        return f"{finding['gql_type']}.{finding['gql_field']}"
+    if finding.get("proto_message") and finding.get("proto_field"):
+        return f"{finding['proto_message']}.{finding['proto_field']}"
+    return finding.get("finding_id") or "conflict"
+
+
+def _finding_file(finding: dict[str, Any]) -> str:
+    return (
+        finding.get("defined_in")
+        or finding.get("contract_file")
+        or finding.get("schema_file")
+        or finding.get("proto_file")
+        or finding.get("called_in")
+        or finding.get("client_file")
+        or finding.get("operation_file")
+        or "unknown file"
+    )
+
+
+def _conflict_detail(finding: dict[str, Any]) -> str:
+    desc = finding.get("description")
+    if desc:
+        return desc
+    func = finding.get("function")
+    if func:
+        old = finding.get("old_required", "?")
+        new = finding.get("new_required", "?")
+        return f"{func}() changed from {old} to {new} required params."
+    return "Cross-branch contract conflict."
+
+
+def _build_summary(data: dict[str, Any], branch: str | None) -> str:
+    findings = data.get("unique_findings", []) or []
+    target = branch or data.get("_mcp", {}).get("target_branch") or "selected branches"
+    if not findings:
+        note = data.get("mcp_note")
+        suffix = f" {note}" if note else ""
+        return f"Rosentic found no conflicts for {target}.{suffix}"
+
+    verdict_counts: dict[str, int] = {}
+    layer_counts: dict[str, int] = {}
+    for finding in findings:
+        verdict = finding.get("verdict") or finding.get("severity") or "WARNING"
+        verdict_counts[verdict] = verdict_counts.get(verdict, 0) + 1
+        layer = _finding_layer(finding)
+        layer_counts[layer] = layer_counts.get(layer, 0) + 1
+
+    most_critical = sorted(
+        findings,
+        key=lambda f: (
+            0 if f.get("verdict") == "UNSAFE" else 1,
+            -float(f.get("confidence_score") or 0),
+            _finding_title(f),
+        ),
+    )[0]
+
+    verdict_part = ", ".join(f"{count} {name}" for name, count in sorted(verdict_counts.items()))
+    layer_part = ", ".join(f"{count} {name}" for name, count in sorted(layer_counts.items()))
+    recommendation = (
+        "Recommendation: inspect the UNSAFE findings first and update the stale branch before merging."
+        if verdict_counts.get("UNSAFE")
+        else "Recommendation: review the WARNING findings; Rosentic found plausible but not fully proven conflicts."
+    )
+
+    return (
+        f"Rosentic found {len(findings)} unique conflict(s) for {target}: {verdict_part}. "
+        f"Layer breakdown: {layer_part}. "
+        f"Most critical: {_finding_title(most_critical)} in {_finding_file(most_critical)} - "
+        f"{_conflict_detail(most_critical)} "
+        f"{recommendation}"
+    )
+
+
+@mcp.tool
+def check_conflicts(
+    repo_path: Annotated[str, Field(description="Absolute or relative path to the local git repository to scan.")],
+    branch: Annotated[
+        str | None,
+        Field(description="Branch to check against other active branches. If omitted, the current checked-out branch is used."),
+    ] = None,
+    branches: Annotated[
+        list[str] | None,
+        Field(description="Explicit list of branch names to scan. Bypasses enumeration and age filters. Use this when you know exactly which branches to check."),
+    ] = None,
+    base: Annotated[
+        str,
+        Field(description="Base branch used for branch diffs. Defaults to main."),
+    ] = "main",
+    format: Annotated[
+        Literal["summary", "json"],
+        Field(description="Use summary for concise text. Use json only when the agent needs finding_ids or full structured findings."),
+    ] = "summary",
+) -> str | list[dict[str, Any]]:
+    """Check a local git repository for Rosentic cross-branch conflicts.
+
+    Call this before merging or after an agent edits a branch. The summary format
+    is the normal agent-facing response. The json format returns unique findings
+    with finding_id values for follow-up explain_conflict calls.
+    """
+    repo_path = _require_repo(repo_path)
+
+    if branches:
+        target_branch = None
+    elif branch:
+        target_branch = branch
+        _require_branch(repo_path, target_branch)
+    else:
+        current = _current_branch(repo_path)
+        target_branch = None if current == base else current
+
+    branch_list = branches if branches else None
+    data = _run_scan(repo_path, base, target_branch, branch_list=branch_list)
+
+    if format == "json":
+        return data.get("unique_findings", []) or []
+    return _build_summary(data, target_branch)
+
+
+@mcp.tool
+def explain_conflict(
+    repo_path: Annotated[str, Field(description="Absolute or relative path to the local git repository that was scanned.")],
+    finding_id: Annotated[str, Field(description="finding_id returned by check_conflicts with format=json.")],
+) -> str:
+    """Explain one Rosentic finding and what the developer should do next.
+
+    Call this after check_conflicts(format="json") when the user asks why a
+    specific finding matters or how to resolve it. Uses the recent scan cache
+    when available and falls back to a fresh scan.
+    """
+    repo_path = _require_repo(repo_path)
+    data = None
+    now = time.time()
+    for key, entry in list(_scan_cache.items()):
+        if key.startswith(f"{repo_path}::") and now - entry.get("timestamp", 0) <= _CACHE_TTL_SECONDS:
+            candidate = entry.get("data") or {}
+            if any(f.get("finding_id") == finding_id for f in candidate.get("unique_findings", []) or []):
+                data = candidate
+                break
+    if data is None:
+        data = _run_scan(repo_path, "main", None)
+
+    finding = next((f for f in data.get("unique_findings", []) or [] if f.get("finding_id") == finding_id), None)
+    if finding is None:
+        return f"No finding with id {finding_id} was found in the recent Rosentic scan."
+
+    verdict = finding.get("verdict") or finding.get("severity") or "WARNING"
+    layer = _finding_layer(finding)
+    title = _finding_title(finding)
+    detail = _conflict_detail(finding)
+    source = _finding_file(finding)
+    instances = finding.get("instances", []) or []
+    affected = []
+    for inst in instances[:5]:
+        pair = inst.get("pair")
+        file = inst.get("called_in") or inst.get("client_file") or inst.get("operation_file") or inst.get("consumer_file")
+        line = inst.get("call_line") or inst.get("client_line") or inst.get("operation_line") or inst.get("line")
+        if pair or file:
+            affected.append(f"- {pair or 'branch pair'}: {file or 'unknown file'}{f':{line}' if line else ''}")
+
+    what_to_do = (
+        "Update the consumer branch to match the producer change, or merge/rebase so both sides agree before merging."
+        if verdict == "UNSAFE"
+        else "Review the evidence manually; Rosentic has a plausible link but is not treating it as proven unsafe."
+    )
+
+    parts = [
+        f"{title} - {verdict} ({layer})",
+        "",
+        f"What changed: {detail}",
+        f"Producer evidence: {source}",
+    ]
+    if affected:
+        parts.extend(["Affected consumers:", *affected])
+    parts.extend([
+        f"Why it matters: {verdict} is Rosentic's final gate after compatibility, confidence, and identity checks.",
+        f"What to do: {what_to_do}",
+    ])
+    return "\n".join(parts)
+
+
+@mcp.tool
+def list_branches(
+    repo_path: Annotated[str, Field(description="Absolute or relative path to the local git repository to inspect.")],
+) -> list[dict[str, str]]:
+    """List local branches so an agent can choose a branch before scanning.
+
+    Call this when the user has not named a branch or asks what branches Rosentic
+    can scan. Results are sorted by most recent commit date.
+    """
+    repo_path = _require_repo(repo_path)
+    out = _run_git(
+        repo_path,
+        ["for-each-ref", "--sort=-committerdate", "--format=%(refname:short)\t%(committerdate:iso8601)", "refs/heads/"],
+    )
+    branches = []
+    current = _current_branch(repo_path)
+    for line in out.splitlines():
+        if not line.strip():
+            continue
+        name, _, date = line.partition("\t")
+        branches.append({
+            "name": name.strip(),
+            "last_commit_date": date.strip(),
+            "current": str(name.strip() == current).lower(),
+        })
+    return branches
+
+
+def main():
+    if any(arg in {"-h", "--help"} for arg in sys.argv[1:]):
+        print("Rosentic MCP server (stdio)")
+        print("")
+        print("Usage: rosentic-mcp")
+        print("")
+        print("Tools: check_conflicts, explain_conflict, list_branches")
+        print("")
+        print(f"Engine: {_DOCKER_IMAGE}")
+        raise SystemExit(0)
+
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()