dsh-zai-mcp
A DeepSeek Harness user skill for connecting the Z.AI hosted MCP servers (ZRead, Vision, Web Reader) to a DSH profile — and, more generally, for adding, porting and debugging any MCP server:
- one
insertrow with@deepseek-ai/dsh-mcp-clientin the profile'scordis.patch.yml, forstdio,streamable-httpandssetransports; - mapping from other clients (Claude Desktop, Codex, Cursor/VS Code, local Go/Python MCP servers, hosted vendors);
- the only correct secret seam:
!!jsenvironment expressions plus$DSH_HOME/.env(mode 600) — never a literal token in the config; - verification (
--dump-config, an MCPinitializeprobe, restart) and the pitfalls seen in practice.
The worked Z.AI example (ZRead, Vision, Web Reader) is in
references/zai-mcp.md.
Repository layout
| Path | What it is |
|---|---|
SKILL.md |
the skill itself (frontmatter + procedure), symlinked into ~/.dsh/skills/ |
references/zai-mcp.md |
the worked configuration: key source, all four servers, the agent-preset gate, verification, troubleshooting |
templates/standard-0.2.1-rc.2.plugins.yml |
the standard agent preset's plugin list, copied verbatim from DSH 0.2.1-rc.2 |
templates/zai-mcp-rows.yml |
the four mcp-client rows appended to that list |
bin/install.mjs |
zero-dependency installer + verifier (--dry-run, --check, --global, --force, --standard) |
bootstrap.sh |
one-command end-to-end setup (skill link, key, preset, verify, optional --restart) |
AGENTS.md / CLAUDE.md |
agent entry points (installation target: DeepSeek Harness) |
Handing the link to an agent
The repository is written to be driven by an AI agent, whichever harness it runs in:
AGENTS.mdis the entry point: the target is always DeepSeek Harness, and the agent may run inside or outside DSH; the file carries the preconditions, the bootstrap command, the key/restart rules and the report format;CLAUDE.mdpoints Claude Code at the same file;- every step is idempotent and self-verifying, so an agent can rerun it after a failure without corrupting the profile.
One-command setup on a new machine
Install and launch DeepSeek Harness once, then paste the link:
git clone git@github.com:bosenok/dsh-zai-mcp.git ~/src/github.com/bosenok/dsh-zai-mcp \
&& ~/src/github.com/bosenok/dsh-zai-mcp/bootstrap.sh --restart
bootstrap.sh does everything by itself:
- picks node (the system one or the runtime bundled with the app);
- pulls the latest checkout (skipped when offline / the private remote refuses);
- links the skill into
~/.dsh/skills/dsh-zai-mcp; - provisions
ZAI_API_KEYin~/.dsh/.env— from the credential store of the already configured Z.AI provider,--key, or the environment — and fails with the console link when no source exists; - writes the
preset-zaiagent preset throughbin/install.mjs(idempotent managed block between markers); - verifies the result: env key, patch rows, and a
--dump-configof a throwaway profile copy; - with
--restart, quits and reopens the app so the new.envand preset load.
Afterwards create a new chat, pick the Z.AI (GLM) preset and choose a GLM model in that session; Standard/Creator sessions never mount the servers.
If the Z.AI provider is not configured in DSH yet, either configure it there or
run ./bootstrap.sh --key <token> with a key from
z.ai → API Keys → Personal Coding Plan.
Manual equivalent (same steps, no bootstrap):
ln -s "$PWD" ~/.dsh/skills/dsh-zai-mcp
printf "ZAI_API_KEY='%s'\n" "$KEY" >> ~/.dsh/.env && chmod 600 ~/.dsh/.env
node bin/install.mjs
node bin/install.mjs --check
Options
| Flag | Effect |
|---|---|
--dry-run |
print the managed block, write nothing |
--check |
verify the current state (env, patch, composed profile); write nothing and exit 1 on problems |
--global |
mount the four rows at profile level instead of inside the preset |
--prune-global |
when installing the preset, remove a profile-level mount left by an earlier setup |
--force |
rewrite the managed block even when it already exists |
--dsh-home PATH / --profile NAME |
target another Harness home or profile |
--npx PATH |
absolute npx used by the stdio vision row (default: volta/homebrew probe) |
--standard FILE |
build from another DSH version's presets/standard.patch.yml instead of the committed snapshot |
Updating the preset after a DSH upgrade:
# extract the new standard preset from the installed app (or copy it from a source checkout)
npx asar extract-file "/Applications/DeepSeek Harness.app/Contents/Resources/app.asar" \
node_modules/@deepseek-ai/dsh-bundle-web-app/presets/standard.patch.yml > /tmp/standard.patch.yml
node bin/install.mjs --standard /tmp/standard.patch.yml --force
node bin/install.mjs --check
Install
The skill is a plain directory bundle: SKILL.md with YAML frontmatter plus
optional references/. DSH's filesystem skill provider discovers it under the
user root (~/.dsh/skills), the project root (<repo>/.dsh/skills) or
<repo>/.agents/skills.
git clone git@github.com:bosenok/dsh-zai-mcp.git ~/src/github.com/bosenok/dsh-zai-mcp
ln -s ~/src/github.com/bosenok/dsh-zai-mcp ~/.dsh/skills/dsh-zai-mcp
A symlink keeps the checkout as the single source of truth: editing SKILL.md
here is picked up by the next skill catalog, no restart needed.
Verify
ls -l ~/.dsh/skills/dsh-zai-mcp # -> the checkout
sed -n '1,6p' ~/.dsh/skills/mcp-setup/SKILL.md
In a DSH session the skill appears in the catalog as dsh-zai-mcp.
Versioning
This project follows Semantic Versioning (MAJOR.MINOR.PATCH).
Releases are tagged in git (v0.1.0 and later v0.1.x tags), announced
as GitHub releases and documented in CHANGELOG.md.
Bump policy: patch — fixes; minor — new features without breaking the configuration; major — breaking changes to the configuration, the session format or the supported DSH range.
CHANGELOG.md is generated with git-cliff from
Conventional Commits (cliff.toml):
./scripts/changelog.sh # print unreleased notes
./scripts/changelog.sh v0.2.0 # add the next release section
git cliff -o CHANGELOG.md # full regeneration (curated history is kept otherwise)
Cutting a release. Use the guarded helper instead of hand-cutting one:
./scripts/release.sh patch # or minor / major / an explicit x.y.z
./scripts/release.sh patch --dry-run # print the plan, change nothing
It refuses a dirty tree or a branch other than develop, a target that is not
strictly newer than every existing tag, an existing tag (local or origin) or
GitHub release, then bumps package.json, prepends the CHANGELOG with
git-cliff, runs Git Flow, pushes master/develop/tags and creates the GitHub
release. The committable hooks (.githooks/commit-msg, .githooks/pre-push,
installed by ./scripts/gitflow-setup.sh) reject a chore(release): vX commit
whose version already exists or does not match package.json, and refuse to
move a published tag or push a backwards version.
To install a specific release instead of a moving branch, pin the tag:
dsh plugin --profile desktop add "git+ssh://git@github.com/bosenok/dsh-zai-mcp.git#v0.1.0"
Tags are created on master by Git Flow; integration builds live on develop
(install with #develop if you want the latest unreleased code).
Git Flow
Development follows Git Flow via the
committable .gitflow configuration. In a fresh clone activate it once:
./scripts/gitflow-setup.sh
(The script runs git flow config sync and creates the local master/develop
branches. git flow config sync alone is enough if both base branches already
exist.)
| Branch | Purpose |
|---|---|
master |
released code only; every commit here is tagged vX.Y.Z |
develop |
integration branch (repository default branch) |
feature/* |
one change, started from and finished into develop |
release/* |
stabilization, started from develop, finished into master + develop |
hotfix/* |
urgent production fix, started from master, finished into both |
git flow feature start my-change
# ... conventional commits: feat: …, fix: …, docs: …, chore: …
git flow feature finish my-change
git flow release start 0.2.0
# bump the version; update CHANGELOG.md (see Versioning)
git add -A && git commit -m "chore(release): v0.2.0"
git flow release finish 0.2.0 # merges to master + develop, creates the tag
git push origin master develop --tags
No comments yet. Be the first to write one.