dsh-plugin-pkgseek

PkgSeek Linux package, command and CVE intelligence as native DeepSeek Harness (DSH) tools — plus a system-prompt segment that tells the agent when to use them.

The plugin is a thin adapter over PkgSeek's public MCP-over-HTTP endpoint: at load time it fetches tools/list and registers one native DSH tool per definition (names prefixed pkgseek_), so tools go through the same approval, guard and logging pipeline as built-in tools. Every call is forwarded as tools/call to the hosted API — all tools are read-only and need no API key.

Install

# interactive (web) profile
dsh plugin --profile web add dsh-plugin-pkgseek
# one-shot (headless) profile — dsh run uses this one
dsh plugin --profile headless add dsh-plugin-pkgseek

web and headless are separate profiles; install into both if you use both. The package is published on npm as dsh-plugin-pkgseek; dsh plugin add resolves it from the registry. Installing from the GitHub source also works (dsh plugin --profile web add github:web-casa/dsh-plugin-pkgseek).

The published manifest declares support for DSH >=0.1.0-rc.7 <0.2.0 on both the web and Desktop clients. That declaration lets a strict Cordis v4 catalog verify exact registry evidence; it does not by itself grant marketplace or Microsoft Store approval.

Verification

The plugin was smoke-tested against a live dsh 0.1.0-rc.7 headless profile: it loaded, fetched tools/list from the production API, registered pkgseek_resolve_install, the model called it, and the session log shows the API answer (sudo apt install ripgrep) flowing back through tools/call. Unit tests cover the JSON-RPC client, the schema adapter, the offline snapshot and the config surface (npm test).

Configuration

All settings are optional and live in the plugin's config: row:

- id: pkgseek
  name: dsh-plugin-pkgseek
  config:
    apiBase: https://api.pkgseek.com   # any PkgSeek API deployment
    timeoutMs: 20000                   # per-request timeout
    promptGuidance: true               # register the usage-guidance prompt section
    refreshTools: true                 # refresh tools/list at load (snapshot fallback)
    enabledTools: []                   # allowlist of unprefixed names; empty = all

If the live tools/list fails at load time (offline, API down), the plugin registers from its bundled snapshot and tool calls fail individually with a clear error instead of breaking the profile.

Tools

22 read-only tools, registered with the pkgseek_ prefix:

• Command/tool intelligence: pkgseek_search_tools, pkgseek_get_tool, pkgseek_resolve_install, pkgseek_identify_binary, pkgseek_query_file_provides, pkgseek_compare_distros, pkgseek_get_context
• Error & command doctor: pkgseek_diagnose_linux_error, pkgseek_lint_command, pkgseek_explain_command, pkgseek_suggest_fix
• Packages: pkgseek_search_packages, pkgseek_get_package, pkgseek_compare_package_versions, pkgseek_get_package_history
• Vulnerabilities: pkgseek_search_vulnerabilities, pkgseek_get_vulnerability
• Lifecycle & migration: pkgseek_check_release_lifecycle, pkgseek_get_distro_lifecycle, pkgseek_compare_distro_releases, pkgseek_plan_distro_migration
• Meta: pkgseek_get_repository_health

Development

npm install
npm run sync-tools   # refresh tools.snapshot.json from the live endpoint
npm test             # build + node --test

Layout: src/mcp-client.ts (JSON-RPC over HTTP), src/adapter.ts (MCP tool definitions → defineTool), src/prompt.ts (guidance section), src/index.ts (wiring, config schema).

Release

Releases are deliberately manual. An authorized maintainer dispatches the publish.yml workflow from main, enters the exact unpublished package.json version, and types PUBLISH. The workflow installs locked dependencies without lifecycle scripts, runs the tests, packs the tested artifact, then publishes it through npm Trusted Publishing (GitHub Actions OIDC). It has no npm write token and does not run for pushes or tags.

The npm trusted-publisher binding is restricted to web-casa/dsh-plugin-pkgseek, publish.yml, and the npm-publish environment. Configure required reviewers for that GitHub environment and protect the default branch before delegating release authority; the workflow's manual confirmation is not a substitute for an independent review policy.

License

MIT