# duckcoop

MCP server that lets an LLM client run sandboxed, read-only SQL (via DuckDB) against CSV/Parquet/JSON files under a directory you choose. Like a duck, it only gets to paddle around the pen you build for it.

## Usage

```bash
npm run build
node dist/cli.js /path/to/sandbox-root
```

Optional flags: `--scratch-dir <path>` (defaults to a temp directory), `--max-temp-size <size>` (defaults to `4GB`).

Exposes two tools: `query` (SELECT / CREATE TEMP VIEW / CREATE TEMP TABLE only) and `list_files` (data files under the sandbox root). See `docs/adr/` for the security model.

## Registering with an MCP client

### Claude Code

```bash
claude mcp add duckcoop node /absolute/path/to/duckcoop/dist/cli.js /absolute/path/to/sandbox-root
```

### Claude Desktop

Add an entry to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "duckcoop": {
      "command": "node",
      "args": [
        "/absolute/path/to/duckcoop/dist/cli.js",
        "/absolute/path/to/sandbox-root"
      ]
    }
  }
}
```

Restart Claude Desktop for the change to take effect.

**Querying files you drag-and-drop into a chat:** Claude Desktop doesn't save chat attachments to a path duckcoop can see. Files dropped in a Local Agent Mode session instead land under `~/Library/Application Support/Claude/local-agent-mode-sessions/<account-id>/<session-id>/local_<id>/outputs/`. Point the sandbox root at the stable parent directory, `~/Library/Application Support/Claude/local-agent-mode-sessions`, so newly created session folders are covered without editing the config again:

```json
{
  "mcpServers": {
    "duckcoop": {
      "command": "node",
      "args": [
        "/absolute/path/to/duckcoop/dist/cli.js",
        "/Users/<you>/Library/Application Support/Claude/local-agent-mode-sessions"
      ]
    }
  }
}
```