writedock-mcp 0.4.4 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "writedock-mcp",
-  "version": "0.4.4",
+  "version": "0.4.7",
   "description": "WriteDock local MCP server for the browser extension",
   "type": "commonjs",
   "license": "GPL-3.0-only",
@@ -17,7 +17,8 @@
     "LICENSE-MULTIPOST",
     "NOTICE.md",
     "THIRD_PARTY_NOTICES.txt",
-    "source"
+    "source",
+    "extension"
   ],
   "keywords": [
     "mcp",

package/source/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedock/mcp-server",
-  "version": "0.4.4",
+  "version": "0.4.7",
   "private": true,
   "type": "module",
   "description": "WriteDock local MCP server for the browser extension",

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

@@ -2,7 +2,9 @@ import { afterEach, describe, expect, it } from 'vitest'
 import { createServer } from 'node:net'
 import { once } from 'node:events'
 import { randomBytes } from 'node:crypto'
+import http from 'node:http'
 import { WebSocket } from 'ws'
+import { EXTENSION_ORIGIN } from '../extension-id'
 import { LocalBridge, proof, requestProof } from '../bridge'
 
 const token = 'test-pairing-key-that-is-long-enough'
@@ -31,6 +33,26 @@ async function pair(bridge: LocalBridge, key = token) {
 afterEach(async () => { clients.splice(0).forEach(ws => ws.terminate()); await Promise.all(brokers.splice(0).map(value => value.close())) })
 
 describe('authenticated local bridge', () => {
+  it('answers discovery and one-click connection only for the fixed extension origin', async () => {
+    const bridge = await broker()
+    const hello = (origin?: string) => new Promise<number>((resolve, reject) => { const req = http.get({ host: '127.0.0.1', port: bridge.port, path: '/hello', headers: origin ? { Origin: origin } : {} }, res => { res.resume(); resolve(res.statusCode!) }); req.on('error', reject) })
+    expect(await hello(EXTENSION_ORIGIN)).toBe(200)
+    expect(await hello()).toBe(200)
+    expect(await hello('https://example.com')).not.toBe(200)
+    expect(await hello('chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).not.toBe(200)
+    const open = (origin: string) => new Promise<{ code?: number; message?: Record<string, unknown> }>(resolve => {
+      const ws = new WebSocket(`ws://127.0.0.1:${bridge.port}/connect`, { origin })
+      ws.on('message', raw => resolve({ message: JSON.parse(raw.toString()) }))
+      ws.on('unexpected-response', (_req, res) => resolve({ code: res.statusCode }))
+      ws.on('error', () => {})
+    })
+    expect((await open('chrome-extension://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).code).toBe(403)
+    expect((await open('https://example.com')).code).toBe(403)
+    const connected = await open(EXTENSION_ORIGIN)
+    expect(connected.message).toMatchObject({ type: 'connect_result', port: bridge.port, protocol: 'writedock/1' })
+    expect(String(connected.message?.token)).toMatch(/^[a-f0-9]{64}$/)
+  })
+
   it('rejects unauthenticated HTTP calls and browser-origin requests', async () => {
     const bridge = await broker()
     const url = `http://127.0.0.1:${bridge.port}/status`

package/source/src/__tests__/extension-update.test.ts

@@ -0,0 +1,54 @@
+import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { bundledExtension, findInstalledExtension, installExtensionFiles } from '../extension-update'
+
+const manifest = (version: string, extra: Record<string, unknown> = {}) => JSON.stringify({ name: '写作台 WriteDock', version, key: 'fixed-key', ...extra })
+
+describe('extension update', () => {
+  let work: string, source: string, target: string
+  beforeEach(async () => {
+    work = await mkdtemp(join(tmpdir(), 'writedock-ext-'))
+    source = join(work, 'bundle/extension'); target = join(work, 'installed')
+    await mkdir(source, { recursive: true })
+    await writeFile(join(source, 'manifest.json'), manifest('2.0.0'))
+    await writeFile(join(source, 'worker.js'), 'new')
+  })
+  afterEach(() => rm(work, { recursive: true, force: true }))
+
+  it('installs into an empty folder, then overwrites in place keeping files still in use', async () => {
+    expect(await installExtensionFiles(source, target)).toMatchObject({ version: '2.0.0' })
+    expect(await readFile(join(target, 'worker.js'), 'utf8')).toBe('new')
+    await writeFile(join(target, 'old-hashed.js'), 'still used until reload')
+    await writeFile(join(target, 'manifest.json'), manifest('1.0.0'))
+    await installExtensionFiles(source, target)
+    expect(JSON.parse(await readFile(join(target, 'manifest.json'), 'utf8')).version).toBe('2.0.0')
+    expect(await readFile(join(target, 'old-hashed.js'), 'utf8')).toBe('still used until reload')
+  })
+
+  it('refuses another extension or a different identity, and leaves the folder alone', async () => {
+    await mkdir(target)
+    await writeFile(join(target, 'manifest.json'), JSON.stringify({ name: 'Other', version: '1.0.0' }))
+    await expect(installExtensionFiles(source, target)).rejects.toThrow('不是 WriteDock')
+    expect(JSON.parse(await readFile(join(target, 'manifest.json'), 'utf8')).name).toBe('Other')
+    await writeFile(join(target, 'manifest.json'), manifest('1.0.0', { key: 'other-key' }))
+    await expect(installExtensionFiles(source, target)).rejects.toThrow('身份不同')
+    expect(JSON.parse(await readFile(join(target, 'manifest.json'), 'utf8')).version).toBe('1.0.0')
+  })
+
+  it('finds the loaded folder by extension ID and ignores others', async () => {
+    await installExtensionFiles(source, target)
+    const browser = join(work, 'browser')
+    await mkdir(join(browser, 'Default'), { recursive: true })
+    await writeFile(join(browser, 'Default/Preferences'), JSON.stringify({ extensions: { settings: { other: { path: join(work, 'nope') }, theid: { path: target } } } }))
+    expect(await findInstalledExtension([browser], 'theid')).toBe(await realpath(target))
+    expect(await findInstalledExtension([browser], 'missing')).toBeUndefined()
+    expect(await findInstalledExtension([join(work, 'no-browser')], 'theid')).toBeUndefined()
+  })
+
+  it('reads the bundled version, and reports none from a source checkout', () => {
+    expect(bundledExtension(join(work, 'bundle'))).toMatchObject({ version: '2.0.0' })
+    expect(bundledExtension(work)).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,50 @@
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { runSetup } from '../setup'
+
+describe('setup', () => {
+  let home: string
+  const log: string[] = []
+  beforeEach(async () => { home = await mkdtemp(join(tmpdir(), 'writedock-setup-')); log.length = 0 })
+  afterEach(() => rm(home, { recursive: true, force: true }))
+
+  it('adds WriteDock to Codex and keeps the rest of the file, with a backup', async () => {
+    await mkdir(join(home, '.codex'))
+    const original = 'model = "x"\n\n[mcp_servers.other]\ncommand = "other"\n'
+    await writeFile(join(home, '.codex/config.toml'), original)
+    expect(await runSetup(home, line => log.push(line))).toBe(1)
+    const result = await readFile(join(home, '.codex/config.toml'), 'utf8')
+    expect(result.startsWith(original.trimEnd())).toBe(true)
+    expect(result).toContain('[mcp_servers.writedock]')
+    expect(result).toContain('"writedock-mcp@latest"')
+    expect(await readFile(join(home, '.codex/config.toml.writedock-backup'), 'utf8')).toBe(original)
+  })
+
+  it('leaves an existing entry alone, including its custom port and token', async () => {
+    await mkdir(join(home, '.codex'))
+    const original = '[mcp_servers.writedock]\ncommand = "node"\n\n[mcp_servers.writedock.env]\nWRITEDOCK_PORT = "9700"\n'
+    await writeFile(join(home, '.codex/config.toml'), original)
+    await runSetup(home, line => log.push(line))
+    expect(await readFile(join(home, '.codex/config.toml'), 'utf8')).toBe(original)
+    expect(log.join()).toContain('未改动')
+  })
+
+  it('merges JSON clients, and reports a broken file without changing it', async () => {
+    await writeFile(join(home, '.claude.json'), JSON.stringify({ theme: 'dark', mcpServers: { other: { command: 'x' } } }))
+    await mkdir(join(home, '.cursor'))
+    await writeFile(join(home, '.cursor/mcp.json'), '{ broken')
+    await runSetup(home, line => log.push(line))
+    const claude = JSON.parse(await readFile(join(home, '.claude.json'), 'utf8'))
+    expect(claude.theme).toBe('dark')
+    expect(Object.keys(claude.mcpServers).sort()).toEqual(['other', 'writedock'])
+    expect(await readFile(join(home, '.cursor/mcp.json'), 'utf8')).toBe('{ broken')
+    expect(log.join()).toContain('配置失败')
+  })
+
+  it('touches nothing when no client exists, and prints the configuration', async () => {
+    expect(await runSetup(home, line => log.push(line))).toBe(0)
+    expect(log.join()).toContain('writedock-mcp@latest')
+  })
+})

package/source/src/bridge.ts

@@ -1,11 +1,13 @@
 /** Local bridge, based on Wechatsync's stdio → WebSocket architecture (MIT).
- * WriteDock uses one loopback port, authenticated forwarding and mutual HMAC pairing.
+ * WriteDock uses one loopback port, authenticated forwarding and an HMAC handshake.
  */
 import http from 'node:http'
-import { createCipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
 import { WebSocket, WebSocketServer } from 'ws'
 import { MediaStore, type MediaAsset } from './media'
 import { mcpReleaseInfo } from './release-info'
+import { EXTENSION_ORIGIN } from './extension-id'
+import { updateInstalledExtension } from './extension-update'
 
 const LIMIT = 32 * 1024 * 1024
 const messageOf = (error: unknown) => error instanceof Error ? error.message : String(error)
@@ -26,7 +28,6 @@ export class LocalBridge {
   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> }>()
@@ -45,7 +46,7 @@ export class LocalBridge {
       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.
+      // Only attach to a broker that proves it holds this key.
       await this.httpCall('/status')
     }).catch(error => { this.starting = undefined; throw error })
     return this.starting
@@ -59,10 +60,10 @@ export class LocalBridge {
     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)) {
+      if (!this.validHost(req.headers.host) || !['/extension', '/connect'].includes(req.url || '') || (origin && !extensionOrigin) || (req.url === '/connect' && origin !== EXTENSION_ORIGIN)) {
         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) })
+      sockets.handleUpgrade(req, socket, head, ws => { if (req.url === '/connect') void this.acceptConnect(ws); else this.accept(ws) })
     })
     await new Promise<void>((resolve, reject) => {
       server.once('error', reject)
@@ -79,69 +80,40 @@ export class LocalBridge {
 
   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 配置。确认用户要连接当前扩展后再生成。' }
+  /** Replaces the extension credential and drops whatever was using the old one. */
+  private async replaceExtensionToken(reason: string) {
+    const token = randomBytes(32).toString('hex')
+    await this.options.credentials?.setExtensionToken(token)
+    this.extensionToken = token
+    const previousClient = this.client
+    this.client = undefined; this.extensionId = undefined
+    for (const value of this.pending.values()) { clearTimeout(value.timer); value.reject(new Error(reason)) }
+    this.pending.clear()
+    previousClient?.close(1000, 'Extension connection replaced')
+    return token
   }
 
-  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', () => {})
+  /** One-click connection: only this extension's fixed origin can reach here, and the user has just clicked 连接. */
+  private async acceptConnect(ws: WebSocket) {
+    try {
+      const token = await this.replaceExtensionToken('扩展连接已更换；请查询原同步任务，不要自动重新提交。')
+      ws.send(JSON.stringify({ type: 'connect_result', token, port: this.port, protocol: 'writedock/1' }))
+      ws.close(1000)
+    } catch { ws.close(1011, 'Connect failed') }
   }
 
   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)
+    const timer = setTimeout(() => ws.close(1008, 'Handshake 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
+            ws.close(1008, 'Handshake failed'); return
           }
           if (this.client?.readyState === WebSocket.OPEN) { ws.close(1008, 'An extension is already connected'); return }
           authenticated = true; clearTimeout(timer)
@@ -150,6 +122,13 @@ export class LocalBridge {
           return
         }
         if (message.type === 'pong') return
+        if (message.type === 'update_extension') {
+          void updateInstalledExtension().then(
+            result => ws.send(JSON.stringify({ type: 'update_extension_result', ok: true, version: result.version })),
+            error => ws.send(JSON.stringify({ type: 'update_extension_result', ok: false, error: messageOf(error) })),
+          )
+          return
+        }
         const pending = this.pending.get(message.id)
         if (!pending) return
         this.pending.delete(message.id); clearTimeout(pending.timer)
@@ -179,6 +158,11 @@ export class LocalBridge {
       if (responseNonce) res.setHeader('X-Writedock-Proof', proof(this.options.token, `http-response:${digest(body)}`, responseNonce))
       res.writeHead(status); res.end(body)
     }
+    // Lets the extension find this service before it is connected. Reveals only that it exists and its version.
+    // Chrome omits Origin on GETs from an extension with host permission; web pages always send theirs.
+    if (req.url === '/hello' && req.method === 'GET' && this.validHost(req.headers.host) && (!req.headers.origin || req.headers.origin === EXTENSION_ORIGIN)) {
+      send(200, { service: 'writedock-mcp', protocol: 'writedock/1', version: mcpReleaseInfo().mcp_version }); return
+    }
     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
@@ -205,9 +189,8 @@ export class LocalBridge {
       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
+        send(200, { connected: this.client?.readyState === WebSocket.OPEN, extensionId: this.extensionId, protocol: 'writedock/1', ...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('素材参数不正确')
@@ -240,14 +223,14 @@ export class LocalBridge {
 
   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() }
+    if (this.primary) return { connected: this.client?.readyState === WebSocket.OPEN, extensionId: this.extensionId, protocol: 'writedock/1', ...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() }
+      if (this.primary) return { connected: false, protocol: 'writedock/1', ...mcpReleaseInfo() }
       throw error
     }
   }
@@ -270,7 +253,7 @@ export class LocalBridge {
   }
 
   private async requestConnected(method: string, params: Record<string, unknown>): Promise<unknown> {
-    if (this.client?.readyState !== WebSocket.OPEN) throw new Error('扩展未连接。请调用 begin_pairing，将一次性配对码粘贴到扩展的 MCP 连接页；无需重装 MCP。')
+    if (this.client?.readyState !== WebSocket.OPEN) throw new Error('扩展未连接。请让用户打开浏览器的 WriteDock 扩展，在「连接」页点“连接”。无需重装 MCP。')
     const id = randomUUID()
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -286,7 +269,6 @@ export class LocalBridge {
   }
 
   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()

package/source/src/extension-id.ts

@@ -0,0 +1,2 @@
+/** Derived from the public key in packages/extension/manifest.json, so the ID does not depend on the install folder. */
+export const EXTENSION_ORIGIN = 'chrome-extension://himncajjeipncfpoajkcmfieonfpjfhb'

package/source/src/extension-update.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from 'node:fs'
+import { cp, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { EXTENSION_ORIGIN } from './extension-id'
+
+const EXTENSION_ID = EXTENSION_ORIGIN.replace('chrome-extension://', '')
+const readManifest = async (directory: string) => JSON.parse(await readFile(join(directory, 'manifest.json'), 'utf8')) as { name?: string; version?: string; key?: string }
+const isWriteDock = (manifest: { name?: string; manifest_version?: number }) => manifest.name === '写作台 WriteDock'
+
+/** The extension shipped inside this npm package. Absent when running from a source checkout. */
+export function bundledExtension(base = __dirname) {
+  try {
+    const directory = join(base, 'extension')
+    const manifest = JSON.parse(readFileSync(join(directory, 'manifest.json'), 'utf8')) as { version?: string }
+    return typeof manifest.version === 'string' ? { directory, version: manifest.version } : undefined
+  } catch { return undefined }
+}
+
+/** Where setup installs the extension: stable, and visible in the browser's folder picker, which hides ~/Library on macOS. */
+export const defaultExtensionDirectory = (home = homedir()) => join(home, 'WriteDock', 'extension')
+
+function browserRoots(user = homedir()) {
+  const names = process.platform === 'win32'
+    ? ['Google/Chrome/User Data', 'Microsoft/Edge/User Data', 'Chromium/User Data', 'BraveSoftware/Brave-Browser/User Data'].map(name => join(process.env.LOCALAPPDATA || join(user, 'AppData/Local'), name))
+    : process.platform === 'darwin'
+      ? ['Google/Chrome', 'Microsoft Edge', 'Chromium', 'BraveSoftware/Brave-Browser'].map(name => join(user, 'Library/Application Support', name))
+      : ['google-chrome', 'microsoft-edge', 'chromium', 'BraveSoftware/Brave-Browser'].map(name => join(process.env.XDG_CONFIG_HOME || join(user, '.config'), name))
+  return names
+}
+
+/** Finds the folder the browser actually loaded this extension from, by its fixed ID. */
+export async function findInstalledExtension(roots = browserRoots(), id = EXTENSION_ID) {
+  for (const root of roots) {
+    let profiles: { name: string; isDirectory: () => boolean }[]
+    try { profiles = await readdir(root, { withFileTypes: true }) } catch { continue }
+    for (const profile of profiles.filter(item => item.isDirectory() && /^(Default|Profile \d+)$/.test(item.name))) {
+      for (const filename of ['Secure Preferences', 'Preferences']) {
+        try {
+          const preferences = JSON.parse(await readFile(join(root, profile.name, filename), 'utf8'))
+          const path = preferences.extensions?.settings?.[id]?.path
+          if (typeof path === 'string' && isAbsolute(path) && isWriteDock(await readManifest(path))) return realpath(path)
+        } catch { /* Missing or unreadable profile. */ }
+      }
+    }
+  }
+  return undefined
+}
+
+/** Overwrites in place, manifest last, restoring the previous files if anything fails. */
+export async function installExtensionFiles(source: string, target: string) {
+  const next = await readManifest(source)
+  if (!isWriteDock(next)) throw new Error('内置扩展文件不正确')
+  let previous: Awaited<ReturnType<typeof readManifest>> | undefined
+  try { previous = await readManifest(target) } catch { /* A first install. */ }
+  if (previous) {
+    if (!isWriteDock(previous)) throw new Error('目标目录不是 WriteDock 扩展，未覆盖')
+    if (previous.key !== next.key) throw new Error('旧版扩展的身份不同，无法原位更新，请重新加载一次新版')
+  }
+  await mkdir(target, { recursive: true })
+  const backup = previous ? await mkdtemp(join(tmpdir(), 'writedock-extension-backup-')) : undefined
+  if (backup) await cp(target, backup, { recursive: true, force: true })
+  try {
+    await cp(source, target, { recursive: true, force: true, filter: path => path !== join(source, 'manifest.json') })
+    const staged = join(target, '.writedock-manifest-update.tmp')
+    await writeFile(staged, await readFile(join(source, 'manifest.json')))
+    await rename(staged, join(target, 'manifest.json'))
+  } catch (error) {
+    if (backup) await cp(backup, target, { recursive: true, force: true })
+    throw error
+  } finally { if (backup) await rm(backup, { recursive: true, force: true }).catch(() => {}) }
+  return { directory: target, version: next.version }
+}
+
+/** Handles the 更新 button in the extension. */
+export async function updateInstalledExtension() {
+  const bundle = bundledExtension()
+  if (!bundle) throw new Error('当前服务没有内置扩展，请重启 agent 后再试')
+  const target = await findInstalledExtension()
+  if (!target) throw new Error('没有找到已加载的扩展目录，请手动更新')
+  return installExtensionFiles(bundle.directory, target)
+}

package/source/src/identity.ts

@@ -20,7 +20,7 @@ export async function loadIdentity(port: number, legacyToken?: string) {
   const filename = join(directory, `identity-${port}.json`)
   const read = async (): Promise<Identity> => {
     const value = JSON.parse(await readFile(filename, 'utf8'))
-    if (value.version !== 1 || !validToken(value.token) || !validToken(value.extensionToken)) throw new Error('MCP 配对资料格式不正确；请保留原文件并检查备份，不会自动覆盖')
+    if (value.version !== 1 || !validToken(value.token) || !validToken(value.extensionToken)) throw new Error('MCP 连接资料格式不正确；请保留原文件并检查备份，不会自动覆盖')
     return value
   }
   let identity: Identity
@@ -43,7 +43,7 @@ export async function loadIdentity(port: number, legacyToken?: string) {
     token: identity.token,
     getExtensionToken: async () => (await read()).extensionToken,
     setExtensionToken: async (extensionToken: string) => {
-      if (!validToken(extensionToken)) throw new Error('扩展配对密钥格式不正确')
+      if (!validToken(extensionToken)) throw new Error('扩展连接密钥格式不正确')
       const current = await read()
       if (current.token !== identity.token) throw new Error('MCP 身份已变化，请重新启动服务')
       const temporary = join(directory, `.identity-${randomUUID()}.tmp`)

package/source/src/index.ts

@@ -4,6 +4,7 @@ import { LocalBridge } from './bridge'
 import { createMcpServer } from './server'
 import { loadIdentity } from './identity'
 import mcpPackage from '../package.json'
+import { runSetup } from './setup'
 
 async function main() {
   const port = Number(process.env.WRITEDOCK_PORT || 9647)
@@ -22,6 +23,8 @@ async function main() {
 if (process.argv.slice(2).some(argument => argument === '--version' || argument === '-v')) {
   // Allow inspecting an npm archive without starting a bridge or reading pairing credentials.
   console.log(mcpPackage.version)
+} else if (process.argv[2] === 'setup') {
+  runSetup().catch(error => { console.error('[WriteDock MCP]', error instanceof Error ? error.message : String(error)); process.exit(1) })
 } else {
   main().catch(error => { console.error('[WriteDock MCP]', error instanceof Error ? error.message : String(error)); process.exit(1) })
 }

package/source/src/release-info.ts

@@ -1,5 +1,6 @@
 import mcpPackage from '../package.json'
 import distribution from '../distribution.json'
+import { bundledExtension } from './extension-update'
 
 const CHECK_INTERVAL = 6 * 60 * 60_000
 const RETRY_INTERVAL = 10 * 60_000
@@ -56,8 +57,10 @@ function refresh() {
 /** Check asynchronously; version lookup must never delay pairing, tool calls or publication. */
 export function mcpReleaseInfo() {
   refresh()
+  const bundle = bundledExtension()
   return {
     mcp_version: mcpPackage.version,
+    ...(bundle ? { extension_bundle_version: bundle.version } : {}),
     ...(latestVersion ? { latest_version: latestVersion } : {}),
     update_available: !!latestVersion && newerVersion(latestVersion, mcpPackage.version),
     ...(checkedAt ? { update_checked_at: checkedAt } : {}),

package/source/src/server.ts

@@ -30,7 +30,7 @@ const agentWorkflow = 'Agent 只通过 WriteDock MCP 投稿和查询回执，不
 
 export function createMcpServer(bridge: LocalBridge) {
   const server = new McpServer({ name: 'writedock', version: mcpPackage.version }, {
-    instructions: agentWorkflow + 'WriteDock 通过本机扩展执行投稿。先检查连接和平台登录。实际平台能力以 list_platforms 返回的 action、publishModes、tools、modeOptions、confirmation、capabilities、coverRequired 为准，扩展更新后优先按该元信息选择工具。知乎、百家号、微博长文章、B站专栏、小红书长文使用 publish_article，Agent 直接提供 Markdown/HTML 或文件路径即可发布，无需用户在扩展编辑。百家号必须提供 cover 封面；知乎另支持 <video src="本地MP4路径"></video> 文章内视频，独立封面暂未接入。prepare_article 仅供可选本机预览，不是发布的前置要求。小红书 ID 为 xiaohongshu，三种模式共用此平台：写长文用 publish_article，支持正文图片、原生自动排版后发布，标题最多 64 字、正文最多 10000 字，不接独立 cover 或文章内视频；普通图文用 publish_post(kind=image)，独立视频用 publish_post(kind=video)，未传 cover_path 时保留平台自动生成的第一帧封面。小红书最终均须匹配 POST /web_api/sns/v2/note 的 success=true、result=0 和笔记 ID 回执才确认 submitted。抖音平台 ID 为 douyin，图文和视频同样用 publish_post(kind=image|video)，可选 cover_path；图文话题最多 4 个、视频最多 5 个，当前只接即时发布。抖音 confirmation=native_page_message，以本次操作新增的原生成功提示确认 submitted，未核对最终 HTTP 业务回执；仅跳转作品管理时仍为 unknown，Agent 不自动重发。小红书、抖音、微博普通图文与独立视频使用 prepare_post / publish_post，微博平台 ID 仍为 weibo，不另建平台。微博图文标题放入正文首行，最多 18 张图片；独立视频标题最多 30 个汉字（60 个半角字符），weibo_video_creation 必填，须依据用户实际内容传 original、secondary 或 repost，不能默认原创。微博同一次只能选图文或视频，长文章继续用 publish_article。只有用户明确要求发布并指定平台时才调用发布工具。微信公众号、搜狐号目前用 sync_article 保存文章草稿。B站专栏 ID 为 bilibili，使用 publish_article 直接发布文字和正文图片，不接视频、音频、附加内容卡片或独立封面；通过新版原生编辑器上传并发布，code=-352 时停止自动提交并转人工验证。遇到 needs_user_action 或 requires_user_action 时，把 user_actions 中的原因和稿件链接告诉用户，优先让用户切换到扩展已打开的页面处理验证码、封面、内容声明、来源、原创协议或发布设置，并手动发布；不得自动解决验证码、重新提交或换 request_id。该状态只记录人工接管，不代表用户之后的操作结果已被确认。扩展更新复用已有 MCP；需要恢复连接时调用 begin_pairing，让用户在扩展输入配对码。提交返回任务 ID，随后用 get_sync_task 查询结果。保持同一操作的 request_id 不变。publicationState=unknown 或任务中断时，向用户给出链接让其自行核对平台，Agent 不打开网页，不要自动生成新 request_id 重发。直接发布成功表示平台已接受提交，是否公开展示以平台为准。',
+    instructions: agentWorkflow + 'WriteDock 通过本机扩展执行投稿。先检查连接和平台登录。实际平台能力以 list_platforms 返回的 action、publishModes、tools、modeOptions、confirmation、capabilities、coverRequired 为准，扩展更新后优先按该元信息选择工具。知乎、百家号、微博长文章、B站专栏、小红书长文使用 publish_article，Agent 直接提供 Markdown/HTML 或文件路径即可发布，无需用户在扩展编辑。百家号必须提供 cover 封面；知乎另支持 <video src="本地MP4路径"></video> 文章内视频，独立封面暂未接入。prepare_article 仅供可选本机预览，不是发布的前置要求。小红书 ID 为 xiaohongshu，三种模式共用此平台：写长文用 publish_article，支持正文图片、原生自动排版后发布，标题最多 64 字、正文最多 10000 字，不接独立 cover 或文章内视频；普通图文用 publish_post(kind=image)，独立视频用 publish_post(kind=video)，未传 cover_path 时保留平台自动生成的第一帧封面。小红书最终均须匹配 POST /web_api/sns/v2/note 的 success=true、result=0 和笔记 ID 回执才确认 submitted。抖音平台 ID 为 douyin，图文和视频同样用 publish_post(kind=image|video)，可选 cover_path；图文话题最多 4 个、视频最多 5 个，当前只接即时发布。抖音 confirmation=native_page_message，以本次操作新增的原生成功提示确认 submitted，未核对最终 HTTP 业务回执；仅跳转作品管理时仍为 unknown，Agent 不自动重发。小红书、抖音、微博普通图文与独立视频使用 prepare_post / publish_post，微博平台 ID 仍为 weibo，不另建平台。微博图文标题放入正文首行，最多 18 张图片；独立视频标题最多 30 个汉字（60 个半角字符），weibo_video_creation 必填，须依据用户实际内容传 original、secondary 或 repost，不能默认原创。微博同一次只能选图文或视频，长文章继续用 publish_article。只有用户明确要求发布并指定平台时才调用发布工具。微信公众号、搜狐号目前用 sync_article 保存文章草稿。B站专栏 ID 为 bilibili，使用 publish_article 直接发布文字和正文图片，不接视频、音频、附加内容卡片或独立封面；通过新版原生编辑器上传并发布，code=-352 时停止自动提交并转人工验证。遇到 needs_user_action 或 requires_user_action 时，把 user_actions 中的原因和稿件链接告诉用户，优先让用户切换到扩展已打开的页面处理验证码、封面、内容声明、来源、原创协议或发布设置，并手动发布；不得自动解决验证码、重新提交或换 request_id。该状态只记录人工接管，不代表用户之后的操作结果已被确认。扩展更新复用已有 MCP；未连接时，让用户打开 WriteDock 扩展的「连接」页点“连接”。提交返回任务 ID，随后用 get_sync_task 查询结果。保持同一操作的 request_id 不变。publicationState=unknown 或任务中断时，向用户给出链接让其自行核对平台，Agent 不打开网页，不要自动生成新 request_id 重发。直接发布成功表示平台已接受提交，是否公开展示以平台为准。',
   })
   const wrap = (operation: () => Promise<unknown>) => operation().then(result => ({
     content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
@@ -38,12 +38,8 @@ export function createMcpServer(bridge: LocalBridge) {
   const readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
 
   server.registerTool('get_connection_status', {
-    description: '检查本机 MCP 与扩展的连接、运行版本和 npm 更新提示。update_available=true 时告知用户重新启动 WriteDock MCP，保留配置和配对；发布任务进行中不要自动重启。旧版服务可能不返回版本字段；latest_version 缺失或 update_checking=true 时，不得声称已是最新版。', inputSchema: {}, annotations: { ...readOnly, openWorldHint: true },
+    description: '检查本机 MCP 与扩展的连接、运行版本和 npm 更新提示。update_available=true 时告知用户重新启动 WriteDock MCP，保留配置；发布任务进行中不要自动重启。旧版服务可能不返回版本字段；latest_version 缺失或 update_checking=true 时，不得声称已是最新版。', inputSchema: {}, annotations: { ...readOnly, openWorldHint: true },
   }, () => wrap(() => bridge.status()))
-  server.registerTool('begin_pairing', {
-    description: '首次连接或扩展卸载重装后，生成 3 分钟有效的一次性配对码。让用户粘贴到扩展的 MCP 连接页即可，复用已有 MCP 和 agent 配置。新配对会替换此前浏览器的连接授权，请在用户要求连接扩展时调用。',
-    inputSchema: {}, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
-  }, () => wrap(() => bridge.beginPairing()))
   server.registerTool('list_platforms', {
     description: '列出扩展实际支持的平台、登录状态、publishModes、对应 tools 及 modeOptions 限制；小红书 article 对应 publish_article，image/video 对应 publish_post。不会返回 Cookie。',
     inputSchema: { force_refresh: z.boolean().optional() }, annotations: { ...readOnly, openWorldHint: true },