dsh-mcp-skill-manager

Readme

# dsh-mcp-skill-manager

A Settings-page panel for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) that manages **MCP servers** and the **skill library** in one place.

Every server card shows its transport (**stdio** / streamable-http), a live reachability badge, a **tool count + token estimate**, and per-server **Test / Edit / Delete** actions. The skill library groups 130+ skills by **collection** (e.g. `hack-skills`, `superpowers-zh`, `ui-ux-pro-max`) with batch enable/disable; the **grouping rules** panel lists the built-in default matchers plus your own rules.

## Design philosophy

Most skill managers list skills flat and rely on search/tags. This panel takes a different angle: DSH users often install whole skill **packs** (superpowers, hack-skills, ui-ux-pro-max, …) that each ship a set of skills. So the panel groups skills by **collection** — auto-detected from frontmatter shape and user rules — so you can see *where each skill came from* at a glance, act on a whole pack at once, and scale to a hundred skills.

Key principles:
- **Provenance first**: every skill shows *why* it is in a group (frontmatter field / manual assignment / a rule), and the grouping panel lets you **test** what a rule matches before applying it.
- **Heuristics are suggestions, not decisions**: built-in shape detection and signature clustering only propose groups; you **confirm** before anything is written. A skill is never silently re-grouped.
- **Batteries for the everyday, levers for the power user**: the default view is grouped, and one-click suggestions cover the common case; the rule editor (10 matcher types, suggest/auto toggle, live match test) is there if you want finer control.

## Features

### 1. MCP servers (Settings → MCP & Skills → MCP Servers)

| MCP management panel | Add MCP server panel |
| :-: | :-: |
| <img src="img_en/mcp.png" alt="MCP management panel" width="300" /> | <img src="img_en/add_mcp_server.png" alt="Add MCP server panel" width="300" /> |

- List every `mcp-*` server from your profile patch (`cordis.patch.yml`) with live status (active / failed / loading).
- Add, edit, delete and enable/disable servers; changes are written to the user patch layer with an automatic backup, and DSH hot-reloads them (no restart needed for config edits). New servers get an auto-derived id (`mcp-<slug>`).
- Test connections with a real handshake (`initialize` + `tools/list`) for both stdio and streamable-http transports.
- **Service status badge**: HTTP servers are auto-probed when the panel loads (reachable / not running), so "plugin active" is clearly separated from "server actually up".
- **Tool count & token estimate**: click *Collect* (or Test) to snapshot each server's `tools/list`; cards show `tools: N · ~X tokens`, and disabled servers still display the last-good snapshot to help you decide whether to enable them.
- **Optional auth headers** (streamable-http): enter one `Key: Value` per line (e.g. `Authorization: Bearer xxx`). Headers are used by real connections (official mcp-client) and by the test probe.
- **"Disable all MCP at startup" toggle**: when on, every boot starts with all MCP servers off — enable what you need per session (applies on next restart). Stored in `~/.dsh/dsh-mcp-skill-manager/settings.json`.
- **Summary bar**: total / enabled / disabled / reachable servers plus the estimated token footprint of enabled servers.
- **Expandable tool list**: collect once, then expand a card to see its tool names.
- **Optional env vars**: `Key=Value` lines per server (stdio and http), passed to real connections and the test probe.

<details>
  <summary>How Collect estimates tool count & token usage</summary>
Clicking **Collect** runs a real MCP handshake for every configured server (stdio via `spawn`, streamable-http via HTTP POST): `initialize` → `notifications/initialized` → `tools/list`. Then: **tool count N** is the number of tools returned by `tools/list`; **schema bytes** is `JSON.stringify(tool.inputSchema ?? tool.parameters).length` summed across all tools; **per-server tokens** is `max(1, ceil(schemaBytes / 4))`, the community rule of thumb "≈4 bytes per token". Each server's "tool count, tool names, schemaBytes, estimatedTokens, serverName, transport, fetchedAt" is stored as a last-good snapshot in `~/.dsh/dsh-mcp-skill-manager/catalog.json`; the card's `tools: N · ~X tokens` reads that snapshot, and the top summary's `~X tokens` is the sum of `estimatedTokens` over **enabled** servers only — disabled servers keep their last snapshot but are excluded from the total.
</details>

### 2. Skill library (Settings → MCP & Skills → Skills)

<table>
  <tr>
    <td align="center"><b>By collection</b><br><img src="img_en/skill-1.png" alt="By collection" width="280" /></td>
    <td align="center"><b>By root</b><br><img src="img_en/skill-2.png" alt="By root" width="280" /></td>
  </tr>
  <tr>
    <td align="center"><b>Custom grouping rules</b><br><img src="img_en/skill-3.png" alt="Custom grouping rules" width="280" /></td>
    <td align="center"><b>View grouping rules</b><br><img src="img_en/skill-4.png" alt="View grouping rules" width="280" /></td>
  </tr>
</table>

- Browse skills from all standard roots (project `.dsh/skills`, `.agents/skills`, `~/.dsh/skills`, `~/.agents/skills`).
- Create skills from a template (kebab-case name, description, optional `whenToUse`), toggle model invocation, edit the description, and delete (moved to `.trash-dsh-mcp-skill-panel/`).
- **View any skill** in a modal (full SKILL.md, read-only) and edit its description inline.
- **Search** skills by name/description. Deleting a skill moves it to `.trash-dsh-mcp-skill-panel/`; once the trash is non-empty, a **Trash** section appears at the bottom of the Skills tab with a **Restore** button.
- **Skill collections**: group skills by collection — `collection:` frontmatter field first, then manual assignment, then user rules — with three views (by collection (default) / by root / flat). Per-card quick-assign dropdown, multi-select assign/unassign, and batch enable/disable model or delete a whole collection.
- **Feature suggestions**: built-in rules (superpowers-zh via `metadata.hermes` metadata; hack-skills via minimal frontmatter + `>- ` folded description; ui-ux-pro-max via `argument-hint` or known design names) plus **signature auto-clustering** (groups skills sharing a distinctive frontmatter shape, ≥2 members, renamable). Suggestions only cover not-yet-grouped skills; review before applying.
- **Custom rules & grouping panel**: 10 matcher types (name regex, path substring, frontmatter key=value, hasKey, missingKey, keysSubset, descFolded, meta deep path, anyOf, json) with a **Suggest / Auto** toggle (Suggest = listed in feature suggestions, groups after apply; Auto = groups immediately). The **Grouping rules panel** shows a rule's matched skills, edit + test + delete rules; built-in default rules are editable and flagged 默认 (confirm before editing). Grouping state lives in `~/.dsh/dsh-mcp-skill-manager/collections.json`.

### 3. Skill custom grouping walkthrough

The following uses the `browser-skill` skill as an example to show the grouping flow.

**1. View the skill content**

Click **View** on `browser-skill` to open its content — the frontmatter has `name: browser-skill`.

<img src="img_en/skill-8.png" alt="View skill content" width="420" />

**2. Add a custom rule**

Fill in the rule as shown below (this example uses **Suggest**; if you choose **Auto**, step 3 is unnecessary — the skill is grouped immediately).

<img src="img_en/skill-5.png" alt="Add custom rule" width="420" />

**3. Open Feature suggestions**

Click **Feature suggestions** — the custom rule you just added now takes effect.

<img src="img_en/skill-6.png" alt="Feature suggestions" width="420" />

**4. Apply the selection**

Click **Apply selected** — `browser-skill` is now automatically added to the `tencent` collection.

<img src="img_en/skill-7.png" alt="Grouped successfully" width="420" />

## Install

Requires Node >= 20 and pnpm, and a DSH `web` profile (default).

### Option A — official CLI (recommended)

The package ships a `dsh.bundle.patch` (`cordis.patch.yml`), so the official DSH plugin CLI installs **and** mounts it in one command — no manual `cordis.patch.yml` edits.

```bash
# published on npm
dsh plugin --profile web add dsh-mcp-skill-manager

# straight from a GitHub repo (builds the client bundle on install)
dsh plugin --profile web add github:<user>/dsh-mcp-skill-manager

# from a local checkout (self-link, for development)
dsh plugin --profile web add .
```

Then restart DSH web and open **Settings → MCP & Skills**.

> [!IMPORTANT]
> - **npm installs** install the published package (`dsh-mcp-skill-manager`); the `files` include `cordis.patch.yml` and the built `client/client.js`.
> - **GitHub installs** build the client bundle on install via the package's `prepare` script (`node client/build.mjs`), which needs `esbuild` (a devDependency). If pnpm blocks the build, allow it in the profile's `pnpm-workspace.yaml` under `allowBuilds` — the DSH CLI prints the exact key to add when it blocks a git-hosted build.
> - **Do not mix the two channels in one profile.** If the plugin is already active through the bundle channel (`dsh.profile.bundles`), do **not** also run `node install.mjs` or keep a manual `- insert:` row in `cordis.patch.yml` — that double-mounts the plugin (two host halves, two client bundles). `install.mjs` detects the bundle channel and skips its manual insert automatically.

### Option B — `node install.mjs` (local / non-CLI)

```bash
node install.mjs
# or with a custom profile:
node install.mjs --profile web
```

The script backs up `cordis.patch.yml`, installs the package into the profile (`pnpm add file:...`), and appends the plugin row. **Restart DSH web once** so the new plugin enters the boot composition (client bundles are assembled at startup):

```bash
cd <your-dsh-install-dir>   # e.g. D:/deepseek-harness
pnpm exec dsh web
```

Then open Settings → **MCP & Skills**. To verify headlessly after the restart: `node scripts/smoke.mjs` (checks the loader entry, the client bundle, and the MCP/Skills RPC endpoints end-to-end).

Manual install (equivalent):
```bash
cd ~/.dsh/profiles/web
pnpm add file:<path-to-this-package> --config.auto-install-peers=false
cat >> cordis.patch.yml <<'EOF'

- insert:
    - id: dsh-mcp-skill-manager
      name: 'dsh-mcp-skill-manager'
EOF
# restart DSH web
```

## Uninstall

```bash
cd ~/.dsh/profiles/web
pnpm remove dsh-mcp-skill-manager
# remove the "- id: dsh-mcp-skill-manager" row from cordis.patch.yml
# restore the backup created by install.mjs if desired
```

## Compatibility

- Tested against DeepSeek Harness **0.1.1-rc.2** (`web` profile on Windows).
- Runtime peer dependency: `@deepseek-ai/cordis` only (provided by the host). Regular dependency: `js-yaml` (frontmatter).
- Feature detection: if the `connection.rpc` service is unavailable (old/headless hosts), the panel degrades to an unavailable message and never blocks startup.
- Only stable contracts are used: `connection.rpc`, `settings.section` slots, `locale`, plus the official file formats (`cordis.patch.yml`, `SKILL.md` frontmatter). The patch file is edited line-wise so your comments and hand-written entries are preserved.
- After upgrading DSH, run `node --test` in this package and re-run `node scripts/smoke.mjs` (end-to-end loader/bundle/RPC check).

## Security

- All mutating RPC endpoints are loopback-only (`authority: "loopback"`).
- Writes are atomic (temp file + rename) with backups: `cordis.patch.yml.bak-mcp-skill-panel`, skill deletes go to `.trash-dsh-mcp-skill-panel/`.
- Plugin state lives in `~/.dsh/dsh-mcp-skill-manager/` (`catalog.json` last-good tool snapshots, `settings.json` preferences, `collections.json` grouping rules/assignments/excluded). HTTP auth headers are stored in your profile patch — visible only to the loopback panel.
- stdio probes spawn with `shell: false`; ids/serverNames are validated against strict patterns; skill paths are confined to the discovered roots.

## Development

```bash
npm install
npm run build   # bundle client/index.jsx -> client/client.js
npm test        # node --test
```

## License

MIT