mcp-vision-web-bridge 0.2.0

package/src/server.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { askModel, askModelWithImage } from './model-client.mjs';
+import { buildWebContext, extractUrls } from './web-reader.mjs';
+
+const DEFAULT_MODEL = process.env.MODEL_NAME || 'replace-with-your-vision-model';
+const packageInfo = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+const server = new McpServer({
+  name: 'mcp-vision-web-bridge',
+  version: packageInfo.version
+});
+
+server.registerTool(
+  'read_image_with_model',
+  {
+    title: 'Read Image With Model',
+    description:
+      'Read an image from the latest Claude upload, an image URL, base64, an allowed local path, or clipboard, then send it to the configured vision-capable model.',
+    inputSchema: {
+      prompt: z.string().default('Please describe this image. If it contains text, extract the text.'),
+      image_path: z.string().optional().describe('Local image path. Disabled unless ALLOW_LOCAL_IMAGE_PATHS=true.'),
+      image_url: z.string().optional().describe('HTTP/HTTPS image URL or data URL.'),
+      image_base64: z.string().optional().describe('Raw base64 or data URL.'),
+      mime_type: z.string().default('image/png').describe('MIME type for raw base64 input.'),
+      use_latest_upload: z.boolean().default(true).describe('When no image source is provided, read the newest recent Claude upload.'),
+      use_clipboard: z.boolean().default(false).describe('Read macOS clipboard image. Disabled unless ALLOW_CLIPBOARD_IMAGES=true.'),
+      max_age_minutes: z.number().int().min(1).max(1440).default(240),
+      model: z.string().default(DEFAULT_MODEL),
+      max_tokens: z.number().int().min(64).max(32768).default(8192),
+      temperature: z.number().min(0).max(2).optional()
+    }
+  },
+  async ({
+    prompt,
+    image_path: imagePath,
+    image_url: imageUrl,
+    image_base64: imageBase64,
+    mime_type: mimeType,
+    use_latest_upload: useLatestUpload,
+    use_clipboard: useClipboard,
+    max_age_minutes: maxAgeMinutes,
+    model,
+    max_tokens: maxTokens,
+    temperature
+  }) => {
+    const hasExplicitImage = Boolean(imagePath || imageUrl || imageBase64 || useClipboard);
+    const result = await askModelWithImage({
+      prompt,
+      imagePath,
+      imageUrl,
+      imageBase64,
+      mimeType,
+      fromClipboard: useClipboard,
+      latestClaudeUpload: !hasExplicitImage && useLatestUpload,
+      maxAgeMinutes,
+      model,
+      maxTokens,
+      temperature
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: [`Image source: ${formatImageSource(result.source)}`, '', result.text].join('\n')
+        }
+      ]
+    };
+  }
+);
+
+server.registerPrompt(
+  'img',
+  {
+    title: 'Read latest uploaded image',
+    description: 'Ask the vision MCP tool to read the latest image uploaded to the client.',
+    argsSchema: {
+      prompt: z.string().optional().describe('What to analyze in the image')
+    }
+  },
+  async ({ prompt }) => ({
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: [
+            'Use the MCP tool `read_image_with_model` with `use_latest_upload=true` and `use_clipboard=false`.',
+            `Prompt: ${prompt || 'Please describe this image. If it contains text, extract the text.'}`
+          ].join('\n')
+        }
+      }
+    ]
+  })
+);
+
+server.registerPrompt(
+  'clipboard-image',
+  {
+    title: 'Read clipboard image',
+    description: 'Ask the vision MCP tool to read the current clipboard image.',
+    argsSchema: {
+      prompt: z.string().optional().describe('What to analyze in the image')
+    }
+  },
+  async ({ prompt }) => ({
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text: [
+            'Use the MCP tool `read_image_with_model` with `use_clipboard=true` and `use_latest_upload=false`.',
+            `Prompt: ${prompt || 'Please describe this image. If it contains text, extract the text.'}`
+          ].join('\n')
+        }
+      }
+    ]
+  })
+);
+
+server.registerTool(
+  'read_links_with_model',
+  {
+    title: 'Read Links With Model',
+    description:
+      'Extract web links from user input, fetch readable page content locally, then ask the configured model to summarize, translate, or answer questions.',
+    inputSchema: {
+      input: z.string().min(1).describe('User request containing one or more URLs.'),
+      instruction: z.string().default('Please read these links, summarize the main points, and answer the user request.'),
+      max_urls: z.number().int().min(1).max(8).default(5),
+      max_chars_per_url: z.number().int().min(1000).max(60000).default(24000),
+      model: z.string().default(DEFAULT_MODEL),
+      max_tokens: z.number().int().min(64).max(32768).default(8192),
+      temperature: z.number().min(0).max(2).optional()
+    }
+  },
+  async ({
+    input,
+    instruction,
+    max_urls: maxUrls,
+    max_chars_per_url: maxCharsPerUrl,
+    model,
+    max_tokens: maxTokens,
+    temperature
+  }) => {
+    const urls = extractUrls(input);
+    if (!urls.length) {
+      throw new Error('No URLs found in input');
+    }
+
+    const webContext = await buildWebContext(input, {
+      maxUrls,
+      maxCharsPerUrl
+    });
+    const prompt = [
+      instruction,
+      '',
+      'User request:',
+      input,
+      '',
+      'Fetched web content:',
+      webContext.text
+    ].join('\n');
+    const text = await askModel({
+      prompt,
+      model,
+      maxTokens,
+      temperature
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text
+        }
+      ]
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+function formatImageSource(source) {
+  if (!source?.type) return 'unknown';
+  if (source.type === 'latest_upload') return 'latest uploaded image';
+  if (source.type === 'clipboard') return 'clipboard image';
+  if (source.type === 'local_path') return 'local image path';
+  if (source.type === 'image_url') return 'image URL';
+  if (source.type === 'data_url') return 'data URL';
+  if (source.type === 'base64') return 'base64 image';
+  return source.type;
+}

package/src/web-reader.mjs

@@ -0,0 +1,371 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { isIP } from 'node:net';
+import { promisify } from 'node:util';
+
+const execFile = promisify(execFileCallback);
+
+const DEFAULT_USER_AGENT =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36';
+
+const DEFAULT_MAX_CHARS_PER_URL = 24000;
+const DEFAULT_MAX_URLS = 5;
+const DEFAULT_TIMEOUT_MS = 20000;
+
+const ENTITY_MAP = new Map([
+  ['amp', '&'],
+  ['lt', '<'],
+  ['gt', '>'],
+  ['quot', '"'],
+  ['apos', "'"],
+  ['nbsp', ' ']
+]);
+
+export function extractUrls(text) {
+  if (!text || typeof text !== 'string') {
+    return [];
+  }
+
+  const seen = new Set();
+  const matches = text.match(/https?:\/\/[^\s<>"'`，。！？、；：]+/g) || [];
+  const urls = [];
+
+  for (const match of matches) {
+    const url = trimUrl(match);
+    if (!url || seen.has(url)) continue;
+    seen.add(url);
+    urls.push(url);
+  }
+
+  return urls;
+}
+
+export function htmlToReadableText(html, { maxChars = DEFAULT_MAX_CHARS_PER_URL } = {}) {
+  if (!html || typeof html !== 'string') {
+    return '';
+  }
+
+  const title = decodeHtmlEntities(extractTitle(html));
+  const text = decodeHtmlEntities(
+    html
+      .replace(/<!--[\s\S]*?-->/g, ' ')
+      .replace(/<script\b[\s\S]*?<\/script>/gi, ' ')
+      .replace(/<style\b[\s\S]*?<\/style>/gi, ' ')
+      .replace(/<noscript\b[\s\S]*?<\/noscript>/gi, ' ')
+      .replace(/<svg\b[\s\S]*?<\/svg>/gi, ' ')
+      .replace(/<canvas\b[\s\S]*?<\/canvas>/gi, ' ')
+      .replace(/<\/?(?:article|aside|blockquote|br|dd|div|dl|dt|figcaption|figure|footer|form|h[1-6]|header|hr|li|main|nav|ol|p|pre|section|table|tbody|td|tfoot|th|thead|tr|ul)\b[^>]*>/gi, '\n')
+      .replace(/<[^>]+>/g, ' ')
+  );
+  const lines = text
+    .split(/\n+/)
+    .map((line) => line.replace(/[ \t\f\v]+/g, ' ').trim())
+    .filter(Boolean);
+  const body = truncate(lines.join('\n'), maxChars);
+
+  return [title ? `Title: ${title}` : '', body].filter(Boolean).join('\n\n');
+}
+
+export async function fetchReadableUrl(
+  url,
+  {
+    fetchImpl = fetch,
+    maxChars = DEFAULT_MAX_CHARS_PER_URL,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    useJinaFallback = process.env.USE_JINA_READER === 'true',
+    allowPrivateNetworkUrls = process.env.ALLOW_PRIVATE_NETWORK_URLS === 'true'
+  } = {}
+) {
+  validateHttpUrl(url, {
+    allowPrivateNetworkUrls
+  });
+
+  let primary;
+
+  try {
+    primary = await fetchReadableUrlOnce(url, {
+      fetchImpl,
+      maxChars,
+      timeoutMs
+    });
+  } catch (error) {
+    if (!useJinaFallback) {
+      throw error;
+    }
+
+    const fallback = await fetchReadableUrlOnce(toJinaReaderUrl(url), {
+      fetchImpl,
+      maxChars,
+      timeoutMs
+    });
+
+    return {
+      ...fallback,
+      url,
+      fetchedUrl: fallback.url,
+      reader: 'jina'
+    };
+  }
+
+  const needsFallback = shouldUseJinaFallback(primary);
+  if (!needsFallback || !useJinaFallback) {
+    return primary;
+  }
+
+  try {
+    const fallback = await fetchReadableUrlOnce(toJinaReaderUrl(url), {
+      fetchImpl,
+      maxChars,
+      timeoutMs
+    });
+
+    if (fallback.ok && (needsFallback || fallback.text.length >= primary.text.length)) {
+      return {
+        ...fallback,
+        url,
+        fetchedUrl: fallback.url,
+        reader: 'jina'
+      };
+    }
+  } catch {
+    // Keep the primary result when the optional reader is unavailable.
+  }
+
+  return primary;
+}
+
+export async function buildWebContext(
+  input,
+  {
+    fetchImpl = fetch,
+    maxUrls = DEFAULT_MAX_URLS,
+    maxCharsPerUrl = DEFAULT_MAX_CHARS_PER_URL,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    useJinaFallback = process.env.USE_JINA_READER === 'true'
+  } = {}
+) {
+  const urls = extractUrls(input).slice(0, maxUrls);
+  const pages = [];
+
+  for (const url of urls) {
+    try {
+      const page = await fetchReadableUrl(url, {
+        fetchImpl,
+        maxChars: maxCharsPerUrl,
+        timeoutMs,
+        useJinaFallback
+      });
+      pages.push(page);
+    } catch (error) {
+      pages.push({
+        url,
+        status: 0,
+        ok: false,
+        text: `读取失败：${error.message}`
+      });
+    }
+  }
+
+  return {
+    urls,
+    pages,
+    text: pages
+      .map((page, index) => {
+        const status = page.status ? `Status: ${page.status}` : 'Status: failed';
+        return [`Source ${index + 1}: ${page.url}`, status, page.text].join('\n');
+      })
+      .join('\n\n---\n\n')
+  };
+}
+
+async function fetchReadableUrlOnce(url, { fetchImpl, maxChars, timeoutMs }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    let response;
+
+    try {
+      response = await fetchImpl(url, {
+        redirect: 'follow',
+        signal: controller.signal,
+        headers: {
+          'user-agent': DEFAULT_USER_AGENT,
+          accept: 'text/html,application/xhtml+xml,application/xml,text/plain,application/json,*/*;q=0.8',
+          'accept-language': 'zh-CN,zh;q=0.9,en;q=0.8'
+        }
+      });
+    } catch (error) {
+      if (fetchImpl !== fetch) {
+        throw error;
+      }
+
+      return fetchReadableUrlWithCurl(url, {
+        maxChars,
+        timeoutMs
+      });
+    }
+
+    const contentType = response.headers.get('content-type') || '';
+    const body = await response.text();
+    const text = normalizeResponseText(body, contentType, maxChars);
+
+    return {
+      url,
+      fetchedUrl: response.url || url,
+      status: response.status,
+      ok: response.ok,
+      contentType,
+      text
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function fetchReadableUrlWithCurl(url, { maxChars, timeoutMs }) {
+  const marker = '\n__MCP_WEB_READER_META__\n';
+  const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+  const { stdout } = await execFile(
+    'curl',
+    [
+      '-sS',
+      '-L',
+      '--max-time',
+      String(timeoutSeconds),
+      '-A',
+      DEFAULT_USER_AGENT,
+      '-H',
+      'Accept: text/html,application/xhtml+xml,application/xml,text/plain,application/json,*/*;q=0.8',
+      '-H',
+      'Accept-Language: zh-CN,zh;q=0.9,en;q=0.8',
+      '-w',
+      `${marker}%{http_code}\n%{content_type}\n%{url_effective}`,
+      url
+    ],
+    {
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+      timeout: timeoutMs + 5000
+    }
+  );
+  const markerIndex = stdout.lastIndexOf(marker);
+
+  if (markerIndex === -1) {
+    throw new Error('curl did not return response metadata');
+  }
+
+  const body = stdout.slice(0, markerIndex);
+  const [statusLine = '0', contentType = '', effectiveUrl = url] = stdout
+    .slice(markerIndex + marker.length)
+    .split('\n');
+  const status = Number.parseInt(statusLine, 10) || 0;
+
+  return {
+    url,
+    fetchedUrl: effectiveUrl,
+    status,
+    ok: status >= 200 && status < 300,
+    contentType,
+    text: normalizeResponseText(body, contentType, maxChars)
+  };
+}
+
+function normalizeResponseText(body, contentType, maxChars) {
+  if (contentType.includes('text/html') || /<\/?[a-z][\s\S]*>/i.test(body)) {
+    return htmlToReadableText(body, {
+      maxChars
+    });
+  }
+
+  if (contentType.includes('application/json')) {
+    try {
+      return truncate(JSON.stringify(JSON.parse(body), null, 2), maxChars);
+    } catch {
+      return truncate(body, maxChars);
+    }
+  }
+
+  return truncate(body.replace(/\r\n/g, '\n').replace(/[ \t\f\v]+/g, ' ').trim(), maxChars);
+}
+
+function shouldUseJinaFallback(page) {
+  if (page.reader === 'jina') return false;
+  if (!page.ok) return true;
+  if (/application\/pdf/i.test(page.contentType)) return true;
+  if (
+    page.text.length < 1000 &&
+    /<script|enable javascript|captcha|access denied|cloudflare|something went wrong|try again|privacy related extensions|don.t miss what.s happening/i.test(
+      page.text
+    )
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function toJinaReaderUrl(url) {
+  return `https://r.jina.ai/${url}`;
+}
+
+function extractTitle(html) {
+  return html.match(/<title\b[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/<[^>]+>/g, ' ').trim() || '';
+}
+
+function decodeHtmlEntities(text) {
+  return text.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (entity, raw) => {
+    const lower = raw.toLowerCase();
+    if (lower.startsWith('#x')) {
+      return String.fromCodePoint(Number.parseInt(lower.slice(2), 16));
+    }
+    if (lower.startsWith('#')) {
+      return String.fromCodePoint(Number.parseInt(lower.slice(1), 10));
+    }
+    return ENTITY_MAP.get(lower) ?? entity;
+  });
+}
+
+function truncate(text, maxChars) {
+  if (text.length <= maxChars) {
+    return text;
+  }
+
+  return `${text.slice(0, maxChars)}\n\n[Truncated]`;
+}
+
+function validateHttpUrl(url, { allowPrivateNetworkUrls }) {
+  const parsed = new URL(url);
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error('Only http and https URLs are supported');
+  }
+
+  if (!allowPrivateNetworkUrls && isPrivateHostname(parsed.hostname)) {
+    throw new Error('Private network URLs are disabled by default');
+  }
+}
+
+function isPrivateHostname(hostname) {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  if (normalized === 'localhost' || normalized.endsWith('.localhost')) return true;
+
+  const ipVersion = isIP(normalized);
+  if (!ipVersion) return false;
+
+  if (ipVersion === 6) {
+    return normalized === '::1' || normalized.startsWith('fc') || normalized.startsWith('fd') || normalized.startsWith('fe80:');
+  }
+
+  const parts = normalized.split('.').map((part) => Number.parseInt(part, 10));
+  const [a, b] = parts;
+  return (
+    a === 10 ||
+    a === 127 ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    a === 0
+  );
+}
+
+function trimUrl(value) {
+  return value.replace(/[，。！？、；：,.!?;:)\]}>]+$/g, '');
+}