# dsh-claude-mcp

Hand one task to the **Claude Code CLI** on this machine, and get the result back
cleanly — while Claude cannot touch your project files. Good for reviewing a plan,
a code change or a PR, or for getting a second opinion.

## What it does

- **Runs one Claude Code task for you.** Give it a complete, self-contained job
  ("review this plan", "review this change"), it runs `claude -p`, and brings the
  answer back.
- **Keeps Claude out of your files.** Claude reads the directories you name, but
  the only place it can write is its own throwaway run directory.
- **Hands back a list, not a wall of text.** You get Claude's final message plus a
  manifest of what it produced: name, size, and a `sha256` checksum. Open what you
  need, decide for yourself, then copy the parts you approve into your project.
- **One tool.** Nothing else to learn and nothing else to configure.

## Requirements

Node.js 22.19 or newer, or 24 or newer, plus a working, already-signed-in `claude` command on the same machine.

## Install

1. Append the block below to `~/.dsh/profiles/<your profile>/cordis.patch.yml`,
   replacing every `/absolute/path/...` with a real absolute path:

```yaml
- insert:
    - id: mcp-claude
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        transport: stdio
        serverName: claude
        command: /absolute/path/to/node
        args:
          - /absolute/path/to/dsh-claude-mcp/src/server.mjs
        cwd: /absolute/path/to/your/workspace
        toolCallTimeoutMs: 900000
        failOnStartupError: true
```

Absolute paths matter: a desktop app launched from the Finder inherits a minimal `PATH`, so a bare
`node` or a relative path will not resolve.

2. **If the tool does not appear, restart the app once.** A profile that reloads its patches live
   picks the row up on its own; the desktop profile declares no live reload.

You then have one extra tool: `mcp__claude__run`.

## Usage

Ask me for a review, or anything else you want a second opinion on, and I will
call it. What you can specify:

| Argument | Required | Meaning |
| --- | --- | --- |
| `prompt` | yes | The whole job, written out. Claude cannot see our conversation, so say which files to read and which file to write. |
| `model` | no | Which Claude model or alias to use, for example `sonnet`. Leave it out to use your own Claude Code settings. |
| `files` | no | Report only these files. Leave it out to report everything the run produced. |
| `readDirs` | no | Extra directories Claude may read. Defaults to the configured workspace. |
| `timeoutMs` | no | How long this run may take, in milliseconds. Default: 15 minutes. |
| `maxBudgetUsd` | no | Optional spending ceiling for the run. |

A run looks like this:

```
ok  exit=0  140.1s  model=sonnet  permission=dontAsk
artifact   <workspace>/.claude-staging/run-20261001-191307-9c44/work
final message
-------------
review written to review.md
artifacts (1) — bodies are NOT included, read them yourself
-------------
    2500 B  sha256:6676042702213315  review.md
```

`artifact` is the directory Claude was allowed to write; the run directory also
holds a `manifest.json` recording the same facts. Open the files the list names,
read them, and copy the parts you approve into your project.

If the boundary blocked something Claude wanted to do, the run says so under
`denied by the permission boundary`; the answer may then be incomplete, so read that
list first. Keep answers short and structured — say how long they should be, because
very long replies get truncated.

## Command line (optional)

```sh
claude-mcp run -p "Review plan/foo.md and write review.md" -m sonnet
claude-mcp runs                                 # list past runs
claude-mcp prune --older-than-days 7 --keep 5   # clean up old run directories
claude-mcp env                                  # show how Claude Code will be launched
```

## Configuration (optional)

| Environment variable | Effect |
| --- | --- |
| `CLAUDE_MCP_ENTRY` | Full path to the `claude` program, when it cannot be found automatically. |
| `CLAUDE_MCP_TIMEOUT_MS` | Default per-run time limit. |
| `CLAUDE_MCP_STAGING_DIR` | Where run directories live. Default: `<your workspace>/.claude-staging`. |
| `CLAUDE_MCP_READ_DIRS` | Extra readable directories, separated by your platform's path separator. |
| `CLAUDE_MCP_ENV_PASSTHROUGH` | Comma-separated names to forward to Claude Code even though they look like credentials or steer model routing. |

## Safety

- Claude reads the directories you name and writes only in its own run directory.
  Both are enforced by Claude Code's permission rules, not by asking the model
  nicely; the session has no shell and no network tools at all, and your Claude
  Code login is used as-is. This tool never reads, stores, or forwards your
  credentials, and variables whose names look like credentials are not passed on.
- Nothing Claude produces enters your project by itself — you decide what to copy.
- Every run leaves a manifest, and `claude-mcp prune` is the only thing that
  deletes run directories.

## Development

```sh
node --test tests/*.test.mjs
```

The tests are fully offline: they use a fake `claude`, call no model and cost
nothing. The real thing lives in `scripts/live-review.mjs` (**that one costs money**).

## License

MIT.