kenshocodemcp

# kenshocodemcp

A Model Context Protocol server for coding agents. It gives any MCP-capable client batched, token-efficient file and search operations with edits that are matched tolerantly and verified automatically.

It works with Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Zed, VS Code, and any other client that speaks MCP over stdio.

Two goals:

1. Save tokens. Batch many operations into one tool call, return compact results (symbol bodies, line ranges, grouped matches, diffs) instead of whole files, and cache repeated reads and searches so the model gets a short stub instead of the full payload again.

2. Improve accuracy. Apply edits through a tolerant matcher (absorbs CRLF, trailing whitespace, curly quotes, dashes), verify imports resolve before the model trusts them, catch broken syntax right after an edit, and always return a diff so the change is visible.

Tools

The server exposes one batch tool plus focused single-purpose tools.

codeops (recommended)

Runs an ordered batch of operations in a single call.

Example:

{
  "ops": [
    { "op": "exists", "paths": ["src/config.ts"] },
    { "op": "search", "pattern": "DEFAULT_TIMEOUT", "include": "**/*.ts" },
    { "op": "read", "path": "src/config.ts", "symbol": "defaultTimeout" },
    { "op": "edit", "path": "src/config.ts", "oldString": "timeout: 60", "newString": "timeout: 30" }
  ]
}

One round-trip instead of four, a symbol read instead of the whole file, and a returned diff instead of a re-read to confirm the change.

Focused tools

For clients or models that prefer narrow tools: read_file, edit_file, search_code, and run_command (only with --allow-shell).

Related MCP server: Coding Tools MCP

Install

Requires Node.js 20 or newer.

You do not need to clone this repository. Your MCP client launches it with npx.

Claude Code

claude mcp add kensho -- npx -y kenshocodemcp --root "C:\path\to\your\project" --allow-command npm

On macOS or Linux, use a forward-slash path, for example --root /home/you/project.

Claude Desktop, Cursor, Windsurf, Cline, and others

Add this to the client's MCP configuration file (for Claude Desktop this is claude_desktop_config.json; other clients use an equivalent mcpServers block):

{
  "mcpServers": {
    "kensho": {
      "command": "npx",
      "args": ["-y", "kenshocodemcp", "--root", "/absolute/path/to/your/project"]
    }
  }
}

On Windows, use "command": "cmd", "args": ["/c", "npx", "-y", "kenshocodemcp", "--root", "C:\\path\\to\\project"] if the client cannot find npx directly.

Generic MCP client (stdio)

Run the server with npx -y kenshocodemcp --root <dir> and connect over stdin and stdout.

Options

Safety defaults

• Sandboxed to --root. Paths that escape the workspace with .. or an absolute path outside it are refused unless --allow-outside-root is set.

• No shell by default. Shell is an exception you grant, in one of two ways:

  • Allowlist (recommended): --allow-command npm --allow-command git lets only those commands run. A command matches when it starts with the allowed words at a word boundary, so npm allows npm test but not npmx.

  • Unrestricted: --allow-shell allows any command. Only use it for workspaces and clients you fully trust.

• Chaining is blocked in allowlist mode. ;, &, |, backticks, $(, <, >, and newlines are refused, so an allowed command cannot be used to run a second one. Run one command per call.

How it saves tokens

• Batching: many operations per call means fewer model round-trips.

• Symbol and range reads: return just the function you need.

• Grouped search: matches are grouped by file and capped, so a common word does not flood the context.

• Diffs, not files: edits and writes return a unified diff.

• Caching: a repeated read or search returns a short [cached] ... stub. An edit to a file invalidates its cache entries.

• Budgets: large results are trimmed to the head and tail with an explicit note about what was elided.

How it improves accuracy

• Tolerant edits: an exact match is tried first, then a normalized match that ignores line-ending, whitespace, and quote drift. When a match is ambiguous or missing, the error says why and tells the model to re-read.

• Verification after every edit: unbalanced braces and brackets are caught immediately, and local imports are checked against the filesystem to catch hallucinated paths.

• Optional typecheck and lint: wire in --typecheck and --lint to have real compiler or linter errors reported right after an edit.

Development

git clone https://github.com/scr1ptyureishirayukimikotofujiwarasayo/kenshocodemcp
cd kenshocodemcp
npm install
npm test          # unit and integration tests
npm run typecheck
npm run build     # emits dist/

Run locally against a project:

node dist/index.js --root /path/to/project

Layout

src/core/     portable engine: tokens, diff, edit, read, search, compress,
              verify, verify-edit, cache, text
src/engine/   host (sandboxed filesystem + shell) and the batch op engine
src/index.ts  MCP server: tool registration and stdio transport
src/config.ts CLI argument parsing
test/         node:test suites (engine and core)

The engine is host-agnostic. It depends only on a small Host interface, so it can be tested with an in-memory filesystem or re-hosted elsewhere.

Relationship to kenshocodeplugin

This server is extracted from the kenshocodeplugin OpenCode plugin, and shares its portable core. The OpenCode plugin integrates with OpenCode's permission system and hooks. This package brings the same engine to any MCP client.

License

MIT. See LICENSE.