dsh-paper-design

dsh-paper-design

Paper Design MCP bridge as a DeepSeek Harness bundle.

Connects to the Paper Desktop MCP server (http://127.0.0.1:29979/mcp), registers every Paper tool as a native paper_* tool with image screenshot support, injects Cursor-parity design guidance, registers the Paper skills, and exposes reconnect + OAuth auth commands.

What it provides

• paper_* tools — every tool advertised by Paper Desktop MCP (get_basic_info, get_screenshot, write_html, update_styles, …), registered natively on ctx.tools. Raw MCP inputSchemas are normalized to the enforced DSH JSON-Schema subset ($schema/format/pattern/propertyNames/min*/max* stripped, anyOf→oneOf).
• Image screenshot forwarding — get_screenshot image blocks are decoded and durably committed through ctx.attachments (saveImage), then emitted as attachment-backed image blocks (and deferred as plugin-sourced context for nested run_code dispatches), so screenshots reach image-capable models.
• Cursor-parity guidance — standing rules injected as a system-prompt section (order 150), plus the full paper-mcp-instructions guide injected for the first 2 agent turns after connect/reconnect. paper_get_guide also caches the guide body.
• Skills — code-to-design, design-to-code (Cursor Paper plugin bodies verbatim), and paper-design (progressive-disclosure tool reference index).
• /paper-reconnect — re-initializes the MCP session, (re)registers the paper_* tools, clears the guide cache, and resets the early-turn guide-injection budget.
• Late-start recovery — DSH is usually booted long before Paper Desktop is opened, so a failed first connection is not terminal: the bridge retries in the background (10s by default; retryMs changes it) and publishes the tools as soon as the server answers. The prompt section, skills, and commands register up front, so /paper-reconnect exists even while Paper is closed.
• MCP OAuth auth (Cursor parity) — a discovery-driven OAuth 2.1 client: RFC 8414/OIDC discovery probe → RFC 7591 dynamic client registration → PKCE (RFC 7636) authorization via loopback redirect → token exchange/refresh → bearer-token attachment with 401/403 WWW-Authenticate challenge handling (RFC 9728). Tokens persist to $DSH_HOME/paper-design/oauth.json. Paper Desktop currently runs unauthenticated on localhost (no discovery/challenge), so the bridge stays dormant there and the auth layer activates only when a server advertises or challenges auth. Commands:
  • /paper-auth-status — show mode (unauthenticated vs oauth), configured/authenticated state, expiry, discovery endpoints, last challenge/error.
  • /paper-auth-login — start the OAuth authorization flow (opens the browser; falls back to printing the URL).
  • /paper-auth-logout — clear stored tokens.

Requirements

• Paper Desktop running with a file open (the MCP server lives inside the desktop app). It does not have to be running when DSH boots — the bridge picks it up when it appears.
• DSH 0.2.0-rc.2 or 0.1.0-rc.5+ — the plugin declares matching @deepseek-ai/dsh-* peer ranges, and DSH refuses to load it on a runtime outside them.
• A DeepSeek Harness profile that bundles @deepseek-ai/dsh-base (or the services it mounts): tools, systemPrompt, attachments (for images), skills, commands, llm.
• An image-capable model route for screenshot support (text tools work on any route).

Install

Add this package to the profile and its bundles list, e.g. in ~/.dsh/profiles/<name>/package.json:

{
  "dependencies": {
    "@try-works/dsh-paper-design": "^0.1.6"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@try-works/dsh-paper-design"
      ]
    }
  }
}

Then pnpm install in the profile and restart the running DSH process. The bridge ships its src/*.ts sources directly (DSH loads them through tsx), mirroring dsh-recursive-mode.

Restart is required for host/bundle changes: the web client-plugin HMR only rebuilds the web shell, not host plugins.

Usage

• Ask the agent to read or design in Paper; it will use paper_get_basic_info, paper_open_file, paper_get_screenshot, and the rest.
• /paper-reconnect republishes the tools and re-syncs after restarting Paper Desktop. You normally do not need it: the tools appear on their own when Paper starts.
• /paper-auth-status / /paper-auth-login / /paper-auth-logout manage OAuth auth when a server requires it.

Development

pnpm install
pnpm run build                        # type-check (tsc -p tsconfig.build.json)
pnpm run verify                       # live MCP bridge verification (needs Paper Desktop)
pnpm run verify:bridge                # in-process plugin boot + live paper_get_basic_info
pnpm run verify:parity                # Cursor/pi skill-body parity
pnpm run verify:injection             # prompt-section marker/budget logic
pnpm run verify:auth                  # OAuth flow vs a mock authorization server
pnpm run test:unit                    # bridge + late-start recovery (stub MCP; no Paper needed)
pnpm test                             # everything above

Layout

• src/index.ts — bundle entry: register prompt/skills/commands, then connect, normalize, and (re)register tools with late-start retry.
• src/mcp-client.ts — minimal Streamable HTTP MCP client (initialize/tools-list/tools-call, session tracking, SSE parsing, one-shot re-init, bearer-token + challenge hooks).
• src/auth.ts — discovery-driven MCP OAuth 2.1 client (RFC 8414/OIDC discovery, DCR, PKCE, loopback redirect, token exchange/refresh, persisted store, challenge handling).
• src/schema.ts — raw Paper JSON Schema → enforced DSH subset normalizer.
• src/guide.ts — standing rules + early-turn guide markers and builder.
• src/skills.ts — runtime skill registrations.
• skills/*/SKILL.md — on-disk skill bodies (parity artifacts).
• cordis.patch.yml — loader patch inserting the bridge into a cordis:group realm.

License

MIT