@auggieteo/dsh-mcp-adapter 0.1.0

package/CONTEXT.md

@@ -0,0 +1,37 @@
+# DSH MCP Adapter
+
+A Deepseek Harness (DSH) plugin that connects the DSH agent to MCP servers, mirroring the major features of pi-mcp-adapter. Configuration lives in the DSH web UI under Settings > MCP.
+
+## Language
+
+**Adapter**:
+The DSH plugin this repo builds. It owns MCP client connections and exposes their tools to the DSH agent.
+_Avoid_: extension, bridge, wrapper
+
+**Server**:
+One configured MCP server entry, identified by its name. A server has one transport and produces zero or more tools.
+_Avoid_: endpoint, backend, service
+
+**Transport**:
+How the adapter talks to a server: stdio subprocess, or remote streamable HTTP with SSE fallback.
+_Avoid_: channel, protocol, connection type
+
+**Proxy Tool**:
+The single DSH tool named `mcp` that the model uses to search, describe, and call any server's tools. It is the token-efficient default surface, mirroring pi-mcp-adapter.
+_Avoid_: bridge tool, gateway tool, dispatcher
+
+**Promotion**:
+Turning one MCP tool into a native DSH tool registered in the DSH tool registry, with its own tool card and approval behavior. Controlled per tool in Settings > MCP. Mirrored from pi-mcp-adapter's `directTools`.
+_Avoid_: direct tool, native tool, registration
+
+**Auto-allow**:
+A per-server toggle that lets that server's tool calls run without asking the user. All other calls ask per call through the DSH approval system.
+_Avoid_: trust, bypass, whitelist
+
+**Config**:
+The standard `mcpServers`-shaped JSON stored in the adapter's DSH settings namespace, editable in Settings > MCP. Global: one list for every DSH session.
+_Avoid_: manifest, registry file
+
+**Lazy Lifecycle**:
+The connection policy: a server connects on first use and disconnects after an idle timeout. Opposite of eager connect at startup.
+_Avoid_: on-demand boot, cold start

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The dsh-mcp-adapter authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# dsh-mcp-adapter
+
+A [Deepseek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) plugin that connects the DSH agent to MCP servers. It mirrors the major features of [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter): one token-efficient `mcp` proxy tool over every configured server, optional per-tool promotion to native DSH tools, and lazy server lifecycles. Servers are added and configured in the DSH web UI under **Settings > MCP**; configuration persists in the DSH settings document (`$DSH_HOME/settings.yaml`, namespace `mcp`).
+
+Vocabulary lives in [CONTEXT.md](./CONTEXT.md). Design decisions live in [docs/adr/](./docs/adr/). Work is tracked as [GitHub issues](https://github.com/auggie246/dsh-mcp-adapter/issues).
+
+## Status
+
+The v1 implementation is complete through issues #1–#7. See the [v1 end-to-end verification](./docs/verification/v1-e2e.md). Issues #8–#14 track deferred follow-ups.
+
+## Config
+
+The Host registers one live DSH settings namespace, `mcp`. Its user layer lives under `mcp:` in `$DSH_HOME/settings.yaml`; the Settings > MCP page owns normal edits.
+
+```yaml
+mcp:
+  mcpServers:
+    filesystem:
+      command: npx
+      args: [-y, "@modelcontextprotocol/server-filesystem", /workspace]
+      autoAllow: false
+    hosted:
+      url: https://mcp.example.com/api
+      headers:
+        Authorization: Bearer example-token
+```
+
+Each Server configures exactly one Transport: `command` for stdio, or `url` for streamable HTTP with SSE fallback. Adapter extension fields are `disabled`, `autoAllow`, `lifecycle` (`lazy` only in v1), `idleTimeoutMinutes` (default `10`), and `promotedTools`.
+
+The schema rejects unknown fields and invalid transport combinations before they reach `$DSH_HOME/settings.yaml`. Each `env` and `headers` value has the DSH `secret` schema role. Wire views retain each key and redact its value.
+
+## Settings page
+
+Open **Settings > MCP** to add, import, edit, reconnect, disable, or delete a Server. The Server list shows live connection state and cached tool counts. The detail panel manages Transport fields, secret values, Auto-allow, the idle timeout, and Promotions.
+
+JSON import accepts the standard `{ "mcpServers": { ... } }` shape. Import replaces matching Server entries and preserves Servers absent from the import.
+
+Every page write carries the latest namespace revision. Field edits use path mutations. Existing secret values remain saved when their value inputs stay blank.
+
+## Server lifecycle
+
+The Host creates no unpromoted Server connection at startup. The first tool-list or tool-call request connects the Server and fills an in-memory metadata cache. A persisted Promotion can connect once to rebuild its native input schema. MCP `tools/list_changed` notifications refresh the cache. The default idle timeout closes the connection after 10 minutes without a request; the next request reconnects it.
+
+Changing, disabling, or removing a Server closes its connection and clears its cache. Re-enabling a Server restores the lazy behavior. A Connection RPC channel, `/mcp-adapter`, exposes detached `status`, `catalog`, and combined `overview` snapshots. Its `reconnect` endpoint restarts one named Server. These endpoints never expose Config secrets or SDK objects.
+
+## Proxy Tool
+
+The Host registers one global `mcp` tool with three actions:
+
+```text
+mcp({ action: "search", query: "screenshot" })
+mcp({ action: "describe", server: "browser", tool: "take_screenshot" })
+mcp({ action: "call", server: "browser", tool: "take_screenshot", args: {} })
+```
+
+Search results use `<server>__<tool>` names to avoid collisions. The first search fills empty metadata caches; later search and describe operations use the cache. Call requests ask for DSH approval unless that Server has `autoAllow: true`.
+
+Call, search, and describe output is limited to 50 KiB and 2,000 lines. Larger text uses `spillStore` for a full-result reference. Raw structured details larger than 16 KiB become a compact summary with their own spill reference.
+
+## Promotion
+
+Add a raw MCP tool name to a Server's `promotedTools` list to register `<server>__<tool>` as a native DSH tool. The native tool uses the MCP input schema and the same approval, call, and output-guard path as `mcp({ action: "call" })`.
+
+Promotion changes apply through `settings/updated`. They do not restart a connected Server. Removing a Promotion unregisters its native tool. Non-promoted tools remain available only through the `mcp` Proxy Tool.
+
+DSH native tool names must match `[A-Za-z0-9_-]` and contain at most 64 characters. The Adapter logs a warning and skips an invalid or colliding Promotion name.
+
+## Install
+
+Requires the `dsh` CLI and a web profile (the browser GUI you run DSH with).
+
+```sh
+dsh plugin --profile web add @auggieteo/dsh-mcp-adapter
+```
+
+Then restart DSH. The Settings panel (`⌘,` / sidebar foot) gains an **MCP** section.
+
+### Local development
+
+```sh
+pnpm install
+pnpm build          # produces lib/client.js (required before install)
+dsh plugin --profile web add /absolute/path/to/dsh-mcp-adapter
+```
+
+During client development, run `pnpm dev` alongside DSH. `dsh-client-hmr` reloads each rebuilt client bundle without a manual refresh.
+
+Host changes need a DSH restart. The web profile disables host HMR for plugin rows.
+
+## Uninstall
+
+```sh
+dsh plugin --profile web remove @auggieteo/dsh-mcp-adapter
+```
+
+## Release
+
+The package uses Semantic Versioning. Update `package.json` before each release.
+
+```sh
+pnpm version patch --no-git-tag-version  # or minor, major, or an explicit version
+pnpm test
+```
+
+Merge the version change. Then publish a GitHub Release whose tag is exactly `v<package version>`.
+
+The `Publish to npm` workflow rejects any different tag. It tests and builds the package before publishing with npm provenance.
+
+A prerelease GitHub Release publishes with the npm `next` tag. A regular GitHub Release publishes with the npm `latest` tag.
+
+The first publish creates the npm package. Add a short-lived granular npm token as the GitHub `NPM_TOKEN` secret for this publish.
+
+Then configure npm trusted publishing for `auggie246/dsh-mcp-adapter` and `publish.yml`. Allow `npm publish`, then delete `NPM_TOKEN`.
+
+Later releases use GitHub OIDC and need no long-lived npm token. npm requires the package to exist before trusted publishing configuration.
+
+## Layout
+
+```
+cordis.patch.yml   bundle patch: inserts the host composition row on install
+src/host/          host half: plain ESM, no build step
+src/client/        client half: JSX, bundled to lib/client.js
+build.mjs          esbuild wrapper producing the loader-compatible bundle
+lib/client.js      build artifact (gitignored), required at runtime
+docs/adr/          architecture decisions
+CONTEXT.md         project vocabulary
+```

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# Bundle patch for dsh-mcp-adapter: inserts the Adapter's host row into the
+# profile tree. `dsh plugin --profile web add <this repo>` appends this bundle
+# to dsh.profile.bundles automatically. The client roster entry is discovered
+# from package.json's dsh.client block by the clientModules scan — no row here.
+
+- insert:
+    - id: mcp-adapter
+      name: "@auggieteo/dsh-mcp-adapter"

package/docs/adr/0001-proxy-first-tool-surface.md

@@ -0,0 +1,7 @@
+# Proxy-first tool surface
+
+The Adapter exposes every Server's tools to the DSH agent through one Proxy Tool named `mcp` (search / describe / call) instead of registering every MCP tool natively, mirroring pi-mcp-adapter's headline design. The reason is token economy: registering every MCP tool natively would put hundreds of tool schemas into every model step of every session, whether or not they are used. Native registration stays available through Promotion, a per-tool toggle in Settings > MCP, for tools whose DSH-native card and approval UX justify the context cost.
+
+Considered options: native registration for every server (best per-tool UX, unbounded context cost, rejected); proxy only (strictest pi mirror, no native path at all, rejected to keep the Promotion escape hatch).
+
+Consequences: approval gating for proxy calls must live inside the Proxy Tool's `execute` (DSH does not gate new tools by default), keyed on the server name inside the call arguments, with the per-server Auto-allow toggle consulted there. Promoted tools rely on DSH's native surface instead.

package/docs/adr/0002-config-in-dsh-settings-namespace.md

@@ -0,0 +1,7 @@
+# Config in the DSH settings namespace, not .mcp.json files
+
+Server Config is stored in the Adapter's `mcp` namespace of the DSH settings service (persisted to `$DSH_HOME/settings.yaml`, hot-reloaded, revision-fenced), not in pi-mcp-adapter's layered `.mcp.json` files. We still adopt the standard `mcpServers`-shaped JSON as the Config schema, so users can paste configs from pi, Claude Desktop, Cursor, or VS Code.
+
+Considered options: pi's multi-file merge chain (`~/.config/mcp/mcp.json` → agent dirs → workspace `.mcp.json`, plus cross-tool `imports`) was rejected because DSH users interact through the web UI, not dotfiles; a single global namespace with a Settings > MCP form matches how every other DSH settings surface works, and gives us validation, conflict detection, and live update events for free.
+
+Consequences: per-workspace servers and config-file imports become a later feature layered on top of the namespace (a workspace source merged at resolve time), not a change to where the global Config lives. The settings page needs an explicit JSON import action, since there is no file to copy-paste into.

package/docs/verification/v1-e2e.md

@@ -0,0 +1,45 @@
+# v1 end-to-end verification
+
+Date: 2026-08-30
+
+## Environment
+
+- Package commit: `69f6b16` plus this verification record.
+- Install: `link:/Users/augustine/projects/dsh-mcp-adapter` in the `web` profile.
+- DSH profile: `/Users/augustine/.dsh/profiles/web`.
+- Managed verification server: a fresh `dsh web --no-open --port 0` process.
+- Browser: headless Google Chrome through the Chrome DevTools Protocol.
+- Fixture: `test/fixtures/mcp-stdio-server.mjs`.
+
+This run did not use a clean `$DSH_HOME`. The profile already contained unrelated model and UI settings. The `mcp` namespace was absent before the test. A separate managed web process loaded the current Host code without interrupting the active development session.
+
+## Build checks
+
+- `pnpm install --frozen-lockfile`: passed.
+- `pnpm build`: passed.
+- `pnpm test`: 28 of 28 tests passed.
+- `git diff --check`: passed.
+- `npm pack --dry-run`: passed with a temporary npm cache. The user cache contains unrelated root-owned files.
+
+## Browser checks
+
+1. Opened **Settings > MCP** and confirmed the empty state.
+2. Added `e2e-fixture` as a stdio Server through the form.
+3. Confirmed `$DSH_HOME/settings.yaml` contained the command, args, defaults, and empty Promotion list.
+4. Confirmed the initial Server state was `disconnected` with zero cached tools.
+5. Used **Reconnect** and confirmed `connected`, `stdio`, and one cached `ping` tool.
+6. Promoted `ping` and confirmed `promotedTools: [ping]` in `settings.yaml`.
+7. Started an Agent session and used the Proxy Tool to search, describe, and call `e2e-fixture__ping`.
+8. Confirmed the call showed an approval request with the redacted argument preview.
+9. Selected **Allow once** and received the exact result `pong`.
+10. Enabled Auto-allow through Settings and confirmed `autoAllow: true` in `settings.yaml`.
+11. Called the Proxy Tool again and received `pong` without an approval request.
+12. Called the promoted native `e2e-fixture__ping` tool and received `pong`.
+13. Set `idleTimeoutMinutes` to `0.1` and confirmed an idle disconnect with the tool cache retained.
+14. Disabled the Server and confirmed state `disabled` with its cache cleared.
+15. Re-enabled the Server and confirmed it became available again.
+16. Deleted the Server and confirmed the empty state and `mcpServers: {}` in `settings.yaml`.
+
+## Rough edge
+
+A persisted Promotion needs its MCP input schema after Host startup or Server re-enable. The Promotion registry currently connects that Server to rebuild metadata, then the normal idle timeout closes it. GitHub issue #14 tracks the lifecycle decision and documentation correction.