alidocs-web-mcp

Let your AI agent read and edit the DingTalk Doc you already have open — in your own browser, under your own login, with every change landing as a suggestion you approve or discard.

中文文档

Why this exists

You are editing a document in your browser. Your AI agent lives somewhere else — an IDE, a terminal, a desktop app. To let the agent help, you normally have two bad options:

The capability you actually want — structured, block-level editing that renders as a reviewable suggestion — only exists inside the page runtime. So instead of recreating it elsewhere, this tool connects your agent to the page you already have open.

The direction is inverted on purpose. The page dials out to a local process; the local process never reaches into your browser. That is what makes it work without debug ports, browser extensions, or any change to your agent's host application.

Related MCP server: webmcp-polyfill

What you get

• Standard MCP over stdio — works with any MCP host (IDE, terminal, desktop agent). No custom protocol to adopt.

• Zero runtime dependencies — plain Node ≥ 18, hand-rolled WebSocket framing. npx and go.

• Zero code injection — the pairing credential is data, never a script. Nothing is ever eval'd.

• Read-only by default — writes require an explicit flag, and land as suggestions rather than saved edits.

• Loopback only — binds 127.0.0.1, enforces an Origin allowlist, and authenticates with an HMAC challenge-response.

Requirements

• Node.js ≥ 18

• A DingTalk Doc page open in a browser, with the page-side connector present

Install & run

Register it with your MCP host — no global install needed:

{
  "mcpServers": {
    "alidocs-web-mcp": {
      "command": "npx",
      "args": ["-y", "alidocs-web-mcp", "--allow-write"]
    }
  }
}

Or run it directly:

npx -y alidocs-web-mcp              # read-only
npx -y alidocs-web-mcp --allow-write # allow the page to register write tools

The bridge tries ports 19837 → 19838 → 19839 and takes the first free one. The page discovers it by probing those same ports, which is why they are fixed rather than random.

How pairing works

Three steps, and the agent can drive all of them:

1. Call get_pairing_code → you get a pairing code (a string of data) and the port.

2. Put that code into the page's "local agent" pairing field — the agent can type and click it, or you can paste it yourself.

3. The page completes an HMAC handshake. From then on tools/list includes the document tools.

After a refresh or same-tab navigation, the page reconnects automatically using the code it kept in sessionStorage. No re-pairing.

Architecture

flowchart LR
    subgraph outside["Outside the browser"]
        host["MCP host<br/>(IDE / terminal / desktop agent)"]
        bridge["alidocs-web-mcp<br/>pairing + dumb pipe"]
    end
    subgraph browser["Your browser, your login"]
        page["Document page<br/>MCP server + tools"]
        doc["Document<br/>suggestion state"]
    end

    host <-->|"stdio · standard MCP"| bridge
    page -->|"1 · discover: GET /health"| bridge
    page <-->|"2 · ws://127.0.0.1 · HMAC handshake<br/>3 · JSON-RPC passthrough"| bridge
    page --> doc

    classDef trust fill:#eef7ff,stroke:#4b86c9
    classDef local fill:#f6f6f6,stroke:#999
    class browser trust
    class outside local

Two properties worth noting:

• The page always initiates. The bridge only listens on loopback; it never dials into the browser.

• The bridge is a dumb pipe. Beyond its own three tools, it merges tools/list and forwards tools/call verbatim. It does not understand document semantics — so the page can add tools without changing the bridge.

Data flow

sequenceDiagram
    autonumber
    participant H as MCP host
    participant B as alidocs-web-mcp
    participant P as Document page
    participant D as Document

    Note over B: bind 127.0.0.1, generate a per-session pairing code (CSPRNG)

    H->>B: tools/call get_pairing_code
    B-->>H: pairingCode + port (data, never a script)

    P->>B: GET /health on 19837/38/39
    B-->>P: { service, originAllowed, ... }

    Note over H,P: the code reaches the page via UI (typed or pasted)

    P->>B: WS upgrade (Origin checked here → 403 if not allowed)
    B-->>P: challenge { nonce }
    P->>B: auth { mac = HMAC-SHA256(pairingCode, nonce) }
    B-->>P: ready { sessionId }
    B->>H: notifications/tools/list_changed

    H->>B: tools/call read_document
    B->>P: forwarded verbatim (id remapped)
    P->>D: read
    D-->>P: content
    P-->>B: result
    B-->>H: result

    H->>B: tools/call update_block
    B->>P: forwarded verbatim
    P->>D: write as a suggestion (not saved)
    Note over D: you approve or discard it

The pairing code itself is never transmitted — only HMAC(code, nonce) is. Someone who squats the port and captures the mac still cannot recover the code.

Bridge tools

Everything else you see in tools/list comes from the page; the bridge only forwards it.

CLI options

The default allowlist contains only the official document origins plus local dev hosts, enumerated one by one. There is deliberately no wildcard like https://*.dingtalk.com — that would let any subdomain reach your local bridge.

Security posture

This tool opens a listening port on your machine, so it is worth being explicit. Four attack directions, each with its own defence:

Also: /health responses are tiered by Origin (outsiders cannot read connected or allowWrite), one session at a time, and the audit log records tool names and argument keys — never argument values or the pairing code.

Full threat model and the S1–S13 control list: docs/security.md. Reporting a vulnerability: SECURITY.md.

Troubleshooting

Development

npm install       # dev deps only (typescript, @types/node)
npm run build     # tsc → dist/ (CommonJS + .d.ts)
npm test          # runs against dist/ — i.e. against what actually ships
npm run verify    # build + test
npm run typecheck # tsc --noEmit

Source is TypeScript under src/; the published artifact is compiled CommonJS in dist/. Tests stay in plain JavaScript on purpose — they exercise the built output rather than the sources, so the thing being verified is the thing being published. Because the bridge uses a fixed port set, tests run serially.

Downstream projects can build contract tests against a real bridge process:

const { startTestBridge, connectFakePage } = require('alidocs-web-mcp/test-helpers');

See CONTRIBUTING.md and AGENT.md (the latter lists constraints that must not be violated, e.g. "never return executable code").

Project status

Early (0.x). Verified today:

• 49 automated tests over the compiled artifact

• 12 Origin bypass attempts (subdomain suffixing, full-URL-in-Origin, trailing dot, case variants, scheme downgrade, null, missing, port injection, backslash confusion) all rejected at the real upgrade path

• Business messages sent before the handshake are rejected and the socket closed

• Cross-implementation HMAC agreement with the page side, pinned by shared test vectors

Not yet verified: a real MCP host consuming this server end to end. Development so far used a purpose-built minimal MCP client, which also means the notifications/tools/list_changed path — how a host learns that document tools appeared after pairing — has only been covered by automated tests with a fake host, not observed against a real one.

Documentation

• docs/design.md — design, trade-offs, and the three couplings you cannot separate

• docs/security.md — threat model and control list

• AGENT.md — conventions for AI agents working on this repo

• CHANGELOG.md

License

MIT