foxcode-channel 0.1.0

package/lib.mjs

@@ -0,0 +1,159 @@
+/**
+ * FoxCode — Channel plugin shared logic.
+ * Pure functions and protocol definitions, testable without MCP/WebSocket.
+ */
+
+/**
+ * Sequence counter for message IDs.
+ * Exposed as object so tests can reset it.
+ */
+export const state = { seq: 0 }
+
+/** Generate a unique message ID. */
+export function nextId() {
+  return `m${Date.now()}-${++state.seq}`
+}
+
+/**
+ * Build channel notification metadata from an extension message.
+ * @param {object} msg - Extension message with id, tab?, text
+ * @returns {{content: string, meta: object}}
+ */
+export function buildChannelMeta(msg) {
+  const id = msg.id || nextId()
+  const meta = { chat_id: 'web', message_id: id, user: 'web', ts: new Date().toISOString() }
+  if (msg.tab?.url) meta.tab_url = msg.tab.url
+  if (msg.tab?.title) meta.tab_title = msg.tab.title
+  return { content: msg.text, meta }
+}
+
+/**
+ * Build a reply broadcast message for the extension.
+ * @param {string} text - Reply text
+ * @param {string} [replyTo] - Message ID to reply to
+ * @returns {object}
+ */
+export function buildReplyMessage(text, replyTo) {
+  const id = nextId()
+  return { type: 'msg', id, from: 'assistant', text, ts: Date.now(), replyTo }
+}
+
+/**
+ * Build an edit broadcast message.
+ * @param {string} messageId
+ * @param {string} text
+ * @returns {object}
+ */
+export function buildEditMessage(messageId, text) {
+  return { type: 'edit', id: messageId, text }
+}
+
+/**
+ * Build a tool_use broadcast message.
+ * @param {string} tool
+ * @param {object} params
+ * @returns {object}
+ */
+export function buildToolUseMessage(tool, params) {
+  const id = nextId()
+  return { type: 'tool_use', id, tool, params, ts: Date.now() }
+}
+
+/**
+ * Build a tool_result broadcast message.
+ * @param {string} tool
+ * @param {string} content
+ * @returns {object}
+ */
+export function buildToolResultMessage(tool, content) {
+  const id = nextId()
+  return { type: 'tool_result', id, tool, content, ts: Date.now() }
+}
+
+/**
+ * MCP tool definitions exposed by the channel plugin.
+ */
+export const TOOL_DEFINITIONS = [
+  {
+    name: 'reply',
+    description: 'Send a message to the Firefox browser sidebar.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'Message text' },
+        reply_to: { type: 'string', description: 'Message ID to reply to (optional)' },
+      },
+      required: ['text'],
+    },
+  },
+  {
+    name: 'edit_message',
+    description: 'Edit a previously sent message in the browser sidebar.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message_id: { type: 'string', description: 'ID of the message to edit' },
+        text: { type: 'string', description: 'New message text' },
+      },
+      required: ['message_id', 'text'],
+    },
+  },
+  {
+    name: 'evalInBrowser',
+    description: [
+      'Execute JavaScript in Firefox browser. Code runs in extension background with async browser API.',
+      'Multi-page workflows supported (survives navigation).',
+      'navigate() automatically opens a new tab for agent work (preserves user\'s active tab).',
+      'Subsequent operations target this managed tab. closeTab() without args closes it;',
+      'next navigate() creates a fresh tab.',
+      '',
+      'Usage: write JS code using `api` object. Destructure or access directly.',
+      'All selector-based helpers auto-wait for element (poll 100ms, default timeout 2000ms).',
+      'Override: pass {timeout: 5000} as last arg.',
+      '',
+      'API Reference:',
+      '- Wait: api.waitFor(sel, {timeout?,visible?})',
+      '- DOM: api.click(sel,opts?), api.dblclick(sel,opts?), api.type(sel,text,opts?),',
+      '  api.fill(sel,val,opts?), api.select(sel,val,opts?), api.check(sel,opts?),',
+      '  api.uncheck(sel,opts?), api.hover(sel,opts?), api.press(key),',
+      '  api.scrollTo(x,y), api.scrollBy(dx,dy)',
+      '- Query: api.$(sel,opts?), api.$$(sel,opts?), api.snapshot(sel?,opts?),',
+      '  api.getTitle(), api.getUrl(), api.getSelectedText()',
+      '- Eval: api.eval(expr) — execute in page JS context (access page vars, React state)',
+      '- Navigation: api.navigate(url), api.goBack(), api.goForward(), api.reload()',
+      '  — all await page load',
+      '- Tabs: api.getTabs(), api.newTab(url?), api.closeTab(idx?), api.selectTab(idx)',
+      '  closeTab() without args closes managed tab; with idx closes by index',
+      '- Storage: api.localStorage.{list,get,set,delete,clear}(),',
+      '  api.sessionStorage.{…}()',
+      '- Cookies: api.getCookies(filter?), api.setCookie(details),',
+      '  api.deleteCookie(name,url)',
+      '- Window: api.resize(w,h), api.screenshot() → base64',
+      '- Dialog: api.interceptDialog("accept"|"dismiss")',
+      '- Console: api.captureConsole(), api.getConsoleLogs()',
+      '',
+      'opts = {timeout: ms} — override auto-wait timeout per call',
+      '',
+      'Example:',
+      'const {navigate, fill, click, snapshot} = api;',
+      'await navigate("https://example.com/login");',
+      'await fill("#email", "user@test.com");',
+      'await click("button[type=submit]");',
+      'return await snapshot();',
+    ].join('\n'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: {
+          type: 'string',
+          description: 'JS code. Use `api.*` helpers. Async/await supported. Return value = tool result.',
+        },
+        timeout: {
+          type: 'number',
+          description: 'Timeout ms, default 30000',
+        },
+      },
+      required: ['code'],
+    },
+  },
+]

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "foxcode-channel",
+  "version": "0.1.0",
+  "description": "MCP channel plugin bridging Claude Code and FoxCode Firefox extension via WebSocket",
+  "type": "module",
+  "main": "server.mjs",
+  "bin": {
+    "foxcode-channel": "server.mjs"
+  },
+  "scripts": {
+    "start": "node server.mjs",
+    "test": "node --test lib.test.mjs validator.test.mjs"
+  },
+  "keywords": ["claude-code", "mcp", "firefox", "browser-automation", "channel"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/korchasa/foxcode.git",
+    "directory": "channel"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "server.mjs",
+    "lib.mjs",
+    "validator.mjs"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "ws": "^8.20.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * FoxCode — Channel plugin for Firefox extension.
+ *
+ * MCP server that bridges Claude Code ↔ Firefox extension via WebSocket.
+ * - Declares claude/channel capability for bidirectional messaging
+ * - Exposes reply/edit_message tools for CC → browser responses
+ * - Exposes evalInBrowser tool for CC → browser automation (JS execution with ~30 API helpers)
+ * - WebSocket server on localhost for extension connection
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+import { WebSocketServer } from 'ws'
+import {
+  nextId, buildChannelMeta, buildReplyMessage, buildEditMessage,
+  buildToolUseMessage, buildToolResultMessage, TOOL_DEFINITIONS,
+} from './lib.mjs'
+import { validateCode } from './validator.mjs'
+
+const PORT = Number(process.env.FOXCODE_PORT ?? 8787)
+
+// --- WebSocket server for extension connection ---
+
+const wss = new WebSocketServer({ host: '127.0.0.1', port: PORT })
+const clients = new Set()
+
+/** Pending browser tool requests: request_id → {resolve, reject, timer} */
+const pendingToolRequests = new Map()
+const TOOL_TIMEOUT_MS = 30_000
+
+function broadcast(msg) {
+  const data = JSON.stringify(msg)
+  for (const ws of clients) {
+    if (ws.readyState === 1) ws.send(data)
+  }
+}
+
+function hasClients() {
+  for (const ws of clients) {
+    if (ws.readyState === 1) return true
+  }
+  return false
+}
+
+/**
+ * Send a tool request to the browser extension and wait for the response.
+ * Returns a promise that resolves with the response content.
+ */
+function requestFromBrowser(tool, params = {}) {
+  return new Promise((resolve, reject) => {
+    if (!hasClients()) {
+      reject(new Error('No browser extension connected'))
+      return
+    }
+    const requestId = `req-${nextId()}`
+    const timer = setTimeout(() => {
+      pendingToolRequests.delete(requestId)
+      reject(new Error(`Browser tool request timed out after ${TOOL_TIMEOUT_MS}ms`))
+    }, TOOL_TIMEOUT_MS)
+
+    pendingToolRequests.set(requestId, { resolve, reject, timer })
+    broadcast({ type: 'tool_request', request_id: requestId, tool, params })
+  })
+}
+
+wss.on('connection', (ws) => {
+  clients.add(ws)
+  ws.on('close', () => clients.delete(ws))
+  ws.on('error', () => clients.delete(ws))
+  ws.on('message', (raw) => {
+    try {
+      const msg = JSON.parse(String(raw))
+      handleExtensionMessage(msg)
+    } catch { /* ignore malformed messages */ }
+  })
+})
+
+function handleExtensionMessage(msg) {
+  process.stderr.write(`foxcode: rx ${msg.type} ${JSON.stringify(msg).slice(0, 200)}\n`)
+  switch (msg.type) {
+    case 'message': {
+      // FR-2: User message from browser → forward to CC via channel notification
+      const { content, meta } = buildChannelMeta(msg)
+      process.stderr.write(`foxcode: notify channel content=${content.slice(0, 100)}\n`)
+      mcp.notification({
+        method: 'notifications/claude/channel',
+        params: { content, meta },
+      })
+      break
+    }
+    case 'tool_response': {
+      // FR-5: Browser responding to a tool request from CC
+      const pending = pendingToolRequests.get(msg.request_id)
+      if (pending) {
+        clearTimeout(pending.timer)
+        pendingToolRequests.delete(msg.request_id)
+        pending.resolve(msg.content)
+      }
+      break
+    }
+  }
+}
+
+// --- MCP server ---
+
+const mcp = new Server(
+  { name: 'foxcode', version: '0.1.0' },
+  {
+    capabilities: {
+      tools: {},
+      experimental: { 'claude/channel': {} },
+    },
+    instructions: [
+      'Messages from the Firefox browser arrive as <channel source="foxcode" chat_id="web" message_id="..." tab_url="..." tab_title="...">.',
+      'The tab_url and tab_title attributes show which page the user is currently viewing.',
+      'The browser user reads the Firefox sidebar, not this terminal. Anything you want them to see MUST go through the reply tool — your transcript output never reaches the browser UI.',
+      'Use evalInBrowser tool to execute JS in browser with full browser automation API (click, fill, navigate, snapshot, etc.).',
+      `Browser extension connects to ws://localhost:${PORT}.`,
+    ].join('\n'),
+  },
+)
+
+// --- MCP Tools ---
+
+mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOL_DEFINITIONS,
+}))
+
+mcp.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const args = (req.params.arguments ?? {})
+  try {
+    switch (req.params.name) {
+      case 'reply': {
+        const replyMsg = buildReplyMessage(args.text, args.reply_to)
+        broadcast(replyMsg)
+        return { content: [{ type: 'text', text: `sent (${replyMsg.id})` }] }
+      }
+      case 'edit_message': {
+        broadcast(buildEditMessage(args.message_id, args.text))
+        return { content: [{ type: 'text', text: 'ok' }] }
+      }
+      case 'evalInBrowser': {
+        const { valid, error } = validateCode(args.code)
+        if (!valid) {
+          return { content: [{ type: 'text', text: `Syntax error: ${error}` }], isError: true }
+        }
+        const timeout = args.timeout ?? 30000
+        broadcast(buildToolUseMessage('evalInBrowser', { code: args.code }))
+        const result = await requestFromBrowser('EVAL_CODE', { code: args.code, timeout })
+        const text = typeof result === 'string' ? result : JSON.stringify(result)
+        broadcast(buildToolResultMessage('evalInBrowser', text))
+        return { content: [{ type: 'text', text }] }
+      }
+      default:
+        return { content: [{ type: 'text', text: `unknown tool: ${req.params.name}` }], isError: true }
+    }
+  } catch (err) {
+    return { content: [{ type: 'text', text: `${req.params.name}: ${err.message}` }], isError: true }
+  }
+})
+
+// --- Start ---
+
+await mcp.connect(new StdioServerTransport())
+process.stderr.write(`foxcode: ws://localhost:${PORT}\n`)

package/validator.mjs

@@ -0,0 +1,12 @@
+/**
+ * Validate JS code syntax for evalInBrowser.
+ * Wraps in async function with `api` parameter to allow top-level await.
+ */
+export function validateCode(code) {
+  try {
+    new Function('api', `return (async () => { ${code} })()`)
+    return { valid: true }
+  } catch (e) {
+    return { valid: false, error: e.message }
+  }
+}