# kenshocodemcp

A [Model Context Protocol](https://modelcontextprotocol.io) 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.

| op | purpose |
| --- | --- |
| `read` | whole file, a line range, or a named `symbol` |
| `search` | regex or literal search, grouped by file |
| `list` | directory listing |
| `exists` | confirm paths are real before referencing them |
| `edit` | tolerant, validated edit, returns a diff, then verifies |
| `write` | create or replace a file, returns a diff, then verifies |
| `verify` | syntax and import checks on a file |
| `run` | shell command (only with `--allow-shell`) |
| `stats` | token savings for this session |

Example:

```json
{
  "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`).

---

## Install

Requires **Node.js 20 or newer**.

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

### Claude Code

```sh
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):

```json
{
  "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

| flag | default | meaning |
| --- | --- | --- |
| `--root <dir>` | current directory | workspace root every path is resolved against |
| `--allow-command <name>` | none | allow one command to run. Repeatable. Matched by its leading words |
| `--allow-shell` | off | allow any shell command (unrestricted; use with care) |
| `--allow-outside-root` | off | allow paths outside `--root` |
| `--typecheck <cmd>` | none | run after edits, e.g. `"tsc --noEmit"`. Only errors are returned |
| `--lint <cmd>` | none | run after edits, e.g. `"eslint ."` |
| `--no-cache` | cache on | disable result caching |
| `--no-verify` | verify on | disable post-edit verification |
| `--max-tokens <n>` | `1500` | token budget per result before head/tail elision |

### 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

```sh
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:

```sh
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](https://github.com/scr1ptyureishirayukimikotofujiwarasayo/Kenshocode-plugin)
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](LICENSE).