mcp-vision-web-bridge 0.2.0

package/.env.example

@@ -0,0 +1,18 @@
+# OpenAI-compatible model endpoint
+MODEL_BASE_URL=https://api.example.com/v1
+MODEL_API_KEY=replace-with-your-own-key
+MODEL_NAME=replace-with-your-vision-model
+
+# Optional upload directories.
+# macOS/Linux default delimiter: :
+# Windows default delimiter: ;
+# Defaults are best-effort Claude Desktop / Cowork local pending upload directories for macOS, Windows, and Linux.
+# CLAUDE_UPLOAD_DIRS=~/Library/Application Support/Claude-3p/pending-uploads:~/Library/Application Support/Claude/pending-uploads
+# CLAUDE_UPLOAD_DIRS_DELIMITER=:
+
+# Safer defaults.
+ALLOW_LOCAL_IMAGE_PATHS=false
+ALLOW_CLIPBOARD_IMAGES=false
+ALLOW_PRIVATE_NETWORK_URLS=false
+USE_JINA_READER=false
+MAX_IMAGE_BYTES=10485760

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.0
+
+- Add MCP prompts for latest uploaded images and clipboard images.
+- Return a non-sensitive image source label with image recognition results.
+- Block private-network image URLs by default.
+- Replace local endpoint defaults with a placeholder API endpoint.
+- Improve provider error messages and redact bearer tokens.
+- Add release-time secret scanning and `prepack` checks.
+
+## 0.1.0
+
+- Initial MCP server with image reading and web link reading tools.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# mcp-vision-web-bridge
+
+Local MCP server that gives Claude Desktop, Claude Code, and other MCP clients two practical bridge tools:
+
+- read an image from a recent Claude upload, clipboard, local path, URL, or base64 input, then send it to an OpenAI-compatible vision model;
+- read web links locally, extract readable text, then send the result to an OpenAI-compatible model.
+
+It does not include a model or any model credits. You bring your own OpenAI-compatible API endpoint and API key.
+
+## Use Cases
+
+- Your Claude client can accept images, but the third-party model behind it does not reliably receive image content.
+- Your model provider supports vision, but your MCP client needs a local tool to collect image inputs.
+- You want a safer local web reader with private-network blocking enabled by default.
+
+## Capabilities
+
+| Capability | macOS | Windows | Linux |
+| --- | --- | --- | --- |
+| MCP server | Supported | Supported | Supported |
+| OpenAI-compatible chat completions | Supported | Supported | Supported |
+| Web page reading | Supported | Supported | Supported |
+| Recent Claude upload image | Supported | Best effort | Best effort |
+| Clipboard image | Supported | Supported via PowerShell / Windows Forms | Supported via `wl-paste` or `xclip` |
+
+Recent Claude upload paths are client implementation details, not a stable public API. If auto-detection does not work in your environment, set `CLAUDE_UPLOAD_DIRS` manually.
+
+## Security Defaults
+
+The default configuration is intentionally conservative:
+
+- `.env` is ignored and should never be committed.
+- API keys are only read from environment variables.
+- Explicit local image paths are disabled unless `ALLOW_LOCAL_IMAGE_PATHS=true`.
+- Clipboard image reading is disabled unless `ALLOW_CLIPBOARD_IMAGES=true`.
+- Private-network web and image URLs are disabled unless `ALLOW_PRIVATE_NETWORK_URLS=true`.
+- Jina Reader fallback is disabled unless `USE_JINA_READER=true`.
+- The server does not log prompts, image data, API keys, or fetched page bodies.
+
+## Requirements
+
+- Node.js 20 or newer
+- npm
+
+This is a Node.js project. It does not require Python or a virtual environment.
+
+## Install
+
+```bash
+npm install
+cp .env.example .env
+```
+
+Edit `.env`:
+
+```bash
+MODEL_BASE_URL=https://api.example.com/v1
+MODEL_API_KEY=replace-with-your-own-key
+MODEL_NAME=replace-with-your-vision-model
+
+ALLOW_LOCAL_IMAGE_PATHS=false
+ALLOW_CLIPBOARD_IMAGES=false
+ALLOW_PRIVATE_NETWORK_URLS=false
+USE_JINA_READER=false
+MAX_IMAGE_BYTES=10485760
+```
+
+`MODEL_BASE_URL` must be an OpenAI-compatible `/v1` endpoint.
+
+### SiliconFlow Example
+
+```bash
+MODEL_BASE_URL=https://api.siliconflow.cn/v1
+MODEL_API_KEY=replace-with-your-own-key
+MODEL_NAME=Qwen/Qwen3-VL-8B-Instruct
+```
+
+Use a model that supports vision input.
+
+## Claude Desktop Config
+
+Use absolute paths for your local checkout:
+
+```json
+{
+  "mcpServers": {
+    "vision-web-bridge": {
+      "command": "node",
+      "args": [
+        "--env-file-if-exists=/absolute/path/to/mcp-vision-web-bridge/.env",
+        "/absolute/path/to/mcp-vision-web-bridge/src/server.mjs"
+      ]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after changing the config.
+
+## Claude Code Config
+
+Add the same server to your Claude Code MCP config. After restart, check `/mcp` and confirm that `vision-web-bridge` is connected.
+
+The server exposes two tools:
+
+- `read_image_with_model`
+- `read_links_with_model`
+
+It also exposes two MCP prompts:
+
+- `/mcp__vision-web-bridge__img`
+- `/mcp__vision-web-bridge__clipboard-image`
+
+## Usage
+
+Read the latest image uploaded to the Claude client:
+
+```text
+Use read_image_with_model with use_latest_upload=true.
+```
+
+Read the current clipboard image:
+
+```text
+Use read_image_with_model with use_clipboard=true and use_latest_upload=false.
+```
+
+Read a local image path after enabling `ALLOW_LOCAL_IMAGE_PATHS=true`:
+
+```text
+Use read_image_with_model with image_path="/absolute/path/to/image.png".
+```
+
+Read web links:
+
+```text
+Use read_links_with_model to summarize https://example.com/article
+```
+
+## Tool Details
+
+### `read_image_with_model`
+
+Supported image sources:
+
+- latest Claude upload;
+- public image URL;
+- base64 image;
+- data URL;
+- local image path, opt-in only;
+- clipboard image, opt-in only.
+
+The tool returns the model response and a non-sensitive source label such as `latest uploaded image`, `clipboard image`, or `local image path`.
+
+### `read_links_with_model`
+
+The tool extracts URLs from the user input, fetches readable page content locally, and asks the configured model to summarize or answer questions.
+
+Private-network URLs are blocked by default. Optional Jina Reader fallback can be enabled with `USE_JINA_READER=true`, which sends the URL to Jina Reader.
+
+## Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `MODEL_BASE_URL` | `https://api.example.com/v1` | OpenAI-compatible `/v1` endpoint |
+| `OPENAI_BASE_URL` | unset | Fallback base URL if `MODEL_BASE_URL` is not set |
+| `MODEL_API_KEY` | unset | API key for the model provider |
+| `MODEL_NAME` | `replace-with-your-vision-model` | Chat or vision model name |
+| `CLAUDE_UPLOAD_DIRS` | client-specific defaults | Override upload directories |
+| `CLAUDE_UPLOAD_DIRS_DELIMITER` | platform default | Directory list delimiter |
+| `ALLOW_LOCAL_IMAGE_PATHS` | `false` | Allow explicit local image paths |
+| `ALLOW_CLIPBOARD_IMAGES` | `false` | Allow reading image data from clipboard |
+| `ALLOW_PRIVATE_NETWORK_URLS` | `false` | Allow private-network web and image URLs |
+| `USE_JINA_READER` | `false` | Allow Jina Reader fallback |
+| `MAX_IMAGE_BYTES` | `10485760` | Maximum image size in bytes |
+
+## Development
+
+```bash
+npm test
+npm run check:secrets
+```
+
+Before publishing, run:
+
+```bash
+npm pack --dry-run
+```
+
+Check the file list carefully. `.env`, logs, images, local screenshots, and personal paths must not be included.
+
+## Windows Notes
+
+- Use full absolute paths in `claude_desktop_config.json`.
+- Save JSON config as UTF-8 without BOM.
+- Restart Claude from the system tray after editing config.
+- Clipboard image reading uses PowerShell / Windows Forms.
+
+## License
+
+MIT

package/SECURITY_REVIEW.md

@@ -0,0 +1,37 @@
+# Security Review Checklist
+
+Use this checklist before publishing or tagging a release.
+
+## Required Checks
+
+- `.env` is present only locally and is not tracked.
+- No real API keys, cookies, tokens, credentials, account IDs, or session data are present.
+- No local screenshots, image caches, logs, downloads, transcripts, or personal drafts are present.
+- No personal filesystem paths are present.
+- No machine-specific network addresses are present in docs, examples, package metadata, or release notes.
+- Local image paths remain disabled by default.
+- Clipboard image reading remains disabled by default.
+- Private-network web and image URLs remain disabled by default.
+- Third-party reader fallback remains disabled by default.
+- Tool errors do not echo bearer tokens or configured API keys.
+
+## Current Security Boundaries
+
+- `read_image_with_model` requires exactly one image source.
+- `image_path` requires `ALLOW_LOCAL_IMAGE_PATHS=true`.
+- `use_clipboard` requires `ALLOW_CLIPBOARD_IMAGES=true`.
+- `image_url` blocks private-network hosts unless explicitly enabled.
+- `read_links_with_model` blocks private-network hosts unless explicitly enabled.
+- Jina Reader fallback requires `USE_JINA_READER=true`.
+- The tool returns a non-sensitive image source label, not local file paths.
+- The server does not intentionally log prompts, image content, API keys, or fetched web content.
+
+## Release Commands
+
+```bash
+npm test
+npm run check:secrets
+npm pack --dry-run
+```
+
+Manually inspect the `npm pack --dry-run` file list before publishing.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "mcp-vision-web-bridge",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "A local MCP server that adds image understanding and web-page reading through an OpenAI-compatible model API.",
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY_REVIEW.md",
+    "LICENSE",
+    ".env.example",
+    "scripts"
+  ],
+  "bin": {
+    "mcp-vision-web-bridge": "src/server.mjs"
+  },
+  "scripts": {
+    "start": "node --env-file-if-exists=.env src/server.mjs",
+    "test": "node --test",
+    "check:secrets": "node scripts/check-secrets.mjs",
+    "prepack": "npm test && npm run check:secrets"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {}
+}

package/scripts/check-secrets.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+
+const ROOT = process.cwd();
+const EXCLUDED_DIRS = new Set(['.git', '.claude', 'node_modules', 'coverage', 'dist']);
+const EXCLUDED_FILES = new Set(['.env', 'package-lock.json', 'scripts/check-secrets.mjs']);
+const SECRET_PATTERNS = [
+  ['OpenAI-style API key', /sk-[A-Za-z0-9_-]{16,}/],
+  ['Slack token', /xox[baprs]-/],
+  ['GitHub token', /gh[pousr]_[A-Za-z0-9_]{20,}/],
+  ['AWS access key', /AKIA[0-9A-Z]{16}/],
+  ['Bearer token', /Bearer\s+[A-Za-z0-9._~+/=-]{16,}/],
+  ['personal absolute path', /\/Users\/[^\s"'`]+/]
+];
+
+const findings = [];
+
+await scanDir(ROOT);
+
+if (findings.length) {
+  for (const finding of findings) {
+    console.error(`${finding.file}:${finding.line}: ${finding.kind}`);
+  }
+  process.exitCode = 1;
+}
+
+async function scanDir(dir) {
+  const entries = await readdir(dir, {
+    withFileTypes: true
+  });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    const relPath = relative(ROOT, fullPath) || entry.name;
+
+    if (entry.isDirectory()) {
+      if (EXCLUDED_DIRS.has(entry.name)) continue;
+      await scanDir(fullPath);
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+    if (EXCLUDED_FILES.has(relPath) || relPath.endsWith('.tgz')) continue;
+
+    await scanFile(fullPath, relPath);
+  }
+}
+
+async function scanFile(fullPath, relPath) {
+  const info = await stat(fullPath);
+  if (info.size > 2 * 1024 * 1024) return;
+
+  let text;
+  try {
+    text = await readFile(fullPath, 'utf8');
+  } catch {
+    return;
+  }
+
+  const lines = text.split(/\r?\n/);
+  for (const [index, line] of lines.entries()) {
+    for (const [kind, pattern] of SECRET_PATTERNS) {
+      if (pattern.test(line)) {
+        findings.push({
+          file: relPath,
+          line: index + 1,
+          kind
+        });
+      }
+    }
+  }
+}