简体中文

paddock — Local filesystem workbench (MCP stdio server)

paddock gives agents a complete, constrained set of local file operations: text read/write, directory management, filename search, content search, and metadata queries — all operations are confined to configurable "paddock" directories, and out-of-bounds access is always rejected.

• Zero runtime dependencies: pure Node.js standard library, no npm install needed

• MCP protocol: line-delimited JSON-RPC 2.0 over stdio, loadable by any MCP client

• dsh-ready: ships a Cordis bridge plugin, one-line bundle integration with the harness

• Read-only mode: --read-only blocks all write operations in one shot

• Large files & binaries: streaming head/tail, byte slicing, base64 reads, binary sniffing

• Search: a self-built glob engine (* ** ? {a,b} [abc]) plus regex/fixed-string content search

Quick start

# No dependency installation needed, run directly
node src/entry.js "C:/Users/me/projects"

Once started, the MCP session begins: JSON-RPC messages are read line by line from stdin, written line by line to stdout, and logs go only to stderr.

Connect from any MCP client (example with a standard MCP client config):

{
  "mcpServers": {
    "paddock": {
      "command": "node",
      "args": ["/path/to/fs-mcp/src/entry.js", "C:/Users/me/projects"]
    }
  }
}

You can also run a smoke session directly to verify:

# Write an initialize request to stdin and observe the response
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' | node src/entry.js "C:/Users/me/projects"

Related MCP server: MCP Local Filesystem Server

Installation

• As an MCP server: copy this directory, run node src/entry.js <paddock dirs…>, no build step.

• As a dsh plugin: see docs/INTEGRATION.md.

• Requirements: Node.js ≥ 18.17 (check with node --version).

Installing in DSH

dsh plugin --profile demo add github:JohnXu22786/fs-mcp

• demo is a dsh profile: it is created automatically on first use, and the package is added to dsh.profile.bundles;

• The cordis.patch.yml inside the package defines the paddock/bridge plugin, which starts this MCP server within the dsh process and registers all 16 tools into ctx.tools after the handshake — no manual configuration needed;

• Removal:

dsh plugin --profile demo remove paddock

Configuration

Configuration is merged as "defaults < config file < environment variables < command-line arguments"; paddock directories are unioned across all three sources.

Command line

node src/entry.js [options] [paddock dirs…]

  --config <path>   config file (defaults to paddock.config.json in the working directory, loaded only if present)
  --read-only       read-only mode: blocks all write operations
  --zones <path>    additional paddock directories (repeatable)
  --verbose         debug logging (stderr)
  --version / --help

Positional arguments are treated as paddock directories. At least one paddock is required, otherwise startup fails (exit code 2).

Config file (paddock.config.json)

{
  "zones": ["C:/Users/me/projects", "C:/Users/me/data"],
  "readOnly": false,
  "limits": {
    "peekBytes": 1048576,
    "readBytes": 16777216,
    "sliceBytes": 65536,
    "grepBytes": 262144,
    "grepHits": 200,
    "findHits": 1000,
    "treeDepth": 6
  },
  "behavior": {
    "includeHidden": false
  }
}

A full example is in examples/paddock.config.example.json.

Environment variables

limits semantics

Tool interface

16 tools; write operations carry a mutating marker (gated by read-only mode). All path arguments must be absolute paths inside a paddock; relative paths are resolved against the process working directory and validated the same way.

Read-only tools

Write tools

Error model

Tool-level failures do not produce protocol errors; they return structured isError: true results:

{
  "isError": true,
  "content": [{ "type": "text", "text": "[not-found] File does not exist: C:/…" }],
  "structuredContent": { "error": { "code": "not-found", "message": "File does not exist: C:/…" } }
}

Error codes: config readonly validation fence (out of bounds) not-found conflict limit binary wrong-kind io internal (fallback). network / timeout / jsonrpc appear only in the bridge client (the communication layer with the server subprocess). Error messages carry actionable follow-up suggestions (e.g. large files are pointed to pdk_slice).

Security model

• Paddock boundary: every path passes "paddock" validation before any IO (see docs/SECURITY.md).

• Symlinks: existing paths are realpath-resolved then validated; new paths validate by resolving the "nearest existing ancestor" and re-checking — links inside a paddock that point outside can never become a springboard.

• Component-level checks: string-prefix misjudgments such as zone vs zone_extra are impossible; win32 comparisons fold case.

• Windows hardening: rejects invalid path segments, trailing dots/spaces, and reserved device names (NUL/CON/COM1…).

• Read-only mode: with --read-only or config readOnly: true, all 6 write tools are gated.

• Delete protection: paddock root directories cannot be removed by pdk_remove.

• Large files/binaries: text-read limits, slice reads, base64, NUL-byte sniffing — the model is never slammed with gigantic or binary content.

dsh integration

Pick either of the two ways; details in docs/INTEGRATION.md:

1. Bundle bridge (recommended, zero dependencies): this package's dsh.bundle.patch points to cordis.patch.yml, and dsh merges the paddock/bridge plugin line into the config tree; the plugin starts the server subprocess inside the harness process and, after the handshake, registers all 16 tools into ctx.tools — model-side tool names look like mcp__paddock__pdk_peek.

2. Official MCP client: connect directly to node src/entry.js <paddock> with the @deepseek-ai/dsh-mcp-client config line.

Development

npm test        # node --test: 100+ cases (4 symlink cases skip on win32 as they need developer mode)
npm run smoke   # sequential end-to-end smoke test (real subprocess + stdio session, 16 checks)
node src/entry.js --help

Test coverage: paddock escapes/symlink escapes/ancestor-chain protection, read-write round-trips, large-file and binary policies, glob and content search, three-source config merging, protocol engine, end-to-end subprocess sessions.

License

MIT, see LICENSE.