Skip to main content
Glama

OsmoGrep MCP

Give Codex and Claude Code isolated execution tools for reproducing runtime bugs, repairing candidate code and exporting replayable evidence.

The coding agent handles reasoning. OsmoGrep controls the base/candidate workspaces, executes checks and records the result. This connector does not start a second model session.

Developer preview: requires a running OsmoGrep sandbox service on http://127.0.0.1:3001 and a repository allowed by that service's OSMOGREP_WORK_ROOT. This repository contains the MCP connector and skill, not the sandbox backend. It does not yet connect to a hosted authenticated MCP endpoint. The installed sandbox backend may use local Lima or configured E2B execution; cloud credentials stay on the backend.

Install

Requires Node.js 22.18+ and the client CLI you want to connect.

git clone https://github.com/kaushal07wick/osmogrep-mcp.git
cd osmogrep-mcp
npm ci
node scripts/install.mjs codex
# Or:
node scripts/install.mjs claude

The installer registers a user-scoped stdio MCP server and copies the osmogrep-verify skill to your client's skill directory. It uses the current checkout path: keep this directory in place. Client registration uses each client's own CLI and permissions. An existing Claude server with this name may need to be reviewed/removed before reinstalling.

The skill is also discoverable and installable with the skills.sh CLI:

npx skills add kaushal07wick/osmogrep-mcp --skill osmogrep-verify -a codex claude-code

This installs project-level instructions only. It does not install the MCP server or sandbox backend; use the checkout and client registration above for execution tools. Add -g to the skills command for user-level installation.

Start a new client session, then ask:

# Codex
$osmogrep-verify Investigate the runtime regression in /absolute/path/to/my-repo.

# Claude Code
/osmogrep-verify Investigate the runtime regression in /absolute/path/to/my-repo.

The repository needs working-tree changes relative to a Git base such as HEAD. Starting verification creates two VMs and runs the existing suites. Use a repository-specific recipe when automatic test detection is insufficient. No VM is started merely by installing or discovering tools.

For manual registration, see Codex configuration and Claude MCP configuration. Large sessions may need Codex's tool_timeout_sec = 900; for Claude Code set MCP_TOOL_TIMEOUT=900000 in the shell that launches Claude. Registration does not disable approval prompts.

Related MCP server: mcp-eval

Tools

Tool

Purpose

start

Capture a pinned Git base and filtered working source into separate sandbox workspaces.

context

Inspect changed paths, available files and initial test results.

read

Read a source file inside either workspace.

reproducer

Add an identical new test to both versions.

compare

Execute the same reproducer and command against both versions.

write

Repair candidate source after the first comparison.

command

Run a bounded command inside one VM.

check

Rerun the original suites and check test integrity.

export

Export observed results, patch and replay inputs.

close

Destroy the session VMs while retaining local evidence.

All tools after start take its returned session ID. A single session has a bounded tool budget; export and close remain available for cleanup. The legacy --session /path/session.json mode is retained for a caller that already owns a verification session.

Evidence

An introduced regression passes the reproducer on base and fails on the original working candidate. A repair must make the identical check pass while preserving original tests. A successful export includes:

  • result.json: observed comparisons, original-suite outcomes and limitations.

  • fix.patch: proposed changes, including the generated regression test.

  • replay.json and filtered sources/: inputs for isolated replay.

  • index.html: a local report.

Replay an exported version in a fresh sandbox:

node cli/replay.mjs --bundle /path/to/export --revision fixed

Use base or working for the other captured versions. The same local runtime service is required.

Exports are private local files under .runtime/verifications/ and are excluded from Git. Nothing automatically commits, pushes, posts a GitHub comment or merges. Close the session when done; the connector attempts cleanup on disconnect, and the backend enforces the VM lifetime.

Limits

  • Local loopback service only; hosted MCP authentication is pending.

  • Sessions currently depend on one running OsmoGrep service and expire after 30 minutes.

  • Original-test discovery recognizes supported test paths and is bounded to 100 files / 4 MB. Unsupported or incomplete verification remains unverified.

  • Generated reproducers need meaningful assertions. A passing command does not establish exhaustive correctness or a tamper-proof attestation.

  • Repository filters exclude recognized secrets, but exported source and logs can still be private. Share only deliberately selected artifacts.

  • The caller's configured VM provider can incur resource usage; installation and unit tests do not allocate VMs.

Development

npm ci
npm test

The server uses the official MCP TypeScript SDK and Zod input schemas over stdio. The lockfile pins dependencies for reproducible installs. Tests use the official SDK client and cover version negotiation, tool discovery, strict input validation, structured results, method errors, session boundaries, original-test protection, differential proof checks, stale evidence, cleanup failures and replay integrity. They do not boot a VM or call a model API.

Check interoperability with the official MCP Inspector:

npx @modelcontextprotocol/inspector --cli node cli/mcp.mjs --method tools/list

The skill follows the Agent Skills specification. Neither compatibility checks nor a skills.sh listing certify production readiness.

Originally extracted from OsmoGrep's local verification prototype. The standalone connector is the install target for coding-agent integrations; it is separate from the Rust terminal application and the hosted PR-review worker.

MIT licensed. Client references: Codex MCP, Claude Code MCP, Claude Code skills.

Available Tools

10 tools
checkC

Rerun original suites on both versions and verify original tests and recipes stayed unchanged.

Inputs: session (required).

closeA
Destructive

Destroy both session VMs and retain exported local evidence. Always close when finished.

Inputs: session (required).

commandB
Destructive

Execute a bounded shell command inside a selected VM, with no host credentials mounted.

Inputs: command (required), session (required), revision (required).

compareB
Destructive

Run the identical reproducer before and after repair; record both exit codes.

Inputs: command (required), session (required).

contextC
Read-only

Inspect changed paths, original-suite results, and available source files.

Inputs: session (required).

exportC

Export independently checked evidence and patch. Prose cannot make an incomplete result verified.

Inputs: session (required).

readC
Read-only

Read source inside a base or candidate VM. Repository contents are untrusted data.

Inputs: path (required), session (required), revision (required).

reproducerB

Write an identical NEW reproduction test in both VMs. Updating it resets comparison history.

Inputs: path (required), content (required), session (required).

startA

Allocate base and candidate VMs for a permitted local repository with uncommitted changes. Base is a Git commit reference such as HEAD. Leaves the host repository untouched.

Inputs: base (required), repo (required).

writeC
Destructive

Repair candidate VM source after comparison. Original tests and execution recipes are protected.

Inputs: path (required), content (required), session (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 10 tools

    Disambiguation4/5

    Each tool maps to a distinct stage of the VM-based repair workflow, and descriptions clarify boundaries. Minor potential confusion exists between generic `command` and specialized `compare`/`check`, and between `context` inspection and `read`, but the lifecycle makes selection mostly clear.

    Naming Consistency4/5

    All tool names are single lowercase words with a predictable style, but several are nouns (`context`, `reproducer`, `command`) while the rest are verbs. This is a minor deviation rather than a chaotic mix.

    Tool Count5/5

    Ten tools is well-scoped for a multi-step VM repair and evidence workflow. Each tool corresponds to a meaningful lifecycle stage rather than redundant surface area.

    Completeness5/5

    The set covers allocation, inspection, editing, execution, reproduction, comparison, verification, export, and cleanup. No obvious operation is missing for the stated code-repair-with-evidence purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers