writedock-mcp 0.0.0-stage → 0.4.2

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "writedock-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.2",
+  "description": "WriteDock local MCP server for the browser extension",
+  "type": "commonjs",
+  "license": "GPL-3.0-only",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "writedock-mcp": "index.cjs"
+  },
+  "files": [
+    "index.cjs",
+    "README.md",
+    "LICENSE",
+    "LICENSE-MULTIPOST",
+    "NOTICE.md",
+    "THIRD_PARTY_NOTICES.txt",
+    "source"
+  ],
+  "keywords": [
+    "mcp",
+    "writedock",
+    "browser-extension",
+    "publishing"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  }
 }

package/source/distribution.json

@@ -0,0 +1,5 @@
+{
+  "name": "writedock-mcp",
+  "tag": "latest",
+  "registry": "https://registry.npmjs.org/"
+}

package/source/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@writedock/mcp-server",
+  "version": "0.4.2",
+  "private": true,
+  "type": "module",
+  "description": "WriteDock local MCP server for the browser extension",
+  "license": "GPL-3.0-only",
+  "bin": {
+    "writedock-mcp": "dist/index.cjs"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "ws": "^8.18.0",
+    "zod": "^3.25.76",
+    "marked": "^17.0.1",
+    "linkedom": "^0.18.12",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13",
+    "tsup": "^8.0.1",
+    "vitest": "^2.1.9",
+    "@types/node": "^22.10.2"
+  }
+}

package/source/src/__tests__/article.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { resolve } from 'node:path'
+import { prepareSource } from '../article'
+
+const roots: string[] = []
+const png = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScLbtAAAAABJRU5ErkJggg==', 'base64')
+afterEach(async () => { await Promise.all(roots.splice(0).map(path => rm(path, { force: true, recursive: true }))) })
+
+async function fixture() {
+  const path = await mkdtemp(resolve(tmpdir(), 'writedock-article-'))
+  roots.push(path)
+  await writeFile(resolve(path, 'image.png'), png)
+  return path
+}
+
+describe('agent-authored article input', () => {
+  it('reads Markdown title and reference images, embeds local pictures and the cover', async () => {
+    const path = await fixture()
+    await writeFile(resolve(path, 'article.md'), '# 同步示例\n\n正文 **加粗**。\n\n![示意图][picture]\n\n[picture]: ./image.png\n')
+    const result = await prepareSource({ file_path: resolve(path, 'article.md'), cover: './image.png' })
+    expect(result.title).toBe('同步示例')
+    expect(result.html).toContain('<strong>加粗</strong>')
+    expect(result.html).toContain('data:image/png;base64,')
+    expect(result.html).not.toContain('./image.png')
+    expect(result.cover).toMatch(/^data:image\/png;base64,/)
+  })
+
+  it('supports HTML files and explicit titles without reading ordinary links as files', async () => {
+    const path = await fixture()
+    const result = await prepareSource({ html: '<p>正文 <a href="/etc/secret">链接</a></p><img src="image.png">', title: 'HTML 稿件', base_directory: path })
+    expect(result.title).toBe('HTML 稿件')
+    expect(result.html).toContain('/etc/secret')
+    expect(result.html).toContain('data:image/png;base64,')
+    await expect(prepareSource({ markdown: '正文' })).rejects.toThrow('标题')
+  })
+
+  it('rejects directory traversal, invalid image bytes, video and ambiguous inputs', async () => {
+    const path = await fixture()
+    await mkdir(resolve(path, 'nested'))
+    await expect(prepareSource({ title: '测试', markdown: '![x](../image.png)', base_directory: resolve(path, 'nested') })).rejects.toThrow('必须位于')
+    await writeFile(resolve(path, 'invalid.png'), 'this is not an image')
+    await expect(prepareSource({ title: '测试', markdown: '![x](invalid.png)', base_directory: path })).rejects.toThrow('有效的 PNG')
+    await writeFile(resolve(path, 'video.mp4'), 'video')
+    await expect(prepareSource({ file_path: resolve(path, 'video.mp4') })).rejects.toThrow('稿件文件仅支持')
+    await expect(prepareSource({ title: '测试', markdown: '正文', html: '<p>正文</p>' })).rejects.toThrow('一种稿件来源')
+  })
+})

package/source/src/__tests__/bridge.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { createServer } from 'node:net'
+import { once } from 'node:events'
+import { randomBytes } from 'node:crypto'
+import { WebSocket } from 'ws'
+import { LocalBridge, proof, requestProof } from '../bridge'
+
+const token = 'test-pairing-key-that-is-long-enough'
+const brokers: LocalBridge[] = []
+const clients: WebSocket[] = []
+async function unusedPort() {
+  const listener = createServer().listen(0, '127.0.0.1')
+  await once(listener, 'listening')
+  const port = (listener.address() as { port: number }).port
+  await new Promise<void>(resolve => listener.close(() => resolve()))
+  return port
+}
+async function broker() {
+  const bridge = new LocalBridge({ token, port: await unusedPort(), timeoutMs: 1000 })
+  brokers.push(bridge); await bridge.start(); return bridge
+}
+async function pair(bridge: LocalBridge, key = token) {
+  const ws = new WebSocket(`ws://127.0.0.1:${bridge.port}/extension`)
+  clients.push(ws)
+  ws.on('message', raw => {
+    const message = JSON.parse(raw.toString())
+    if (message.type === 'challenge') ws.send(JSON.stringify({ type: 'hello', proof: proof(key, 'extension', message.nonce), extensionId: 'fixture-extension' }))
+  })
+  return ws
+}
+afterEach(async () => { clients.splice(0).forEach(ws => ws.terminate()); await Promise.all(brokers.splice(0).map(value => value.close())) })
+
+describe('authenticated local bridge', () => {
+  it('rejects unauthenticated HTTP calls and browser-origin requests', async () => {
+    const bridge = await broker()
+    const url = `http://127.0.0.1:${bridge.port}/status`
+    const nonce = randomBytes(32).toString('hex'), time = String(Date.now())
+    const headers = { 'X-Writedock-Nonce': nonce, 'X-Writedock-Time': time, 'X-Writedock-Proof': requestProof(token, 'GET', '/status', nonce, time) }
+    expect((await fetch(url)).status).toBe(403)
+    expect((await fetch(url, { headers: { ...headers, Origin: 'https://example.com' } })).status).toBe(403)
+    expect((await fetch(url, { headers })).status).toBe(200)
+    expect((await fetch(url, { headers })).status).toBe(403)
+  })
+
+  it('rejects an extension with the wrong key, then connects an authenticated extension', async () => {
+    const bridge = await broker()
+    const wrong = await pair(bridge, 'wrong-key')
+    const closed = await once(wrong, 'close')
+    expect(closed[0]).toBe(1008)
+    const ws = await pair(bridge)
+    await new Promise<void>(resolve => ws.on('message', raw => { if (JSON.parse(raw.toString()).type === 'ready') resolve() }))
+    expect((await bridge.status()).connected).toBe(true)
+    ws.on('message', raw => {
+      const message = JSON.parse(raw.toString())
+      if (message.method) ws.send(JSON.stringify({ id: message.id, result: { method: message.method } }))
+    })
+    expect(await bridge.request('getSyncHistory')).toEqual({ method: 'getSyncHistory' })
+  })
+
+  it('allows two MCP clients to share a port without replacing the extension or re-sending requests', async () => {
+    const first = await broker()
+    const ws = await pair(first)
+    await new Promise<void>(resolve => ws.on('message', raw => { if (JSON.parse(raw.toString()).type === 'ready') resolve() }))
+    let requests = 0
+    ws.on('message', raw => {
+      const message = JSON.parse(raw.toString())
+      if (message.method) { requests++; ws.send(JSON.stringify({ id: message.id, result: 'ok' })) }
+    })
+    const second = new LocalBridge({ token, port: first.port, timeoutMs: 1000 })
+    brokers.push(second)
+    await second.start()
+    expect(await second.request('listPlatforms')).toBe('ok')
+    expect(requests).toBe(1)
+    const wrong = new LocalBridge({ token: 'other-valid-key-that-is-long-enough', port: first.port })
+    brokers.push(wrong)
+    await expect(wrong.start()).rejects.toThrow('认证失败')
+  })
+
+  it('lets a remaining MCP client acquire the bridge when the first process exits', async () => {
+    const first = await broker()
+    const second = new LocalBridge({ token, port: first.port, timeoutMs: 1000 })
+    brokers.push(second)
+    await second.start()
+    await first.close()
+    expect((await second.status()).connected).toBe(false)
+    const ws = await pair(second)
+    await new Promise<void>(resolve => ws.on('message', raw => { if (JSON.parse(raw.toString()).type === 'ready') resolve() }))
+    expect((await second.status()).connected).toBe(true)
+  })
+})

package/source/src/article.ts

@@ -0,0 +1,127 @@
+import { readFile, realpath, stat } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { marked, type Tokens } from 'marked'
+import { parseHTML } from 'linkedom'
+import { parse as parseYaml } from 'yaml'
+import { mediaPath, type MediaAsset } from './media'
+
+export interface ArticleSource {
+  file_path?: string
+  title?: string
+  markdown?: string
+  html?: string
+  cover?: string
+  base_directory?: string
+}
+const ARTICLE_LIMIT = 24 * 1024 * 1024
+const IMAGE_LIMIT = 8 * 1024 * 1024
+const TEXT_LIMIT = 2 * 1024 * 1024
+
+function imageMime(bytes: Buffer): string {
+  if (bytes.subarray(0, 8).equals(Buffer.from([137,80,78,71,13,10,26,10]))) return 'image/png'
+  if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return 'image/jpeg'
+  if (/^GIF8[79]a$/.test(bytes.subarray(0, 6).toString())) return 'image/gif'
+  if (bytes.subarray(0, 4).toString() === 'RIFF' && bytes.subarray(8, 12).toString() === 'WEBP') return 'image/webp'
+  throw new Error('文章插图只支持有效的 PNG、JPEG、GIF、WebP；视频投稿请使用 prepare_post / publish_post')
+}
+
+export async function prepareSource(source: ArticleSource, registerVideo?: (path: string) => Promise<MediaAsset>) {
+  const choices = [source.file_path, source.markdown, source.html].filter(value => value !== undefined)
+  if (choices.length !== 1) throw new Error('请只提供 file_path、markdown 或 html 中的一种稿件来源')
+  let markdown = source.markdown
+  let html = source.html
+  let title = source.title?.trim() || ''
+  let baseDirectory = source.base_directory ? await realpath(source.base_directory) : undefined
+  if (source.file_path) {
+    if (!isAbsolute(source.file_path)) throw new Error('file_path 必须是绝对路径')
+    const filename = await realpath(source.file_path)
+    const info = await stat(filename)
+    if (!info.isFile() || info.size > TEXT_LIMIT) throw new Error('稿件必须是 2 MB 以内的 Markdown 或 HTML 文件')
+    const text = (await readFile(filename, 'utf8')).replace(/^\uFEFF/, '')
+    if (/\.(md|markdown|mdown)$/i.test(filename)) markdown = text
+    else if (/\.html?$/i.test(filename)) html = text
+    else throw new Error('稿件文件仅支持 .md、.markdown、.html、.htm')
+    baseDirectory ??= dirname(filename)
+  }
+
+  const embedded = new Map<string, string>()
+  let imageBytes = 0
+  const embedImage = async (src: string): Promise<string> => {
+    if (embedded.has(src)) return embedded.get(src)!
+    if (/^https?:\/\//i.test(src)) { new URL(src); return src }
+    let bytes: Buffer
+    if (src.startsWith('data:')) {
+      const match = /^data:image\/(?:png|jpeg|gif|webp);base64,([A-Za-z0-9+/=\r\n]+)$/i.exec(src)
+      if (!match) throw new Error('图片 data URI 无效，或图片格式不受支持')
+      bytes = Buffer.from(match[1], 'base64')
+    } else {
+      if (!baseDirectory) throw new Error('稿件包含本地图片，请提供 base_directory 或使用 file_path')
+      const path = src.startsWith('file:') ? fileURLToPath(src) : decodeURIComponent(src)
+      if (/^[a-z][a-z0-9+.-]*:/i.test(path) && !isAbsolute(path)) throw new Error('图片地址只支持 HTTP(S)、本地图片或 data URI')
+      const filename = await realpath(resolve(baseDirectory, path))
+      const inside = relative(baseDirectory, filename)
+      if (inside === '..' || inside.startsWith('../') || inside.startsWith('..\\') || isAbsolute(inside)) throw new Error('本地图片必须位于稿件目录或明确指定的 base_directory 内')
+      const info = await stat(filename)
+      if (!info.isFile() || info.size > IMAGE_LIMIT) throw new Error('单张本地图片不能超过 8 MB')
+      bytes = await readFile(filename)
+    }
+    if (!bytes.length || bytes.length > IMAGE_LIMIT) throw new Error('单张图片必须在 8 MB 以内')
+    const mime = imageMime(bytes)
+    imageBytes += bytes.length
+    if (imageBytes > 18 * 1024 * 1024) throw new Error('稿件图片总量过大，请先压缩图片')
+    const result = `data:${mime};base64,${bytes.toString('base64')}`
+    embedded.set(src, result)
+    embedded.set(result, result)
+    return result
+  }
+
+  if (markdown !== undefined) {
+    const front = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown)
+    if (front) {
+      const meta: unknown = parseYaml(front[1])
+      if (!title && meta && typeof meta === 'object' && 'title' in meta && typeof meta.title === 'string') title = meta.title.trim()
+      markdown = markdown.slice(front[0].length)
+    }
+    const heading = /^\s*#\s+(.+?)(?:\r?\n|$)/.exec(markdown)
+    if (heading) {
+      title ||= heading[1].trim()
+      if (heading[1].trim() === title) markdown = markdown.slice(heading[0].length)
+    }
+    const tokens = marked.lexer(markdown)
+    const images: Tokens.Image[] = []
+    marked.walkTokens(tokens, token => { if (token.type === 'image') images.push(token as Tokens.Image) })
+    for (const image of images) image.href = await embedImage(image.href)
+    html = marked.parser(tokens)
+  }
+  const { document } = parseHTML(/<html\b/i.test(html || '') ? html! : `<html><head></head><body>${html || ''}</body></html>`)
+  title ||= document.querySelector('title')?.textContent?.trim() || document.querySelector('h1')?.textContent?.trim() || ''
+  const videos: { marker: string; asset: MediaAsset }[] = []
+  for (const video of document.querySelectorAll('video')) {
+    if (!registerVideo) throw new Error('文章内嵌视频请使用 prepare_article / publish_article，目前只支持知乎')
+    if (videos.length >= 5) throw new Error('当前每篇知乎文章最多接收 5 个本地视频')
+    const src = video.getAttribute('src') || video.querySelector('source')?.getAttribute('src')
+    if (!src || /^(https?:|data:|blob:)/i.test(src)) throw new Error('内嵌视频需要通过 <video src="本地路径"></video> 提供本机 MP4 文件')
+    const path = src.startsWith('file:') ? fileURLToPath(src) : decodeURIComponent(src)
+    const asset = await registerVideo(await mediaPath(path, baseDirectory))
+    if (asset.type !== 'video/mp4') throw new Error('当前知乎文章内嵌视频仅接入 MP4 格式')
+    if (videos.reduce((sum, item) => sum + item.asset.size, asset.size) > 512 * 1024 * 1024) throw new Error('文章内嵌视频总量不能超过 512 MB')
+    const marker = `WRITEDOCK_VIDEO_${videos.length + 1}`
+    if (document.body.textContent?.includes(marker)) throw new Error('正文含有保留的视频占位符，请修改后重新提交')
+    const placeholder = document.createElement('p')
+    placeholder.textContent = marker
+    video.replaceWith(placeholder)
+    videos.push({ marker, asset })
+  }
+  for (const image of document.querySelectorAll('img')) {
+    const src = image.getAttribute('src')
+    if (!src) throw new Error('正文包含没有地址的图片')
+    image.setAttribute('src', await embedImage(src))
+    image.removeAttribute('srcset')
+  }
+  const cover = source.cover ? await embedImage(source.cover) : undefined
+  if (!title || title.length > 200) throw new Error('请提供 1–200 字的文章标题，或在稿件中使用一级标题')
+  const article = { title, html: document.body.innerHTML, markdown: '', ...(cover ? { cover } : {}), ...(videos.length ? { videos } : {}) }
+  if (Buffer.byteLength(JSON.stringify(article)) > ARTICLE_LIMIT) throw new Error('稿件超过 24 MB，请压缩图片')
+  return article
+}

package/source/src/bridge.ts

@@ -0,0 +1,298 @@
+/** Local bridge, based on Wechatsync's stdio → WebSocket architecture (MIT).
+ * WriteDock uses one loopback port, authenticated forwarding and mutual HMAC pairing.
+ */
+import http from 'node:http'
+import { createCipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
+import { WebSocket, WebSocketServer } from 'ws'
+import { MediaStore, type MediaAsset } from './media'
+import { mcpReleaseInfo } from './release-info'
+
+const LIMIT = 32 * 1024 * 1024
+const messageOf = (error: unknown) => error instanceof Error ? error.message : String(error)
+export const proof = (token: string, role: string, nonce: string) => createHmac('sha256', token).update(`${role}:${nonce}`).digest('hex')
+const digest = (body: string | Buffer) => createHash('sha256').update(body).digest('hex')
+export const requestProof = (token: string, method: string, path: string, nonce: string, time: string, body = '') => proof(token, `http-request:${method}:${path}:${time}:${digest(body)}`, nonce)
+function equal(a: string, b: string) {
+  const left = Buffer.from(a); const right = Buffer.from(b)
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+export class LocalBridge {
+  private server?: http.Server
+  private sockets?: WebSocketServer
+  private client?: WebSocket
+  private heartbeat?: ReturnType<typeof setInterval>
+  private starting?: Promise<void>
+  private primary = false
+  private extensionId?: string
+  private seenNonces = new Map<string, number>()
+  private pairing?: { code: string; expiresAt: number; attempts: number }
+  private extensionToken: string
+  private media: MediaStore
+  private pending = new Map<string, { resolve: (value: unknown) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }>()
+  readonly port: number
+  constructor(private options: { token: string; port?: number; timeoutMs?: number; credentials?: { getExtensionToken: () => Promise<string>; setExtensionToken: (token: string) => Promise<void> } }) {
+    this.port = options.port ?? 9647
+    this.extensionToken = options.token
+    this.media = new MediaStore(this.port)
+    if (!Number.isInteger(this.port) || this.port < 1024 || this.port > 65535) throw new Error('WRITEDOCK_PORT 必须是 1024–65535 的整数')
+    if (!/^[A-Za-z0-9_-]{24,128}$/.test(options.token)) throw new Error('MCP 本机身份密钥格式不正确')
+  }
+
+  async start(): Promise<void> {
+    if (this.starting) return this.starting
+    this.starting = this.listen().catch(async error => {
+      if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error
+      this.server = undefined
+      this.sockets = undefined
+      // Only attach to a broker that proves it holds this pairing key.
+      await this.httpCall('/status')
+    }).catch(error => { this.starting = undefined; throw error })
+    return this.starting
+  }
+
+  private async listen(): Promise<void> {
+    if (this.options.credentials) this.extensionToken = await this.options.credentials.getExtensionToken()
+    const server = http.createServer((req, res) => { void this.handleHttp(req, res) })
+    const sockets = new WebSocketServer({ noServer: true, maxPayload: LIMIT })
+    this.server = server; this.sockets = sockets
+    server.on('upgrade', (req, socket, head) => {
+      const origin = req.headers.origin
+      const extensionOrigin = typeof origin === 'string' && /^chrome-extension:\/\/[a-p]{32}$/.test(origin)
+      if (!this.validHost(req.headers.host) || !['/extension', '/pair'].includes(req.url || '') || (origin && !extensionOrigin) || (req.url === '/pair' && !extensionOrigin)) {
+        socket.write('HTTP/1.1 403 Forbidden\r\n\r\n'); socket.destroy(); return
+      }
+      sockets.handleUpgrade(req, socket, head, ws => { if (req.url === '/pair') this.acceptPairing(ws); else this.accept(ws) })
+    })
+    await new Promise<void>((resolve, reject) => {
+      server.once('error', reject)
+      server.listen(this.port, '127.0.0.1', () => { server.off('error', reject); resolve() })
+    })
+    this.primary = true
+    mcpReleaseInfo()
+    this.heartbeat = setInterval(() => {
+      const release = mcpReleaseInfo()
+      if (this.client?.readyState === WebSocket.OPEN) this.client.send(JSON.stringify({ type: 'ping', ...release }))
+    }, 20_000)
+    this.heartbeat.unref()
+  }
+
+  private validHost(host?: string) { return host === `127.0.0.1:${this.port}` || host === `localhost:${this.port}` }
+
+  async beginPairing(): Promise<Record<string, unknown>> {
+    const state = await this.status() // Also acquire the vacant bridge after another MCP client exits.
+    if (!this.primary && state.pairing_available !== true) throw new Error('本机端口仍由旧版 MCP 占用。请重启仍使用旧版本的 agent/MCP 进程，保留原配置后再生成配对码。')
+    if (!this.primary) return this.httpCall('/pairing', {})
+    const secret = randomBytes(8).toString('hex').toUpperCase().match(/.{4}/g)!.join('-')
+    const code = `WD1-${this.port}-${secret}`
+    const expiresAt = Date.now() + 180_000
+    this.pairing = { code, expiresAt, attempts: 0 }
+    return { pairing_code: code, expires_at: new Date(expiresAt).toISOString(), expires_in_seconds: 180, instructions: '将此一次性配对码粘贴到扩展的「MCP 连接 → 输入一次性配对码」。有效期 3 分钟，使用一次后失效。无需重新安装 MCP 或修改 agent 配置。确认用户要连接当前扩展后再生成。' }
+  }
+
+  private acceptPairing(ws: WebSocket) {
+    const pairing = this.pairing
+    if (!pairing || Date.now() > pairing.expiresAt || pairing.attempts >= 8) { ws.close(1008, 'Pairing code expired'); return }
+    pairing.attempts++
+    const nonce = randomBytes(32).toString('hex')
+    const timer = setTimeout(() => ws.close(1008, 'Pairing timed out'), 10_000)
+    ws.send(JSON.stringify({ type: 'pairing_challenge', nonce, proof: proof(pairing.code, 'pairing-server', nonce) }))
+    let consumed = false
+    ws.on('message', raw => {
+      void (async () => {
+        if (consumed) return
+        consumed = true
+        const body = raw.toString()
+        if (body.length > 2048) throw new Error('Invalid pairing message')
+        const message = JSON.parse(body)
+        if (this.pairing !== pairing || Date.now() > pairing.expiresAt || message.type !== 'pairing_hello' || typeof message.proof !== 'string' || !equal(message.proof, proof(pairing.code, 'pairing-extension', nonce))) throw new Error('Pairing failed')
+        this.pairing = undefined // Consume before the first asynchronous operation.
+        const token = randomBytes(32).toString('hex')
+        await this.options.credentials?.setExtensionToken(token)
+        this.extensionToken = token
+        // A deliberate new pairing retires the old extension credential, not the MCP identity.
+        const previousClient = this.client
+        this.client = undefined; this.extensionId = undefined
+        for (const value of this.pending.values()) { clearTimeout(value.timer); value.reject(new Error('扩展配对已更换；请查询原同步任务，不要自动重新提交。')) }
+        this.pending.clear()
+        previousClient?.close(1000, 'Extension pairing replaced')
+        const key = createHmac('sha256', pairing.code).update(`writedock-pairing-key:${nonce}`).digest()
+        const iv = randomBytes(12)
+        const cipher = createCipheriv('aes-256-gcm', key, iv)
+        cipher.setAAD(Buffer.from('writedock-pairing-v1'))
+        const ciphertext = Buffer.concat([cipher.update(JSON.stringify({ token, port: this.port, protocol: 'writedock/1' })), cipher.final(), cipher.getAuthTag()])
+        clearTimeout(timer)
+        if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'pairing_result', iv: iv.toString('base64'), ciphertext: ciphertext.toString('base64') }))
+        ws.close(1000)
+      })().catch(() => { ws.close(1008, 'Pairing failed') })
+    })
+    ws.on('close', () => clearTimeout(timer))
+    ws.on('error', () => {})
+  }
+
+  private accept(ws: WebSocket) {
+    const nonce = randomBytes(32).toString('hex')
+    const token = this.extensionToken
+    let authenticated = false
+    const timer = setTimeout(() => ws.close(1008, 'Pairing timed out'), 8000)
+    ws.send(JSON.stringify({ type: 'challenge', nonce, proof: proof(token, 'server', nonce) }))
+    ws.on('message', raw => {
+      try {
+        const message = JSON.parse(raw.toString())
+        if (!authenticated) {
+          if (token !== this.extensionToken || message.type !== 'hello' || typeof message.proof !== 'string' || !equal(message.proof, proof(token, 'extension', nonce))) {
+            ws.close(1008, 'Pairing failed'); return
+          }
+          if (this.client?.readyState === WebSocket.OPEN) { ws.close(1008, 'An extension is already connected'); return }
+          authenticated = true; clearTimeout(timer)
+          this.client = ws; this.extensionId = String(message.extensionId || '')
+          ws.send(JSON.stringify({ type: 'ready', ...mcpReleaseInfo() }))
+          return
+        }
+        if (message.type === 'pong') return
+        const pending = this.pending.get(message.id)
+        if (!pending) return
+        this.pending.delete(message.id); clearTimeout(pending.timer)
+        if (message.error) pending.reject(new Error(message.error.message || '扩展操作失败'))
+        else pending.resolve(message.result)
+      } catch { ws.close(1008, 'Invalid message') }
+    })
+    ws.on('close', () => {
+      clearTimeout(timer)
+      if (this.client !== ws) return
+      this.client = undefined; this.extensionId = undefined
+      for (const value of this.pending.values()) {
+        clearTimeout(value.timer)
+        value.reject(new Error('扩展连接已断开。若已提交同步，请按任务 ID 查询结果，不要更换 request_id 自动重发。'))
+      }
+      this.pending.clear()
+    })
+    ws.on('error', () => {})
+  }
+
+  private async handleHttp(req: http.IncomingMessage, res: http.ServerResponse) {
+    res.setHeader('Content-Type', 'application/json; charset=utf-8')
+    res.setHeader('Cache-Control', 'no-store')
+    let responseNonce: string | undefined
+    const send = (status: number, value: unknown) => {
+      const body = JSON.stringify(value)
+      if (responseNonce) res.setHeader('X-Writedock-Proof', proof(this.options.token, `http-response:${digest(body)}`, responseNonce))
+      res.writeHead(status); res.end(body)
+    }
+    const assetPath = /^\/assets\/([a-f0-9-]{36})$/.exec(req.url || '')
+    if (assetPath && this.validHost(req.headers.host) && (!req.headers.origin || /^chrome-extension:\/\/[a-p]{32}$/.test(req.headers.origin))) {
+      await this.media.serve(req, res, assetPath[1]); return
+    }
+    if (!this.validHost(req.headers.host) || req.headers.origin !== undefined) {
+      send(403, { error: '本地桥接认证失败，请检查连接密钥和端口' }); return
+    }
+    try {
+      const chunks: Buffer[] = []; let size = 0
+      for await (const chunk of req) {
+        size += chunk.length
+        if (size > LIMIT) { send(413, { error: '稿件过大，请压缩图片' }); return }
+        chunks.push(chunk)
+      }
+      const body = Buffer.concat(chunks).toString()
+      const nonce = String(req.headers['x-writedock-nonce'] || '')
+      const time = String(req.headers['x-writedock-time'] || '')
+      const signature = String(req.headers['x-writedock-proof'] || '')
+      const now = Date.now()
+      if (!/^[a-f0-9]{64}$/.test(nonce) || !/^\d+$/.test(time) || Math.abs(now - Number(time)) > 15_000 || this.seenNonces.has(nonce) || !equal(signature, requestProof(this.options.token, req.method || '', req.url || '', nonce, time, body))) {
+        send(403, { error: '本地桥接认证失败，请检查连接密钥和端口' }); return
+      }
+      for (const [key, expires] of this.seenNonces) if (expires < now) this.seenNonces.delete(key)
+      this.seenNonces.set(nonce, now + 30_000)
+      responseNonce = nonce
+      if (req.method === 'GET' && req.url === '/status') {
+        send(200, { connected: this.client?.readyState === WebSocket.OPEN, extensionId: this.extensionId, protocol: 'writedock/1', pairing_available: true, ...mcpReleaseInfo() }); return
+      }
+      if (req.method === 'POST' && req.url === '/pairing') { send(200, await this.beginPairing()); return }
+      if (req.method === 'POST' && req.url === '/assets/register') {
+        const input = JSON.parse(body)
+        if (typeof input.path !== 'string' || !['image', 'video'].includes(input.kind)) throw new Error('素材参数不正确')
+        send(200, await this.media.register(input.path, input.kind)); return
+      }
+      if (req.method !== 'POST' || req.url !== '/request') { send(404, { error: 'Not found' }); return }
+      const input = JSON.parse(body)
+      if (typeof input.method !== 'string' || !input.params || typeof input.params !== 'object' || Array.isArray(input.params)) throw new Error('无效的桥接请求')
+      const result = await this.requestConnected(input.method, input.params)
+      send(200, { result })
+    } catch (error) { send(400, { error: messageOf(error) }) }
+  }
+
+  private async httpCall(path: string, body?: unknown): Promise<Record<string, unknown>> {
+    const nonce = randomBytes(32).toString('hex'), time = String(Date.now())
+    const method = body === undefined ? 'GET' : 'POST'
+    const requestBody = body === undefined ? '' : JSON.stringify(body)
+    const response = await fetch(`http://127.0.0.1:${this.port}${path}`, {
+      method,
+      headers: { 'X-Writedock-Nonce': nonce, 'X-Writedock-Time': time, 'X-Writedock-Proof': requestProof(this.options.token, method, path, nonce, time, requestBody), 'Content-Type': 'application/json' },
+      ...(body === undefined ? {} : { body: requestBody }),
+      signal: AbortSignal.timeout(this.options.timeoutMs ?? 55_000),
+    })
+    const text = await response.text()
+    if (!equal(response.headers.get('x-writedock-proof') || '', proof(this.options.token, `http-response:${digest(text)}`, nonce))) throw new Error('本地桥接认证失败，请检查连接密钥和端口')
+    const data = JSON.parse(text) as Record<string, unknown>
+    if (!response.ok) throw new Error(String(data.error || `本地桥接 HTTP ${response.status}`))
+    return data
+  }
+
+  async status() {
+    await this.start()
+    if (this.primary) return { connected: this.client?.readyState === WebSocket.OPEN, extensionId: this.extensionId, protocol: 'writedock/1', pairing_available: true, ...mcpReleaseInfo() }
+    try { return await this.httpCall('/status') }
+    catch (error) {
+      if (!(error instanceof TypeError)) throw error
+      // Read-only health checks can acquire the vacant port after another MCP client exits.
+      this.starting = undefined
+      await this.start()
+      if (this.primary) return { connected: false, protocol: 'writedock/1', pairing_available: true, ...mcpReleaseInfo() }
+      throw error
+    }
+  }
+
+  async request<T = unknown>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+    await this.start()
+    if (this.primary) return this.requestConnected(method, params) as Promise<T>
+    try { return (await this.httpCall('/request', { method, params })).result as T }
+    catch (error) {
+      // Never retry a submitted request. A later tool call may acquire the port after its owner exits.
+      if (error instanceof TypeError) this.starting = undefined
+      throw error
+    }
+  }
+
+  async registerMedia(path: string, kind: 'image' | 'video'): Promise<MediaAsset> {
+    await this.status()
+    if (this.primary) return this.media.register(path, kind)
+    return await this.httpCall('/assets/register', { path, kind }) as unknown as MediaAsset
+  }
+
+  private async requestConnected(method: string, params: Record<string, unknown>): Promise<unknown> {
+    if (this.client?.readyState !== WebSocket.OPEN) throw new Error('扩展未连接。请调用 begin_pairing，将一次性配对码粘贴到扩展的 MCP 连接页；无需重装 MCP。')
+    const id = randomUUID()
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        reject(new Error('扩展响应超时；同步任务可能仍在运行，请查询任务状态。'))
+      }, this.options.timeoutMs ?? 55_000)
+      this.pending.set(id, { resolve, reject, timer })
+      this.client!.send(JSON.stringify({ id, method, params }), error => {
+        if (!error) return
+        clearTimeout(timer); this.pending.delete(id); reject(error)
+      })
+    })
+  }
+
+  async close() {
+    this.pairing = undefined
+    clearInterval(this.heartbeat)
+    for (const value of this.pending.values()) { clearTimeout(value.timer); value.reject(new Error('MCP 服务已关闭')) }
+    this.pending.clear()
+    for (const ws of this.sockets?.clients || []) ws.terminate()
+    this.sockets?.close()
+    if (this.server?.listening) await new Promise<void>(resolve => this.server!.close(() => resolve()))
+    this.primary = false; this.starting = undefined
+  }
+}