@glance-mcp/server 1.1.0 → 1.2.0

package/README.md

@@ -92,15 +92,16 @@ Check remaining API quota for the current billing period.
 
 ### `feedback`
 
-Submit freeform feedback about Glance.
+Send feedback to the Glance team. Supports threading: include a `thread_id` to continue an existing conversation, or omit it to start a new one. Returns a `thread_id` for follow-ups and any operator replies.
 
-### `hello`
-
-Service info, capabilities, and free tier details. Works without an API key.
+| Param | Type | Description |
+|---|---|---|
+| `message` | string | Feedback message. Max 2000 characters. Required. |
+| `thread_id` | string | Thread ID from a previous feedback call. Omit to start a new thread. |
 
 ### `signup`
 
-Provision an API key from an email address. The key is stored in memory for the rest of the session.
+Provision an API key from an email address. The key is active for the current session; the response includes ready-to-run commands to persist it in your MCP config.
 
 ## Interactions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glance-mcp/server",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for Glance — capture what a web page looks like and does",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -52,15 +52,15 @@ export function createApiClient({ apiKey, apiUrl } = {}) {
 
   return {
     get apiKey() { return key; },
-
     setApiKey(newKey) { key = newKey; },
+    rpc,
+    fetchImage,
 
-    hello()          { return rpc('hello'); },
     signup(email)    { return rpc('signup', { email }); },
     glance(params)   { return rpc('glance', params); },
     result(job)      { return rpc('result', { job }); },
     usage()          { return rpc('usage'); },
-    feedback(message){ return rpc('feedback', { message }); },
-    fetchImage,
+    feedbackSend(message, threadId) { return rpc('feedback.send', { message, thread_id: threadId }); },
+    feedbackGet(threadId)           { return rpc('feedback.get', { thread_id: threadId }); },
   };
 }

package/src/index.mjs

@@ -5,10 +5,42 @@
 
 import { createInterface } from 'readline';
 import { createApiClient } from './api.mjs';
-import { tools, handleToolCall } from './tools.mjs';
+import { formatApiError, errorResult } from './tools/_helpers.mjs';
+import * as meta from './tools/_meta.mjs';
+import * as glance from './tools/glance.mjs';
+
+// ── Tool list (served by tools/list) ────────────────────────────
+
+const tools = [...meta.definitions, glance.definition];
+
+// ── Tool dispatch ───────────────────────────────────────────────
+
+const metaNames = new Set(meta.definitions.map(d => d.name));
+
+async function handleToolCall(name, args, api) {
+  try {
+    if (metaNames.has(name)) {
+      return await meta.handler(name, args || {}, api);
+    }
+    if (name === 'glance') {
+      return await glance.handler(args || {}, api);
+    }
+    return errorResult(`Unknown tool: ${name}`);
+  } catch (err) {
+    if (err.code && err.code <= -32000) {
+      return formatApiError(err);
+    }
+    return errorResult(`API request failed: ${err.message}`);
+  }
+}
 
 const SERVER_NAME = 'glance-mcp';
 const SERVER_VERSION = '1.0.0';
+const SERVER_DESCRIPTION =
+  'Glance — web capture for AI agents. ' +
+  'Give Glance a URL and get back screenshots (desktop, tablet, mobile), ' +
+  'network traffic, console output, rendered DOM, visible text, and structured metadata. ' +
+  'To get started, call signup with an email (free, no credit card), then call glance with a URL.';
 const PROTOCOL_VERSION = '2025-06-18';
 
 // ── API client ──────────────────────────────────────────────────
@@ -56,7 +88,7 @@ async function handleMessage(line) {
       respond(id, {
         protocolVersion: PROTOCOL_VERSION,
         capabilities: { tools: {} },
-        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION, description: SERVER_DESCRIPTION },
       });
       break;
 

package/src/tools/_helpers.mjs

@@ -0,0 +1,43 @@
+// Shared helpers for tool handlers.
+
+const POLL_INTERVAL_MS = 1000;
+const POLL_TIMEOUT_MS  = 20_000;
+
+export { POLL_INTERVAL_MS, POLL_TIMEOUT_MS };
+
+export function errorResult(text) {
+  return { content: [{ type: 'text', text }], isError: true };
+}
+
+export function textResult(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+export function formatApiError(err) {
+  const code = err.code;
+  const data = err.data;
+
+  if (code === -32000) {
+    return errorResult(
+      'Authentication required. Set the GLANCE_API_KEY environment variable, or use the ' +
+      'signup tool to create an account and get a key.'
+    );
+  }
+  if (code === -32003) {
+    const parts = ['Quota exhausted.'];
+    if (data?.used != null) parts.push(`Used: ${data.used}/${data.limit}.`);
+    if (data?.resets_at) parts.push(`Resets at: ${data.resets_at}.`);
+    return errorResult(parts.join(' '));
+  }
+  if (code === -32004) {
+    return errorResult(
+      'Concurrency limit reached — too many captures running. Wait for running jobs to finish and try again.'
+    );
+  }
+
+  return errorResult(err.message || 'Unknown error');
+}
+
+export function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/src/tools/_meta.mjs

@@ -0,0 +1,101 @@
+// Platform tools — usage, feedback, signup.
+// Always included regardless of GLANCE_TOOLS filtering.
+
+import { textResult } from './_helpers.mjs';
+
+// ── Definitions ─────────────────────────────────────────────────
+
+export const definitions = [
+  {
+    name: 'usage',
+    description: 'Check remaining Glance API quota for the current billing period.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'feedback',
+    description:
+      'Send feedback to the Glance team. Supports threading: include a thread_id to continue ' +
+      'an existing conversation, or omit it to start a new one. Returns a thread_id for follow-ups ' +
+      'and any operator replies.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        message: {
+          type: 'string',
+          description: 'Feedback message. Max 2000 characters.',
+        },
+        thread_id: {
+          type: 'string',
+          description: 'Thread ID from a previous feedback call. Omit to start a new thread.',
+        },
+      },
+      required: ['message'],
+    },
+  },
+  {
+    name: 'signup',
+    description:
+      'Create a Glance account and provision an API key. Free tier: 100 captures/month, no credit card. ' +
+      'IMPORTANT: The key is active for this session only. You MUST present the persistence command ' +
+      'from the response to the user so they can save the key for future sessions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        email: {
+          type: 'string',
+          description: 'Email address for the account. Same email always returns the same key.',
+        },
+      },
+      required: ['email'],
+    },
+  },
+];
+
+// ── Handlers ────────────────────────────────────────────────────
+
+const handlers = {
+  async usage(args, api) {
+    const res = await api.usage();
+    const lines = [
+      `Tier: ${res.tier}`,
+      `Used: ${res.used} / ${res.calls_per_month}`,
+      `Running: ${res.running}`,
+      `Resets at: ${res.resets_at}`,
+    ];
+    return textResult(lines.join('\n'));
+  },
+
+  async feedback(args, api) {
+    const res = await api.feedbackSend(args.message, args.thread_id);
+    const lines = [`Feedback received. Thread: ${res.thread_id}`];
+    if (res.replies.length > 0) {
+      lines.push('', `Replies (${res.replies.length}):`);
+      for (const r of res.replies) {
+        lines.push(`  [${r.created_at}] ${r.message}`);
+      }
+    }
+    return textResult(lines.join('\n'));
+  },
+
+  async signup(args, api) {
+    const res = await api.signup(args.email);
+    api.setApiKey(res.api_key);
+    const key = res.api_key;
+    return textResult(
+      `Account ready. API key: ${key}\n` +
+      `Tier: ${res.tier}, ${res.calls_per_month} calls/month.\n\n` +
+      '⚠️  PERSIST YOUR KEY — it only lives in memory for this session.\n' +
+      'Present one of these commands to the user so they can save it:\n\n' +
+      `  Claude Code:  claude mcp update-env glance GLANCE_API_KEY=${key}\n` +
+      `  Manual:       Add to the "env" block in your MCP server config:\n` +
+      `               "env": { "GLANCE_API_KEY": "${key}" }`
+    );
+  },
+};
+
+export function handler(name, args, api) {
+  return handlers[name](args, api);
+}

package/src/tools/glance.mjs

@@ -0,0 +1,179 @@
+// Glance — capture what a web page looks like and does.
+
+import { errorResult, sleep, POLL_INTERVAL_MS, POLL_TIMEOUT_MS } from './_helpers.mjs';
+
+export const definition = {
+  name: 'glance',
+  description:
+    'Capture what a web page looks like and does. Takes a screenshot of the page at desktop, ' +
+    'tablet, and mobile viewports and returns URLs to the images. Also captures network traffic, ' +
+    'console output, rendered DOM, visible text, and structured metadata. Supports scripted ' +
+    'interactions (click, type, wait, keypress, eval, screenshot) to capture pages after user actions.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'Absolute URL to capture.',
+      },
+      waitMs: {
+        type: 'integer',
+        description: 'Max ms to wait for network idle after load. Default: 2000.',
+      },
+      settleMs: {
+        type: 'integer',
+        description: 'Extra ms to wait after network idle before capturing. Default: 0.',
+      },
+      dom: {
+        type: 'boolean',
+        description: 'Include rendered DOM (document.documentElement.outerHTML). Default: true.',
+      },
+      text: {
+        type: 'boolean',
+        description: 'Include visible text (document.body.innerText). Default: true.',
+      },
+      meta: {
+        type: 'boolean',
+        description: 'Extract JSON-LD, Open Graph, description, title. Default: true.',
+      },
+      only: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          'Whitelist of artifact types to produce. Options: screenshots, network, console, dom, text, meta. ' +
+          'When omitted, all enabled artifacts are produced.',
+      },
+      burst: {
+        type: 'integer',
+        description: 'Capture N screenshot frames for transition/FOUC analysis.',
+      },
+      click: {
+        type: 'string',
+        description: 'CSS selector to click at midpoint of a burst sequence.',
+      },
+      interactions: {
+        type: 'array',
+        description:
+          'Scripted interaction sequence. Each action has a "type" and type-specific fields. ' +
+          'Actions execute sequentially after network idle.',
+        items: {
+          type: 'object',
+          properties: {
+            type: {
+              type: 'string',
+              enum: ['wait', 'click', 'type', 'keypress', 'eval', 'screenshot'],
+              description: 'Action type.',
+            },
+            ms: {
+              type: 'integer',
+              description: 'For "wait": milliseconds to pause. Default: 1000.',
+            },
+            selector: {
+              type: 'string',
+              description: 'For "click" and "type": CSS selector for the target element.',
+            },
+            value: {
+              type: 'string',
+              description: 'For "type": text to enter into the input.',
+            },
+            key: {
+              type: 'string',
+              description:
+                'For "keypress": key name. Supported: ArrowRight, ArrowLeft, ArrowUp, ArrowDown, ' +
+                'Enter, Escape, Tab, Space, Backspace, Delete, Home, End, PageUp, PageDown.',
+            },
+            script: {
+              type: 'string',
+              description: 'For "eval": JavaScript expression to evaluate in the page context.',
+            },
+            name: {
+              type: 'string',
+              description: 'For "screenshot": filename (without extension). Default: interaction-{n}.',
+            },
+          },
+          required: ['type'],
+        },
+      },
+    },
+    required: ['url'],
+  },
+};
+
+export async function handler(args, api) {
+  // Build params — serialize interactions to JSON string for the API
+  const params = { ...args };
+  if (Array.isArray(params.interactions)) {
+    params.interactions = JSON.stringify(params.interactions);
+  }
+
+  const accepted = await api.glance(params);
+  const jobId = accepted.job;
+
+  // Poll for result
+  const deadline = Date.now() + POLL_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    await sleep(POLL_INTERVAL_MS);
+    const res = await api.result(jobId);
+
+    if (res.status === 'done') {
+      const lines = [`Capture complete for ${args.url}`, ''];
+      const screenshotEntries = [];
+
+      if (res.artifacts) {
+        const { meta, ...urlArtifacts } = res.artifacts;
+
+        for (const [key, value] of Object.entries(urlArtifacts)) {
+          if (typeof value === 'string' && value.endsWith('.png')) {
+            screenshotEntries.push([key, value]);
+          } else if (typeof value === 'string') {
+            lines.push(`${key}: ${value}`);
+          }
+        }
+
+        // Include screenshot URLs in text so agents can link/embed them
+        for (const [key, url] of screenshotEntries) {
+          lines.push(`${key}: ${url}`);
+        }
+
+        // Inline meta
+        if (meta && typeof meta === 'object') {
+          lines.push('');
+          lines.push('meta: ' + JSON.stringify(meta, null, 2));
+        }
+      }
+
+      if (res.capture_url) {
+        lines.push(`capture_url: ${res.capture_url}`);
+      }
+
+      if (res.usage) {
+        lines.push('');
+        lines.push(`Usage: ${res.usage.used} used, ${res.usage.remaining} remaining`);
+      }
+
+      const content = [{ type: 'text', text: lines.join('\n') }];
+
+      // Fetch screenshots and return as inline image blocks
+      for (const [key, url] of screenshotEntries) {
+        try {
+          const buf = await api.fetchImage(url);
+          content.push({ type: 'image', data: buf.toString('base64'), mimeType: 'image/png' });
+        } catch {
+          // If fetch fails, include the URL as text instead
+          content.push({ type: 'text', text: `${key}: ${url} (image fetch failed)` });
+        }
+      }
+
+      return { content };
+    }
+
+    if (res.status === 'failed') {
+      return errorResult(
+        `Capture failed for ${args.url}: ${res.error || 'unknown'}` +
+        (res.detail ? ` — ${res.detail}` : '')
+      );
+    }
+  }
+
+  return errorResult(`Capture timed out after ${POLL_TIMEOUT_MS / 1000}s for ${args.url} (job: ${jobId}).`);
+}

package/src/tools.mjs

@@ -1,323 +0,0 @@
-// MCP tool definitions (JSON Schema) and handlers.
-// Each tool wraps one or more Glance /v1 JSON-RPC methods.
-
-const POLL_INTERVAL_MS = 1000;
-const POLL_TIMEOUT_MS  = 20_000;
-
-// ── Tool definitions ────────────────────────────────────────────
-
-export const tools = [
-  {
-    name: 'glance',
-    description:
-      'Capture what a web page looks like and does. Takes a screenshot of the page at desktop, ' +
-      'tablet, and mobile viewports and returns URLs to the images. Also captures network traffic, ' +
-      'console output, rendered DOM, visible text, and structured metadata. Supports scripted ' +
-      'interactions (click, type, wait, keypress, eval, screenshot) to capture pages after user actions.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        url: {
-          type: 'string',
-          description: 'Absolute URL to capture.',
-        },
-        waitMs: {
-          type: 'integer',
-          description: 'Max ms to wait for network idle after load. Default: 2000.',
-        },
-        settleMs: {
-          type: 'integer',
-          description: 'Extra ms to wait after network idle before capturing. Default: 0.',
-        },
-        dom: {
-          type: 'boolean',
-          description: 'Include rendered DOM (document.documentElement.outerHTML). Default: true.',
-        },
-        text: {
-          type: 'boolean',
-          description: 'Include visible text (document.body.innerText). Default: true.',
-        },
-        meta: {
-          type: 'boolean',
-          description: 'Extract JSON-LD, Open Graph, description, title. Default: true.',
-        },
-        only: {
-          type: 'array',
-          items: { type: 'string' },
-          description:
-            'Whitelist of artifact types to produce. Options: screenshots, network, console, dom, text, meta. ' +
-            'When omitted, all enabled artifacts are produced.',
-        },
-        burst: {
-          type: 'integer',
-          description: 'Capture N screenshot frames for transition/FOUC analysis.',
-        },
-        click: {
-          type: 'string',
-          description: 'CSS selector to click at midpoint of a burst sequence.',
-        },
-        interactions: {
-          type: 'array',
-          description:
-            'Scripted interaction sequence. Each action has a "type" and type-specific fields. ' +
-            'Actions execute sequentially after network idle.',
-          items: {
-            type: 'object',
-            properties: {
-              type: {
-                type: 'string',
-                enum: ['wait', 'click', 'type', 'keypress', 'eval', 'screenshot'],
-                description: 'Action type.',
-              },
-              ms: {
-                type: 'integer',
-                description: 'For "wait": milliseconds to pause. Default: 1000.',
-              },
-              selector: {
-                type: 'string',
-                description: 'For "click" and "type": CSS selector for the target element.',
-              },
-              value: {
-                type: 'string',
-                description: 'For "type": text to enter into the input.',
-              },
-              key: {
-                type: 'string',
-                description:
-                  'For "keypress": key name. Supported: ArrowRight, ArrowLeft, ArrowUp, ArrowDown, ' +
-                  'Enter, Escape, Tab, Space, Backspace, Delete, Home, End, PageUp, PageDown.',
-              },
-              script: {
-                type: 'string',
-                description: 'For "eval": JavaScript expression to evaluate in the page context.',
-              },
-              name: {
-                type: 'string',
-                description: 'For "screenshot": filename (without extension). Default: interaction-{n}.',
-              },
-            },
-            required: ['type'],
-          },
-        },
-      },
-      required: ['url'],
-    },
-  },
-  {
-    name: 'usage',
-    description: 'Check remaining Glance API quota for the current billing period.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-  },
-  {
-    name: 'feedback',
-    description: 'Submit freeform feedback about Glance.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        message: {
-          type: 'string',
-          description: 'Feedback message. Max 2000 characters.',
-        },
-      },
-      required: ['message'],
-    },
-  },
-  {
-    name: 'hello',
-    description: 'Get Glance service info — capabilities, methods, and free tier details. No API key required.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-  },
-  {
-    name: 'signup',
-    description:
-      'Create a Glance account and provision an API key. Free tier: 100 captures/month. ' +
-      'No credit card required. The key is stored for the session — no need to set it manually.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        email: {
-          type: 'string',
-          description: 'Email address for the account. Same email always returns the same key.',
-        },
-      },
-      required: ['email'],
-    },
-  },
-];
-
-// ── Tool handlers ───────────────────────────────────────────────
-
-function errorResult(text) {
-  return { content: [{ type: 'text', text }], isError: true };
-}
-
-function textResult(text) {
-  return { content: [{ type: 'text', text }] };
-}
-
-function formatApiError(err) {
-  const code = err.code;
-  const data = err.data;
-
-  if (code === -32000) {
-    return errorResult(
-      'Authentication required. Set the GLANCE_API_KEY environment variable, or use the ' +
-      'signup tool to create an account and get a key.'
-    );
-  }
-  if (code === -32003) {
-    const parts = ['Quota exhausted.'];
-    if (data?.used != null) parts.push(`Used: ${data.used}/${data.limit}.`);
-    if (data?.resets_at) parts.push(`Resets at: ${data.resets_at}.`);
-    return errorResult(parts.join(' '));
-  }
-  if (code === -32004) {
-    return errorResult(
-      'Concurrency limit reached — too many captures running. Wait for running jobs to finish and try again.'
-    );
-  }
-
-  return errorResult(err.message || 'Unknown error');
-}
-
-function sleep(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-async function handleGlance(args, api) {
-  // Build params — serialize interactions to JSON string for the API
-  const params = { ...args };
-  if (Array.isArray(params.interactions)) {
-    params.interactions = JSON.stringify(params.interactions);
-  }
-
-  const accepted = await api.glance(params);
-  const jobId = accepted.job;
-
-  // Poll for result
-  const deadline = Date.now() + POLL_TIMEOUT_MS;
-  while (Date.now() < deadline) {
-    await sleep(POLL_INTERVAL_MS);
-    const res = await api.result(jobId);
-
-    if (res.status === 'done') {
-      const lines = [`Capture complete for ${args.url}`, ''];
-      const screenshotEntries = [];
-
-      if (res.artifacts) {
-        const { meta, ...urlArtifacts } = res.artifacts;
-
-        for (const [key, value] of Object.entries(urlArtifacts)) {
-          if (typeof value === 'string' && value.endsWith('.png')) {
-            screenshotEntries.push([key, value]);
-          } else if (typeof value === 'string') {
-            lines.push(`${key}: ${value}`);
-          }
-        }
-
-        // Inline meta
-        if (meta && typeof meta === 'object') {
-          lines.push('');
-          lines.push('meta: ' + JSON.stringify(meta, null, 2));
-        }
-      }
-
-      if (res.usage) {
-        lines.push('');
-        lines.push(`Usage: ${res.usage.used} used, ${res.usage.remaining} remaining`);
-      }
-
-      const content = [{ type: 'text', text: lines.join('\n') }];
-
-      // Fetch screenshots and return as inline image blocks
-      for (const [key, url] of screenshotEntries) {
-        try {
-          const buf = await api.fetchImage(url);
-          content.push({ type: 'image', data: buf.toString('base64'), mimeType: 'image/png' });
-        } catch {
-          // If fetch fails, include the URL as text instead
-          content.push({ type: 'text', text: `${key}: ${url} (image fetch failed)` });
-        }
-      }
-
-      return { content };
-    }
-
-    if (res.status === 'failed') {
-      return errorResult(
-        `Capture failed for ${args.url}: ${res.error || 'unknown'}` +
-        (res.detail ? ` — ${res.detail}` : '')
-      );
-    }
-  }
-
-  return errorResult(`Capture timed out after ${POLL_TIMEOUT_MS / 1000}s for ${args.url} (job: ${jobId}).`);
-}
-
-async function handleUsage(args, api) {
-  const res = await api.usage();
-  const lines = [
-    `Tier: ${res.tier}`,
-    `Used: ${res.used} / ${res.calls_per_month}`,
-    `Running: ${res.running}`,
-    `Resets at: ${res.resets_at}`,
-  ];
-  return textResult(lines.join('\n'));
-}
-
-async function handleFeedback(args, api) {
-  await api.feedback(args.message);
-  return textResult('Feedback received. Thank you.');
-}
-
-async function handleHello(args, api) {
-  const res = await api.hello();
-  const lines = [
-    res.glance,
-    '',
-    `Version: ${res.version}`,
-    `Capabilities: ${res.capabilities.join(', ')}`,
-    `Free tier: ${res.free_tier.calls_per_month} calls/month`,
-    `Methods: ${res.methods.join(', ')}`,
-  ];
-  return textResult(lines.join('\n'));
-}
-
-async function handleSignup(args, api) {
-  const res = await api.signup(args.email);
-  api.setApiKey(res.api_key);
-  return textResult(
-    `Account ready. Tier: ${res.tier}, ${res.calls_per_month} calls/month. ` +
-    'API key is active for this session.'
-  );
-}
-
-const handlers = {
-  glance:   handleGlance,
-  usage:    handleUsage,
-  feedback: handleFeedback,
-  hello:    handleHello,
-  signup:   handleSignup,
-};
-
-export async function handleToolCall(name, args, api) {
-  const handler = handlers[name];
-  if (!handler) {
-    return errorResult(`Unknown tool: ${name}`);
-  }
-  try {
-    return await handler(args || {}, api);
-  } catch (err) {
-    if (err.code && err.code <= -32000) {
-      return formatApiError(err);
-    }
-    // Network / unexpected errors
-    return errorResult(`API request failed: ${err.message}`);
-  }
-}