opuscode-mcp 1.0.0

package/README.md

@@ -0,0 +1,144 @@
+# OpusCode MCP
+
+MCP (Model Context Protocol) server that provides **web search** and **image understanding** tools for AI coding agents — Claude Code, Cursor, OpenCode, and more.
+
+## Quick Install
+
+### Claude Code (recommended)
+
+```bash
+claude mcp add -s user OpusCode \
+  --env OPUSCODE_API_KEY=your_key \
+  --env OPUSCODE_URL=https://your-server.com \
+  -- npx opuscode-mcp
+```
+
+### Global install
+
+```bash
+npm install -g opuscode-mcp
+```
+
+## Manual Configuration
+
+### Claude Code
+
+Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "OpusCode": {
+      "command": "npx",
+      "args": ["opuscode-mcp"],
+      "env": {
+        "OPUSCODE_API_KEY": "your_key",
+        "OPUSCODE_URL": "https://your-server.com"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to Cursor MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "OpusCode": {
+      "command": "npx",
+      "args": ["opuscode-mcp"],
+      "env": {
+        "OPUSCODE_API_KEY": "your_key",
+        "OPUSCODE_URL": "https://your-server.com"
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+Add to your OpenCode config:
+
+```json
+{
+  "mcp": {
+    "OpusCode": {
+      "command": "npx",
+      "args": ["opuscode-mcp"],
+      "env": {
+        "OPUSCODE_API_KEY": "your_key",
+        "OPUSCODE_URL": "https://your-server.com"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `web_search` | Search the web for real-time information. Best with 3–5 keywords. |
+| `understand_image` | Analyze images using AI. Accepts URLs, local file paths, or base64 data URLs. |
+
+## Usage Examples
+
+### Web Search
+
+```
+Search for: "Node.js 22 new features 2025"
+```
+
+The `web_search` tool accepts a `query` string and returns structured search results from the web.
+
+### Image Understanding
+
+```
+Prompt: "Describe this UI mockup and list all the components"
+Image source: "./screenshot.png"
+```
+
+The `understand_image` tool accepts:
+
+- **`prompt`** — What you want to know about the image
+- **`image_source`** — One of:
+  - An HTTP/HTTPS URL (`https://example.com/image.png`)
+  - A local file path (`./diagram.png` or `/home/user/photo.jpg`)
+  - A base64 data URL (`data:image/png;base64,...`)
+
+Supported formats: JPEG, PNG, WebP, GIF, BMP, SVG.
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `OPUSCODE_API_KEY` | Yes | — | API key for authentication |
+| `OPUSCODE_URL` | No | `http://localhost:3001` | OpusCode proxy server URL |
+
+## Troubleshooting
+
+### "Error: Proxy request failed: 401"
+
+Your `OPUSCODE_API_KEY` is missing or invalid. Make sure it's set in your environment or MCP config.
+
+### "Error: Proxy request failed: ECONNREFUSED"
+
+The OpusCode proxy server is not running or `OPUSCODE_URL` points to the wrong address. Verify the server is up and the URL is correct.
+
+### "Error: File not found"
+
+When using `understand_image` with a local file path, ensure the path is correct relative to where the MCP server process is running.
+
+### Tools not showing up
+
+1. Restart your AI coding tool after adding the MCP config.
+2. Check that `npx opuscode-mcp` runs without errors in your terminal.
+3. Verify your MCP config JSON is valid.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { CallToolRequestSchema, ListToolsRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
+const fs = require('fs');
+const path = require('path');
+
+const API_KEY = process.env.OPUSCODE_API_KEY || '';
+const BASE_URL = (process.env.OPUSCODE_URL || 'http://localhost:3001').replace(/\/+$/, '');
+
+const MIME_TYPES = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.svg': 'image/svg+xml',
+};
+
+async function processImageSource(imageSource) {
+  let source = imageSource.trim();
+
+  // Strip leading @ (common in curl-style references)
+  if (source.startsWith('@')) {
+    source = source.slice(1);
+  }
+
+  // Already a data URL — pass through
+  if (source.startsWith('data:')) {
+    return source;
+  }
+
+  // HTTP(S) URL — download and convert
+  if (source.startsWith('http://') || source.startsWith('https://')) {
+    const res = await fetch(source);
+    if (!res.ok) {
+      throw new Error(`Failed to download image: ${res.status} ${res.statusText}`);
+    }
+    const contentType = res.headers.get('content-type') || 'image/png';
+    const buffer = Buffer.from(await res.arrayBuffer());
+    const base64 = buffer.toString('base64');
+    return `data:${contentType};base64,${base64}`;
+  }
+
+  // Local file path
+  const resolved = path.resolve(source);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`File not found: ${resolved}`);
+  }
+  const ext = path.extname(resolved).toLowerCase();
+  const mime = MIME_TYPES[ext] || 'image/png';
+  const fileBuffer = fs.readFileSync(resolved);
+  const base64 = fileBuffer.toString('base64');
+  return `data:${mime};base64,${base64}`;
+}
+
+async function callProxy(endpoint, body) {
+  const url = `${BASE_URL}${endpoint}`;
+  const headers = { 'Content-Type': 'application/json' };
+  if (API_KEY) {
+    headers['Authorization'] = `Bearer ${API_KEY}`;
+  }
+
+  const res = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Proxy request failed: ${res.status} ${res.statusText} — ${text}`);
+  }
+
+  return res.json();
+}
+
+const server = new Server(
+  { name: 'opuscode-mcp', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'web_search',
+      description:
+        'Search the web for real-time information. Use 3-5 keywords for best results. For time-sensitive topics, include the current date.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Search query (3-5 keywords recommended)',
+          },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: 'understand_image',
+      description:
+        'Analyze images with AI. Supports JPEG, PNG, WebP. Accepts HTTP URLs, local file paths, or base64 data URLs.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          prompt: {
+            type: 'string',
+            description: 'What you want to know about the image',
+          },
+          image_source: {
+            type: 'string',
+            description:
+              'Image source: an HTTP/HTTPS URL, a local file path, or a base64 data URL',
+          },
+        },
+        required: ['prompt', 'image_source'],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    if (name === 'web_search') {
+      const { query } = args;
+      if (!query) {
+        return { content: [{ type: 'text', text: 'Error: "query" parameter is required.' }], isError: true };
+      }
+
+      const result = await callProxy('/tools/web_search', { query });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+
+    if (name === 'understand_image') {
+      const { prompt, image_source } = args;
+      if (!prompt || !image_source) {
+        return {
+          content: [{ type: 'text', text: 'Error: "prompt" and "image_source" parameters are required.' }],
+          isError: true,
+        };
+      }
+
+      const imageUrl = await processImageSource(image_source);
+      const result = await callProxy('/tools/understand_image', { prompt, image_url: imageUrl });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+
+    return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('Fatal error starting OpusCode MCP server:', err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "opuscode-mcp",
+  "version": "1.0.0",
+  "description": "OpusCode MCP server — web search and image understanding tools for AI coding agents",
+  "main": "index.js",
+  "bin": {
+    "opuscode-mcp": "./index.js"
+  },
+  "keywords": ["mcp", "opuscode", "web-search", "image-understanding", "ai-coding"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}