marble-headed-mcp 0.1.43 → 0.1.44

package/README.md

@@ -1 +1,50 @@
 # marble-headed-mcp
+
+Local-first MCP development setup (no npm publish needed to test).
+
+## Config files
+
+- `mcp.local.json`: runs local build (`node dist/index.js`)
+- `mcp.prod.json`: runs published npm package (`npx marble-headed-mcp@0.1.42`)
+- `mcp.json`: active config used by your local Codex session
+
+## One-command switch for Codex + Claude
+
+Use these commands from this repo:
+
+- `npm run switch:mcp:dev`
+- `npm run switch:mcp:prod`
+- `npm run switch:mcp:status`
+
+What gets updated:
+
+- `mcp.json` in this repo
+- `~/.codex/config.toml` (`[mcp_servers.marble-headed]`)
+- `~/.claude.json` (`mcpServers.marble-headed` globally + project entries)
+
+After switching, restart active Codex and Claude sessions.
+
+## Common workflow
+
+1. Install deps once:
+   - `npm ci`
+2. Switch to local MCP mode:
+   - `npm run use:mcp:local`
+3. Build once (or use watch):
+   - `npm run build`
+   - or `npm run watch`
+4. Restart Codex session so MCP reloads from `mcp.json`.
+5. Test changes locally without publishing to npm.
+
+## Switch back to published MCP
+
+- `npm run use:mcp:prod`
+- Restart Codex session.
+
+## Publish flow (when ready)
+
+1. Keep testing locally until stable.
+2. Bump version:
+   - `npm version patch`
+3. Publish:
+   - `npm publish --access public`

package/dist/index.js

@@ -6,7 +6,13 @@ import { promisify } from 'util';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-const DEFAULT_BASE_URL = 'http://localhost:4000';
+const DEFAULT_BROWSER_APP_BASE_URL = 'http://localhost:3000';
+const DEFAULT_HEADED_SERVER_BASE_URL = 'http://localhost:4000';
+const ENVIRONMENT_BASE_URLS = {
+    localhost: DEFAULT_BROWSER_APP_BASE_URL,
+    dev: 'https://dev.withmarble.ai',
+    production: 'https://withmarble.ai',
+};
 const WEBAPP_LOG_PATH = '/tmp/webapp';
 const DEFAULT_DEV_CONTAINER_PATH = '/Users/akilanbabu/code/marble-container';
 const VSCODE_REPO_PATH = '/Users/akilanbabu/code/vscode-source-marble/code-server-7/lib/vscode';
@@ -15,6 +21,7 @@ const DEFAULT_CODEX_LOGGER_PATH = path.join(process.env.HOME || '/Users/akilanba
 const CODEX_LOGGER_PATH_ENV = 'CODEX_LOGGER_PATH';
 const CODEX_LOG_PREFIX = 'codex-run-';
 const execFileAsync = promisify(execFile);
+let selectedEnvironment = null;
 function parseCodexJsonOutput(output) {
     const result = {};
     if (!output)
@@ -50,6 +57,15 @@ function parseCodexJsonOutput(output) {
 function normalizeBaseUrl(input) {
     return input.replace(/\/+$/, '');
 }
+function parseEnvironment(input) {
+    if (typeof input !== 'string')
+        return null;
+    const normalized = input.trim().toLowerCase();
+    if (normalized === 'localhost' || normalized === 'dev' || normalized === 'production') {
+        return normalized;
+    }
+    return null;
+}
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\"'\"'`)}'`;
 }
@@ -110,19 +126,25 @@ async function readCodexThreadIdFromLog(filePath) {
         return null;
     }
 }
-function resolveRawBaseUrl() {
-    const base = process.env.HEADED_SERVER_BASE_URL || DEFAULT_BASE_URL;
+function resolveHeadedServerRawBaseUrl() {
+    const base = process.env.HEADED_SERVER_BASE_URL || DEFAULT_HEADED_SERVER_BASE_URL;
     return normalizeBaseUrl(base);
 }
-function resolveAppBaseUrl() {
-    const raw = resolveRawBaseUrl();
+function resolveHeadedServerAppBaseUrl() {
+    const raw = resolveHeadedServerRawBaseUrl();
     return raw.replace(/\/api\/headed\/?$/, '');
 }
+function resolveBrowserAppBaseUrl() {
+    if (selectedEnvironment) {
+        return normalizeBaseUrl(ENVIRONMENT_BASE_URLS[selectedEnvironment]);
+    }
+    return normalizeBaseUrl(ENVIRONMENT_BASE_URLS.localhost);
+}
 function buildUrl(pathname) {
-    return `${resolveAppBaseUrl()}${pathname}`;
+    return `${resolveHeadedServerAppBaseUrl()}${pathname}`;
 }
 function buildHeadedUrl(pathname) {
-    return `${resolveAppBaseUrl()}/api/headed${pathname}`;
+    return `${resolveHeadedServerAppBaseUrl()}/api/headed${pathname}`;
 }
 async function postJson(pathname, payload) {
     const response = await fetch(buildUrl(pathname), {
@@ -166,6 +188,16 @@ async function getHeadedText(pathname) {
     const text = await response.text();
     return { status: response.status, ok: response.ok, text };
 }
+function withBrowserAppBaseUrl(payload) {
+    const appBaseUrl = resolveBrowserAppBaseUrl();
+    if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
+        return {
+            ...payload,
+            appBaseUrl,
+        };
+    }
+    return { appBaseUrl };
+}
 async function getJson(pathname) {
     const response = await fetch(buildUrl(pathname));
     const text = await response.text();
@@ -398,6 +430,22 @@ async function saveImageFromUrl({ url, filename }) {
     return { ok: true, path: targetPath, bytes: buffer.length };
 }
 const TOOLS = [
+    {
+        name: 'set_environment',
+        description: 'Set the in-browser app environment used by headed session actions. localhost -> http://localhost:3000, dev -> https://dev.withmarble.ai, production -> https://withmarble.ai. API calls still go to HEADED_SERVER_BASE_URL (default localhost:4000).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                environment: {
+                    type: 'string',
+                    enum: ['localhost', 'dev', 'production'],
+                    description: 'Environment to target.',
+                },
+            },
+            required: ['environment'],
+            additionalProperties: false,
+        },
+    },
     {
         name: 'headed_start_session',
         description: 'Start a headed browser session (if email or password are not provided, they default to akilan@withmarble.ai and marbledebug123, respectively). Remember to call `headed_end_session` when finished to avoid leaving sessions open.',
@@ -435,20 +483,6 @@ const TOOLS = [
             additionalProperties: false,
         },
     },
-    {
-        name: 'navigate_to_url',
-        description: 'Navigate a headed session to a URL. Prefer `headed_navigate_to_project` when possible; use this only for validating code in a separate browser tab (e.g., proxy URL access). If the URL already exists (ignoring query parameters), the existing tab will be focused instead of creating a new one.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                browserSession: { type: 'number', description: 'Headed browser session id.' },
-                browserSessionId: { type: 'number', description: 'Alias for browserSession.' },
-                url: { type: 'string', description: 'URL to navigate to.' },
-            },
-            required: ['url'],
-            additionalProperties: false,
-        },
-    },
     {
         name: 'start_plan_project',
         description: 'Navigate to a project within a plan. If startProject is true (default), clicks BEGIN SIMULATION; if false, only navigates to the plan project without starting the simulation.',
@@ -568,7 +602,7 @@ const TOOLS = [
                 },
                 createProgram: { type: 'boolean', description: 'If true (default), auto-generate program projects before save.' },
                 createProgramMessage: { type: 'string', description: 'Optional custom message used for program generation turn.' },
-                maxOperatorTurns: { type: 'number', description: 'Max auto-follow-up turns after the initial goal (default: 4).' },
+                maxOperatorTurns: { type: 'number', description: 'Max auto-follow-up turns after the initial goal (default: 5).' },
                 workflowRunName: { type: 'string', description: 'Override workflow run name.' },
             },
             required: ['goal'],
@@ -716,37 +750,57 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
         switch (name) {
+            case 'set_environment': {
+                const environment = parseEnvironment(args?.environment);
+                if (!environment) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({
+                                    ok: false,
+                                    error: 'environment must be one of: localhost, dev, production.',
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                selectedEnvironment = environment;
+                const browserAppBaseUrl = resolveBrowserAppBaseUrl();
+                const headedServerAppBaseUrl = resolveHeadedServerAppBaseUrl();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: true,
+                                environment,
+                                browserAppBaseUrl,
+                                headedServerAppBaseUrl,
+                                headedServerHeadedApiBaseUrl: `${headedServerAppBaseUrl}/api/headed`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             case 'headed_start_session': {
-                const result = await postHeadedJson('/start_session', args);
+                const result = await postHeadedJson('/start_session', withBrowserAppBaseUrl(args));
                 return { content: [{ type: 'text', text: JSON.stringify(result.json || { status: result.status, body: result.text }, null, 2) }] };
             }
             case 'headed_end_session': {
-                const result = await postHeadedJson('/end_session', args);
+                const result = await postHeadedJson('/end_session', withBrowserAppBaseUrl(args));
                 return { content: [{ type: 'text', text: JSON.stringify(result.json || { status: result.status, body: result.text }, null, 2) }] };
             }
             case 'headed_navigate_to_project': {
-                const result = await postHeadedJson('/navigate_to_project', args);
-                return { content: [{ type: 'text', text: JSON.stringify(result.json || { status: result.status, body: result.text }, null, 2) }] };
-            }
-            case 'navigate_to_url': {
-                const url = typeof args?.url === 'string' ? args.url.trim() : '';
-                const browserSessionRaw = args?.browserSession ?? args?.browserSessionId;
-                const browserSessionId = typeof browserSessionRaw === 'number' ? browserSessionRaw : Number(browserSessionRaw);
-                if (!url) {
-                    return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'url is required.' }, null, 2) }] };
-                }
-                if (!browserSessionId || Number.isNaN(browserSessionId)) {
-                    return { content: [{ type: 'text', text: JSON.stringify({ ok: false, error: 'browserSession is required.' }, null, 2) }] };
-                }
-                const result = await postHeadedJson('/navigate_to_url', { browserSessionId, url });
+                const result = await postHeadedJson('/navigate_to_project', withBrowserAppBaseUrl(args));
                 return { content: [{ type: 'text', text: JSON.stringify(result.json || { status: result.status, body: result.text }, null, 2) }] };
             }
             case 'start_plan_project': {
-                const result = await postHeadedJson('/start_plan_project', args);
+                const result = await postHeadedJson('/start_plan_project', withBrowserAppBaseUrl(args));
                 return { content: [{ type: 'text', text: JSON.stringify(result.json || { status: result.status, body: result.text }, null, 2) }] };
             }
             case 'headed_send_msg': {
-                const result = await postHeadedJson('/send_msg_headed', args);
+                const result = await postHeadedJson('/send_msg_headed', withBrowserAppBaseUrl(args));
                 const payload = (result.json && typeof result.json === 'object') ? result.json : null;
                 if (payload?.workflowRunId) {
                     const summaryResult = await fetchWorkflowEntries(String(payload.workflowRunId));
@@ -761,7 +815,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: 'text', text: JSON.stringify(payload || { status: result.status, body: result.text }, null, 2) }] };
             }
             case 'take_screenshot': {
-                const result = await postHeadedJson('/take_screenshot', args);
+                const result = await postHeadedJson('/take_screenshot', withBrowserAppBaseUrl(args));
                 const payload = (result.json && typeof result.json === 'object') ? result.json : null;
                 if (payload?.workflowRunId) {
                     const summaryResult = await fetchWorkflowEntries(String(payload.workflowRunId));
@@ -776,14 +830,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return { content: [{ type: 'text', text: JSON.stringify(payload || { status: result.status, body: result.text }, null, 2) }] };
             }
             case 'take_screenshot': {
-                const result = await postHeadedJson('/take_screenshot', args);
+                const result = await postHeadedJson('/take_screenshot', withBrowserAppBaseUrl(args));
                 return { content: [{ type: 'text', text: JSON.stringify(result.json || { status: result.status, body: result.text }, null, 2) }] };
             }
             case 'screenshots_preview': {
                 const payload = args?.screenshotUrls
                     ? { screenshotUrls: args.screenshotUrls }
                     : args?.response || args;
-                const result = await postHeadedJson('/preview_screenshots', payload);
+                const result = await postHeadedJson('/preview_screenshots', withBrowserAppBaseUrl(payload));
                 return { content: [{ type: 'text', text: JSON.stringify({ status: result.status, ok: result.ok, html: result.text }, null, 2) }] };
             }
             case 'screenshots_get_preview': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marble-headed-mcp",
-  "version": "0.1.43",
+  "version": "0.1.44",
   "description": "MCP server for Marble headed automation endpoints",
   "main": "dist/index.js",
   "type": "module",
@@ -16,7 +16,13 @@
     "build": "tsc",
     "prepare": "npm run build",
     "watch": "tsc --watch",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "dev:mcp": "node dist/index.js",
+    "use:mcp:local": "cp mcp.local.json mcp.json",
+    "use:mcp:prod": "cp mcp.prod.json mcp.json",
+    "switch:mcp:dev": "node scripts/switch-mcp-mode.mjs dev",
+    "switch:mcp:prod": "node scripts/switch-mcp-mode.mjs prod",
+    "switch:mcp:status": "node scripts/switch-mcp-mode.mjs status"
   },
   "keywords": [
     "mcp",