@glance-mcp/server 1.0.0

package/README.md

@@ -0,0 +1,140 @@
+# @glance-mcp/server
+
+MCP server for [Glance](https://glance.tools) — capture what a web page looks like and does. Screenshots at three viewports, network traffic, console output, rendered DOM, visible text, and structured metadata.
+
+Zero dependencies. Node 18+ builtins only. No build step.
+
+## Setup
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "glance": {
+      "command": "node",
+      "args": ["/path/to/node_modules/@glance-mcp/server/src/index.mjs"],
+      "env": { "GLANCE_API_KEY": "gl_live_..." }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to Cursor's MCP settings (Settings > MCP Servers):
+
+```json
+{
+  "glance": {
+    "command": "node",
+    "args": ["/path/to/node_modules/@glance-mcp/server/src/index.mjs"],
+    "env": { "GLANCE_API_KEY": "gl_live_..." }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add glance node /path/to/node_modules/@glance-mcp/server/src/index.mjs
+```
+
+Set `GLANCE_API_KEY` in your environment.
+
+### npx (any MCP host)
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@glance-mcp/server"],
+  "env": { "GLANCE_API_KEY": "gl_live_..." }
+}
+```
+
+## Getting an API key
+
+No key? The `signup` tool provisions one from inside the MCP session — no dashboard, no credit card. 100 free captures/month.
+
+Or, from a terminal:
+
+```bash
+curl -s https://api.glance.tools/v1 -d '{
+  "jsonrpc": "2.0", "method": "signup",
+  "params": {"email": "you@example.com"}, "id": 1
+}'
+```
+
+## Tools
+
+### `glance`
+
+Capture a web page. Submits the job, polls for completion, and returns artifact URLs in a single call.
+
+| Param | Type | Description |
+|---|---|---|
+| `url` | string | Absolute URL to capture. Required. |
+| `waitMs` | integer | Max ms to wait for network idle. Default: 2000. |
+| `settleMs` | integer | Extra ms to wait after idle. Default: 0. |
+| `dom` | boolean | Include rendered DOM. Default: true. |
+| `text` | boolean | Include visible text. Default: true. |
+| `meta` | boolean | Extract JSON-LD, Open Graph, title. Default: true. |
+| `only` | string[] | Whitelist: `screenshots`, `network`, `console`, `dom`, `text`, `meta`. |
+| `burst` | integer | Capture N frames for transition analysis. |
+| `click` | string | CSS selector to click at burst midpoint. |
+| `interactions` | object[] | Scripted interaction sequence (see below). |
+
+### `usage`
+
+Check remaining API quota for the current billing period.
+
+### `feedback`
+
+Submit freeform feedback about Glance.
+
+### `hello`
+
+Service info, capabilities, and free tier details. Works without an API key.
+
+### `signup`
+
+Provision an API key from an email address. The key is stored in memory for the rest of the session.
+
+## Interactions
+
+The `interactions` param on `glance` accepts an array of sequential actions:
+
+```json
+[
+  {"type": "type", "selector": "#search", "value": "query"},
+  {"type": "click", "selector": "#submit"},
+  {"type": "wait", "ms": 2000},
+  {"type": "screenshot", "name": "results"}
+]
+```
+
+| Action | Fields | Description |
+|---|---|---|
+| `wait` | `ms` | Pause (default 1000ms). |
+| `click` | `selector` | Click an element. |
+| `type` | `selector`, `value` | Set an input's value. |
+| `keypress` | `key` | Dispatch a key event. |
+| `eval` | `script` | Run JavaScript in the page. |
+| `screenshot` | `name` | Capture the viewport at this point. |
+
+## Environment variables
+
+| Variable | Description |
+|---|---|
+| `GLANCE_API_KEY` | API key for authenticated methods. |
+| `GLANCE_API_URL` | Override the API endpoint (default: `https://api.glance.tools/v1`). |
+
+## How it works
+
+The server speaks [MCP](https://modelcontextprotocol.io) (Model Context Protocol) over stdio — JSON-RPC 2.0 with newline framing. It's a client of the [Glance hosted API](https://glance.tools), not a replacement for it. No engine, no Chrome, no local browser needed.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@glance-mcp/server",
+  "version": "1.0.0",
+  "description": "MCP server for Glance — capture what a web page looks like and does",
+  "type": "module",
+  "bin": { "glance-mcp": "./src/index.mjs" },
+  "main": "./src/index.mjs",
+  "files": ["src"],
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "homepage": "https://glance.tools",
+  "keywords": ["mcp", "mcp-server", "glance", "screenshot", "web-capture", "model-context-protocol", "claude", "cursor", "web-scraping", "headless-chrome", "llm-tools"]
+}

package/src/api.mjs

@@ -0,0 +1,54 @@
+// JSON-RPC HTTP client for the Glance /v1 endpoint.
+// Zero dependencies — uses Node 18+ global fetch.
+
+const DEFAULT_API_URL = 'https://api.glance.tools/v1';
+
+export function createApiClient({ apiKey, apiUrl } = {}) {
+  let key = apiKey || null;
+  const url = apiUrl || process.env.GLANCE_API_URL || DEFAULT_API_URL;
+
+  async function rpc(method, params) {
+    const body = JSON.stringify({
+      jsonrpc: '2.0',
+      method,
+      params: params || {},
+      id: 1,
+    });
+
+    const headers = { 'Content-Type': 'application/json' };
+    if (key) headers['Authorization'] = `Bearer ${key}`;
+
+    const res = await fetch(url, { method: 'POST', headers, body });
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      const err = new Error(`HTTP ${res.status}: ${text || res.statusText}`);
+      err.code = -32000;
+      throw err;
+    }
+
+    const json = await res.json();
+
+    if (json.error) {
+      const err = new Error(json.error.message);
+      err.code = json.error.code;
+      err.data = json.error.data || null;
+      throw err;
+    }
+
+    return json.result;
+  }
+
+  return {
+    get apiKey() { return key; },
+
+    setApiKey(newKey) { key = newKey; },
+
+    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 }); },
+  };
+}

package/src/index.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+// MCP server for Glance — stdio transport, JSON-RPC 2.0.
+// Zero dependencies. Node 18+ builtins only.
+
+import { createInterface } from 'readline';
+import { createApiClient } from './api.mjs';
+import { tools, handleToolCall } from './tools.mjs';
+
+const SERVER_NAME = 'glance-mcp';
+const SERVER_VERSION = '1.0.0';
+const PROTOCOL_VERSION = '2025-06-18';
+
+// ── API client ──────────────────────────────────────────────────
+
+const api = createApiClient({
+  apiKey: process.env.GLANCE_API_KEY || null,
+  apiUrl: process.env.GLANCE_API_URL || null,
+});
+
+// ── JSON-RPC helpers ────────────────────────────────────────────
+
+function respond(id, result) {
+  const msg = JSON.stringify({ jsonrpc: '2.0', result, id });
+  process.stdout.write(msg + '\n');
+}
+
+function respondError(id, code, message, data) {
+  const err = { code, message };
+  if (data !== undefined) err.data = data;
+  const msg = JSON.stringify({ jsonrpc: '2.0', error: err, id });
+  process.stdout.write(msg + '\n');
+}
+
+// ── Method dispatch ─────────────────────────────────────────────
+
+async function handleMessage(line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    respondError(null, -32700, 'Parse error');
+    return;
+  }
+
+  const { id, method, params } = parsed;
+
+  // Notifications (no id) — acknowledge silently
+  if (id === undefined || id === null) {
+    // notifications/initialized, etc. — no response expected
+    return;
+  }
+
+  switch (method) {
+    case 'initialize':
+      respond(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+      });
+      break;
+
+    case 'ping':
+      respond(id, {});
+      break;
+
+    case 'tools/list':
+      respond(id, { tools });
+      break;
+
+    case 'tools/call': {
+      const toolName = params?.name;
+      const toolArgs = params?.arguments || {};
+      const result = await handleToolCall(toolName, toolArgs, api);
+      respond(id, result);
+      break;
+    }
+
+    default:
+      respondError(id, -32601, 'Method not found', { method });
+  }
+}
+
+// ── stdio transport ─────────────────────────────────────────────
+
+const rl = createInterface({ input: process.stdin });
+
+rl.on('line', (line) => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  handleMessage(trimmed).catch((err) => {
+    process.stderr.write(`[glance-mcp] Unhandled error: ${err.message}\n`);
+  });
+});
+
+rl.on('close', () => {
+  process.exit(0);
+});
+
+process.stderr.write(`[glance-mcp] Server started. Waiting for MCP messages on stdin.\n`);

package/src/tools.mjs

@@ -0,0 +1,308 @@
+// 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}`, ''];
+
+      if (res.artifacts) {
+        const { meta, ...urlArtifacts } = res.artifacts;
+
+        // Screenshot and file URLs
+        for (const [key, value] of Object.entries(urlArtifacts)) {
+          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`);
+      }
+
+      return textResult(lines.join('\n'));
+    }
+
+    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}`);
+  }
+}