web-refinery-mcp 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# Web Refinery MCP Server
+
+MCP server that gives AI assistants the ability to extract clean content from any URL via the Web Refinery API. Payments are handled automatically using x402 USDC on Base.
+
+## Tools
+
+| Tool | Cost | Description |
+|------|------|-------------|
+| `web_refinery_basic` | $0.003 USDC | Title, markdown content, word count, reading time |
+| `web_refinery_structured` | $0.005 USDC | Full metadata: author, date, language, site name, etc. |
+
+## Setup
+
+```bash
+cd mcp-server
+npm install
+```
+
+You need a wallet with Base mainnet ETH (gas) and USDC (payment).
+
+## Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "web-refinery": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/index.js"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "web-refinery": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/index.js"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Claude Code
+
+Add to `~/.claude/claude_code_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "web-refinery": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/index.js"],
+      "env": {
+        "EVM_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `EVM_PRIVATE_KEY` | Yes | — | 0x-prefixed private key with Base USDC |
+| `WEB_REFINERY_URL` | No | Production URL | API base URL override |
+
+## How It Works
+
+1. AI assistant calls `web_refinery_basic` or `web_refinery_structured` with a URL
+2. MCP server sends request to Web Refinery API
+3. API returns HTTP 402 with x402 payment requirements
+4. `@x402/axios` automatically signs a USDC payment and retries
+5. Clean article content is returned to the assistant

package/index.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * Web Refinery MCP Server
+ *
+ * Exposes Web Refinery API as MCP tools for Claude Desktop, Cursor, etc.
+ * Uses @x402/axios for automatic USDC payment on Base mainnet.
+ *
+ * Environment:
+ *   EVM_PRIVATE_KEY  - 0x-prefixed Base wallet private key with USDC
+ *   WEB_REFINERY_URL - API base URL (optional)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import axios from 'axios';
+import { wrapAxiosWithPayment, x402Client } from '@x402/axios';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { privateKeyToAccount } from 'viem/accounts';
+import { z } from 'zod';
+
+const EVM_PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;
+const BASE_URL = process.env.WEB_REFINERY_URL || 'https://web-refinery-407929312862.asia-northeast3.run.app';
+
+function createApi() {
+  const instance = axios.create({
+    baseURL: BASE_URL,
+    timeout: 15_000,
+  });
+
+  if (!EVM_PRIVATE_KEY) {
+    console.error('[web-refinery-mcp] Warning: EVM_PRIVATE_KEY not set — x402 payments will fail');
+    return instance;
+  }
+
+  const account = privateKeyToAccount(EVM_PRIVATE_KEY);
+  const client = new x402Client();
+  client.register('eip155:*', new ExactEvmScheme(account));
+  return wrapAxiosWithPayment(instance, client);
+}
+
+function formatResult(data) {
+  const d = data.data;
+  const meta = data.meta;
+  const lines = [];
+
+  lines.push(`# ${d.title}`);
+  lines.push('');
+
+  if (d.author) lines.push(`**Author:** ${d.author}`);
+  if (d.publishedAt) lines.push(`**Published:** ${d.publishedAt}`);
+  if (d.siteName) lines.push(`**Site:** ${d.siteName}`);
+  if (d.language) lines.push(`**Language:** ${d.language}`);
+  lines.push(`**Words:** ${d.wordCount} | **Reading time:** ${d.readingTime} min | **Type:** ${d.contentType}`);
+  if (d.warning) lines.push(`**Warning:** ${d.warning}`);
+  lines.push(`**Processed in:** ${meta.processingMs}ms`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  lines.push(d.content.markdown);
+
+  return lines.join('\n');
+}
+
+function formatError(err) {
+  if (err.response) {
+    const body = err.response.data;
+    const code = body?.error?.code || `HTTP_${err.response.status}`;
+    const msg = body?.error?.message || err.message;
+    return `Error [${code}]: ${msg}`;
+  }
+  if (err.code === 'ECONNABORTED') {
+    return 'Error [TIMEOUT]: Request timed out after 15s';
+  }
+  return `Error: ${err.message}`;
+}
+
+async function main() {
+  const api = createApi();
+  const server = new McpServer({
+    name: 'web-refinery',
+    version: '0.1.0',
+  });
+
+  server.tool(
+    'web_refinery_basic',
+    'Extract clean article content from any URL. Removes ads, navigation, and noise. Returns title, markdown content, word count, and reading time. Costs $0.003 USDC per request.',
+    { url: z.string().describe('The webpage URL to extract content from') },
+    async ({ url }) => {
+      try {
+        const resp = await api.get('/v1/refine', { params: { url, format: 'basic' } });
+        return { content: [{ type: 'text', text: formatResult(resp.data) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: formatError(err) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    'web_refinery_structured',
+    'Extract detailed article content from any URL with full metadata. Returns title, author, publish date, markdown content, word count, language, and more. Costs $0.005 USDC per request.',
+    { url: z.string().describe('The webpage URL to extract content from') },
+    async ({ url }) => {
+      try {
+        const resp = await api.get('/v1/refine', { params: { url, format: 'structured' } });
+        return { content: [{ type: 'text', text: formatResult(resp.data) }] };
+      } catch (err) {
+        return { content: [{ type: 'text', text: formatError(err) }], isError: true };
+      }
+    },
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(err => {
+  console.error('[web-refinery-mcp] Fatal:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "web-refinery-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Web Refinery API — clean web content extraction with x402 USDC payments",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "web-refinery-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "@x402/axios": "^2.6.0",
+    "@x402/evm": "^2.6.0",
+    "axios": "^1.7.0",
+    "viem": "^2.0.0"
+  }
+}