dsh-mcp-proxy

Readme

# dsh-mcp-proxy

Context-cheap MCP access for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

The shipped `dsh-mcp-client` registers **every** tool of **every** configured server on `ctx.tools`, so a handful of MCP servers puts hundreds of JSON schemas into the system prompt of every request — whether or not the model ever calls one.

This plugin registers exactly **two** tools regardless of how many servers you configure, and reaches those servers lazily. The standing prompt cost is constant in the number of MCP tools available.

## Install

```bash
dsh plugin --profile web add dsh-mcp-proxy
```

Then declare your servers by overriding the row (the shipped row has none — see [Trust](#trust)).

## What the model sees

| Tool | Purpose |
|---|---|
| `mcp_discover` | Search the tool catalog by keyword; returns each hit's server, name, description, and argument names |
| `mcp_call` | Invoke one tool by server and name, passing arguments through unchanged |

The catalog is cached on disk, so `mcp_discover` answers from a **cold start without connecting to anything**, and keeps answering when a server is temporarily down.

## How it behaves

- **Nothing connects at boot.** A server is contacted on first discovery or first call.
- **A warm connection is reused** across calls and closed after `idleDisconnectMs` of silence. Concurrent calls share one handshake.
- **One unreachable server degrades discovery instead of failing it**: the model gets the servers that answered, plus a named reason for each that did not.
- **A tool-reported failure is a successful result** carrying `isError: true`, so a Code Mode caller branches on the flag rather than parsing prose. Only transport and protocol failures are tool errors.
- **Catalog entries for servers you removed are pruned** at load, so a renamed server stops advertising tools nothing can call.
- **A corrupt cache file starts empty** rather than stopping the harness from booting — it is a derived cache, not a source of truth.
- Disposal closes every connection and clears every timer.

## Configuration

```yaml
- id: mcp-proxy
  name: dsh-mcp-proxy
  config:
    cachePath: !!js dshHomePath('mcp-proxy/catalog.json')
    catalogTtlMs: 86400000
    idleDisconnectMs: 300000
    connectTimeoutMs: 30000
    callTimeoutMs: 60000
    discoverLimitDefault: 15
    discoverLimitMax: 50
    servers:
      - name: github
        transport: stdio
        command: npx
        args: ['-y', '@modelcontextprotocol/server-github']
        env:
          GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN

      - name: internal
        transport: streamable-http
        url: http://localhost:3000/mcp
        headers:
          Authorization: !!js `Bearer ${process.env.MCP_TOKEN}`
```

| Field | Default | Meaning |
|---|---|---|
| `servers` | `[]` | The servers this deployment can reach. Names are `[A-Za-z0-9_-]{1,32}` and must be unique |
| `cachePath` | — (required) | JSON file caching each server's tool list |
| `catalogTtlMs` | `86400000` (1 day) | Age at which a cached catalog is refetched on the next discovery |
| `idleDisconnectMs` | `300000` (5 min) | Idle period after which a warm connection closes |
| `connectTimeoutMs` | `30000` | Bound on one MCP handshake |
| `callTimeoutMs` | `60000` | Bound on one `callTool` request |
| `discoverLimitDefault` | `15` | Hits returned when the model omits `limit` |
| `discoverLimitMax` | `50` | Hard cap, whatever the model asks for |

## Trust

`servers` ships **empty on purpose**. Every MCP server command is trusted executable code running **outside the agent sandbox**, so no package may enable one on a user's behalf. The shipped harness makes the same choice for `dsh-mcp-client`.

This plugin adds no approval gate of its own. Gate `mcp_call` the way you gate any other tool — a `tools/pre-execute` listener, `ctx.tools.guard()`, or the permission presets — so the policy stays in one place instead of forking per transport.

## Running alongside dsh-mcp-client

Supported, and often the right setup: promote the two or three servers whose tools you want **natively visible** (so the model calls them without a discovery round trip) to `dsh-mcp-client` rows, and leave the long tail behind this proxy. Tool names do not collide — `dsh-mcp-client` registers `mcp__<server>__<tool>`, this plugin registers only `mcp_discover` and `mcp_call`.

## Trade-off

A proxy costs the model one extra round trip when it does not already know the tool name, and hides the tool's full JSON schema behind argument names. That is the deliberate exchange: constant prompt cost, at the price of discovery latency on first use. If you have one MCP server with four tools, `dsh-mcp-client` is the better fit.

## Alternative worth knowing

The harness's own idiom for progressive disclosure is `ctx.tools.restrict()`, which masks a registered tool set per agent. That path keeps full schemas for the visible subset but still requires connecting at boot to enumerate. This plugin chooses the proxy shape instead so that **nothing connects until the model asks** — the property that matters when a deployment configures a dozen servers it rarely uses.

## Development

```bash
pnpm install --ignore-workspace
pnpm run typecheck
pnpm test
pnpm run build
```

The suite runs against a real MCP stdio server (`tests/fixture-server.mjs`) over the real SDK transport, so it covers handshakes, listing, calling, tool-level failures, unreachable servers, and catalog persistence without depending on any third-party server.

## License

MIT

## Prior art

The context-saving proxy idea comes from [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) (MIT) in the Pi ecosystem. This is an independent implementation against Harness extension points and shares no code with it; it covers the lazy-connection and proxy-tool core, not pi-mcp-adapter's OAuth flows, tool promotion, or `/mcp` configuration panel.