dsh-codebase-memory-mcp

Readme

# dsh-codebase-memory-mcp

A [DeepSeek Harness](https://github.com/deepseek-ai/dsh) plugin that bridges the
local **codebase-memory-mcp** knowledge-graph MCP server into DSH — reusing the
built-in `@deepseek-ai/dsh-mcp-client` bridge, so you don't implement any MCP
transport yourself.

The model sees tools named `mcp__codebase-memory__*` (`index_repository`,
`search_graph`, `trace_path`, `query_graph`, `detect_changes`, … — 14 tools in
total).

## Install (from the marketplace / npm)

```sh
dsh plugin --profile web add dsh-codebase-memory-mcp
```

Then reload the DSH web host (restart the app, or use the in-app reload).

## Install (local development)

```powershell
dsh plugin --profile web add link:D:\path\to\dsh-codebase-memory-mcp
```

## Configure the server binary

The plugin reads its configuration from the `codebase-memory-mcp` settings
namespace. The **default rule is unchanged**: `exePath` defaults to
`codebase-memory-mcp`, i.e. it auto-looks-up the server binary on your `PATH`.
You only configure anything when your binary is NOT on `PATH`.

If your binary lives elsewhere (e.g. a downloaded `codebase-memory-mcp.exe`),
set the **absolute path** in the `codebase-memory-mcp` settings namespace. In
this DSH build, external profile plugins do not get a tailored card in
**Settings → Plugins → Plugin configuration**, so edit the namespace either
through the settings document editor, or by writing it into your profile's
settings document under `codebase-memory-mcp:`. Saving hot-reloads the bridge —
no restart needed.

| Setting     | Default             | Meaning                                                      |
|-------------|---------------------|--------------------------------------------------------------|
| `exePath`   | `codebase-memory-mcp` | Command/executable for the MCP server. **Default = auto-lookup on PATH (unchanged).** |
| `cwd`       | (exe's directory)   | Working directory for the spawned server.                    |
| `extraArgs` | (empty)             | Extra CLI args, space-separated, appended to the command.    |
| `env`       | `{}`                | Extra environment passed to the spawned server (merged over the scrubbed parent env). |
| `enabled`   | `true`              | Master switch. Set `false` to keep the namespace but not spawn the server. |

## Status — is the bridge actually bound to DSH?

After install, if you don't see the `mcp__codebase-memory__*` tools, the bridge
likely failed to start (most often: the binary is not resolvable). The plugin no
longer crashes on a bad binary — instead it tracks startup status and exposes
two host tools you (or the model) can call even when MCP itself is down:

- **`codebase_memory_status`** — reports `state` (`idle` / `connecting` /
  `ready` / `error` / `disabled`), how many `mcp__codebase-memory__*` tools are
  live, the last error (if any), and the resolved config. Use this to confirm
  the bridge is bound and to see *why* it isn't.
- **`codebase_memory_restart`** — disposes and re-launches the bridge from the
  current settings (handy after you fix `exePath` / `cwd` / `env`).

Startup transitions are also logged to the console (visible in the host's
plugin load report), e.g. `[codebase-memory-mcp] status: ready — 14 tool(s)`
or `[codebase-memory-mcp] status: error — …`.

If your DSH build loads external plugins' **browser halves**, a tailored card
also appears under **Settings → Plugins → Plugin configuration →
codebase-memory-mcp**. The card shows a live status badge (READY / ERROR /
CONNECTING / DISABLED) with the tool count and last error, plus a config form
(`exePath` / `cwd` / `extraArgs` / `env` / `enabled`) with **Save**, **Reset to
defaults**, and **Restart bridge**. The card talks to the host half through the
`harness.handle` / `host.call` pairing (status + restart). See the Known
limitations note for when this card may not appear.

## Verify

1. Ask the model: "Run `codebase_memory_status` and tell me the state."
2. `state: "ready"` with `toolCount > 0` means the bridge is bound and the
   `mcp__codebase-memory__*` tools (e.g. `index_repository`, `search_graph`,
   `trace_path`, `query_graph`, `detect_changes`, …) are available.
3. `state: "error"` means startup failed — read `error`, fix `exePath`/`cwd`/`env`
   in the `codebase-memory-mcp` settings namespace, then call
   `codebase_memory_restart`.

## How it works

```
DSH host
 └─ composition loads this plugin (cordis.patch.yml insert)
     └─ wrapper plugin apply(ctx):
         1) ctx.settings.register('codebase-memory-mcp', schema)
         2) read scope.get() → build mcp config → ctx.plugin(mcpApply, cfg)  (dynamic)
            - failOnStartupError: false  ← a bad binary only logs, it never crashes the plugin
         3) scope.watch(() => { handle.dispose(); re-launch })   ← settings change = hot reload
         4) spies on ctx.tools.register + ctx.logger.error → live `status`
         5) registers host tools codebase_memory_status / codebase_memory_restart
            (usable even when the MCP bridge is down)
```

The bridge itself is the built-in `@deepseek-ai/dsh-mcp-client`; this package
only contributes the composition entry, a runtime-configurable settings
namespace, startup-status tracking, and two host-facing tools.

## Publish

1. `npm publish` (registry verifies `repository` maps back to the same repo, preventing name squatting).
2. Open a PR adding one entry to [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) — the market picks it up automatically, usually within a day.

## Known limitations

- **The tailored GUI card is best-effort and may not appear in every DSH build.**
  This package now ships a browser half (`lib/client.js`, declared via the
  `dsh.client` field and `exports["./client"]`) that registers a card in
  **Settings → Plugins → Plugin configuration → codebase-memory-mcp**. For that
  card to render, the host must (a) load external profile plugins' browser
  halves and (b) wire the `harness.handle` / `host.call` pairing for live
  status. In the DSH build inspected while writing this, the host composer only
  loaded external plugins' host half (`cordis.patch.yml`) and did not appear to
  read an external `dsh.client` half, so the card may not show. When it does
  not, the `codebase-memory-mcp` namespace is still fully editable via the
  settings document / generic editor, and startup status is always observable
  through the `codebase_memory_status` tool and the console. (The card degrades
  gracefully: if `host.call` is unavailable it shows "status unavailable" but
  config editing still works.)
- If the host cannot resolve `@deepseek-ai/dsh-mcp-client` etc. from this
  package, add those packages as dependencies or symlink them into the profile.

## License

MIT