Skip to content
Conduit

mcp server

scalpel

Precise, atomic file editing for code and text over MCP

0langa/scalpelcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • Node.js 20 or newer
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "0langa-scalpel": {
      "command": "npx",
      "args": [
        "-y",
        "scalpel"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 21, 2026

Scalpel

CI Release

Precise, atomic file editing for code and text over MCP.

Status

1.1.0 stable. Edits keep each file's line-ending style, and an edit that grows a file past maxReadBytes reports success. Expanded hardening (public-corpus stress, race/interference coverage, and the killed-process fault matrix) passed on Windows and on Linux for 1.0.0; 1.1.0 passes the starter hardening lane on both. Streaming mutation for oversized patch/append/prepend targets, an explicit transaction recovery state machine, and commit-time revalidation for move are all implemented and proven.

See the 1.1.0 release notes for the changes and upgrade notes since 1.0.0, and the 1.0.0 release notes for the full safety claim, evidence summary, supported platforms, and unsupported cases.

Implemented Tools

  • config
  • stat
  • read
  • read_chunk
  • list_dir
  • grep
  • create
  • patch
  • batch_edit
  • insert
  • delete_range
  • replace_between_markers
  • append
  • prepend
  • diff
  • move

Run

Install from the GitHub release tarball:

npm install https://github.com/0langa/scalpel/releases/download/v1.1.0/scalpel-1.1.0.tgz
node node_modules/scalpel/dist/index.js

Scalpel is not published to the npm registry for this release; install from the release tarball or from source.

Install dependencies for local development:

pnpm install

Start the stdio server:

pnpm dev

Build:

pnpm build

Run the built package entry:

pnpm build
node dist/index.js

Codex CLI setup after building locally:

codex mcp add scalpel --env SCALPEL_ROOTS=/repo -- node /path/to/scalpel/dist/index.js
codex mcp list

Equivalent config.toml entry:

[mcp_servers.scalpel]
command = "node"
args = ["/path/to/scalpel/dist/index.js"]

[mcp_servers.scalpel.env]
SCALPEL_ROOTS = "/repo"

Verify:

pnpm typecheck
pnpm test
pnpm build
pnpm test:mcp-smoke
pnpm test:package-smoke

Full release validation:

pnpm validate

Runtime Behavior

  • Workspace access is confined to configured roots.
  • If SCALPEL_ROOTS is unset, Scalpel defaults to the current working directory it was started in.
  • config reports the live roots for the current MCP server process.
  • Existing Codex/MCP client threads may need a server reload or new thread before newly added tool schemas appear.
  • Existing symlinks in the traversed path are rejected; grep and list_dir report symlinks and junctions instead of following them.
  • Hidden paths are blocked when allowHiddenPaths is disabled.
  • Read-only files are not replaced: mutating tools fail with PERMISSION_DENIED. Replacing a file keeps its permission bits on POSIX; the replacement stays owner-only (0600) until its content is complete.
  • Full-text tools reject files above maxReadBytes with FILE_TOO_LARGE; use read_chunk for bounded reads. The limit applies to the file an edit starts from, so an edit that grows a file past it still succeeds.
  • Binary and invalid UTF-8 files fail with explicit text-tool errors.
  • Mutating tools support dry_run; content tools return unified diffs and move returns a move plan.
  • Operation journaling is optional and records metadata only, never file content.
  • MCP failures are returned with isError: true, text containing the Scalpel error code, and structuredContent.error.
  • Read-only MCP resources expose Scalpel safety, tool contract, testing, and live config context.

Edit Semantics

  • patch and batch_edit default to occurrence: "unique" and fail on ambiguity.
  • insert is line-oriented. If inserted content lacks a trailing newline, Scalpel normalizes it to the file's native EOL before splicing.
  • A UTF-8 BOM stays at the start of the file through every edit; line-oriented edits and prepend add text after it.
  • Text written into an existing file takes that file's line-ending style: LF line breaks sent to an all-CRLF file are written as CRLF, and CRLF sent to an all-LF file becomes LF. Mixed files and new files get the text as given; create always writes its content exactly. A patch that changes nothing but line breaks (old_string "\r\n", new_string "\n") is applied as given, so a file can still be converted on purpose.
  • replace_between_markers preserves the original marker lines exactly once and rejects new_content that repeats either marker.
  • read succeeds on empty files and returns content: "", lines: 0, and range: { start_line: 1, end_line: 0 }.
  • Mutating tools support hash and mtime preconditions where the target path exists; missing-file creation rejects supplied expectations.

Configuration

SCALPEL_ROOTS

  • Optional
  • Path-delimited list of allowed workspace roots
  • Defaults to the current working directory when unset

Example:

SCALPEL_ROOTS=/repo pnpm dev

SCALPEL_JOURNAL_ENABLED

  • Optional
  • Enable with true or 1
  • Default: disabled

SCALPEL_JOURNAL_PATH

  • Optional JSONL journal path
  • Defaults to .scalpel-journal.jsonl under the first root when journaling is enabled

SCALPEL_DURABILITY

  • Optional
  • Set to strict to flush temp-file content before rename and attempt parent-directory flush
  • Default: best-effort atomic rename without explicit durability flush
  • Parent-directory flush support is platform-dependent; unsupported flushes are reported as warnings

SCALPEL_RENAME_RETRY_MS

  • Optional
  • Windows only: how long a write or move keeps retrying a rename that another process (antivirus, indexer, sync client, editor) blocks by holding the file open
  • Default: 5000

Safety Model Summary

Full definitions live in docs/SAFETY_MODEL.md (safety model version scalpel-safety-model-v1). Final release notes only use terms like "crash-safe" or "race-proof" when linked to that document and backed by hardening evidence.

  • Crash-safe: startup recovery classifies every pending transaction as committed, aborted, or unrecoverable from on-disk evidence, and never silently accepts unknown partial state.
  • Race-proof: mutations serialize on their target paths in-process and across cooperative Scalpel processes; external interference before or after commit fails closed or is reported as a conflict; move revalidates source, destination, and destination parent directory immediately before renaming.
  • Large-scale: patch, append, and prepend stream oversized existing UTF-8 files above maxReadBytes with bounded memory; expanded public-corpus traversal is proven on Windows and Linux.
  • Recoverable: transaction and recovery records are metadata-only and never contain file content.

Known Unsupported Cases

  • Malicious same-user modification after Scalpel reports success.
  • Cross-device moves: detected via EXDEV and rejected with CROSS_DEVICE_MOVE_NOT_SUPPORTED; no copy/delete fallback.
  • Network filesystems and sync folders with non-standard rename/fsync semantics.
  • Binary byte-edit workflows and parser-aware semantic edits.
  • batch_edit, insert, delete_range, and replace_between_markers still require the full file to fit within maxReadBytes.

Docs

Internal/project-history reference (handbook, roadmap, spec, sprint plan):

↑↓ navigate openesc close