skim-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skim
+
+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,137 @@
+# skim-mcp
+
+MCP (Model Context Protocol) server for [Skim](https://skim402.com) — clean web
+reader for AI agents. Pays **$0.002 per call in USDC on Base** over the
+[x402](https://x402.org) protocol. No signup. No API keys. No monthly bills.
+
+Give your agent the ability to read any URL and get back clean, agent-ready
+Markdown (no nav, no ads, no boilerplate) plus structured metadata (title,
+byline, published date, language, excerpt).
+
+## What you need
+
+1. **Node.js 18+**
+2. A **Base wallet private key** with a small amount of **USDC** in it. A dollar
+   funds ~500 reads. Use a fresh wallet — not your personal one.
+
+> Don't have one? Create a key with `cast wallet new` (Foundry) or any EVM
+> wallet, then send USDC to it on Base mainnet from Coinbase, an exchange, or
+> another wallet.
+
+## Install in Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "skim": {
+      "command": "npx",
+      "args": ["-y", "skim-mcp"],
+      "env": {
+        "SKIM_WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see a new `read_url` tool. Ask Claude to read
+any article and it'll fetch it through Skim and pay automatically.
+
+## Install in Cursor
+
+Edit `~/.cursor/mcp.json` (or the in-app **Settings → MCP** panel):
+
+```json
+{
+  "mcpServers": {
+    "skim": {
+      "command": "npx",
+      "args": ["-y", "skim-mcp"],
+      "env": {
+        "SKIM_WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
+      }
+    }
+  }
+}
+```
+
+## Install in Cline / Continue / Zed
+
+All MCP-compatible clients use the same shape. Run the binary as:
+
+```bash
+npx skim-mcp
+```
+
+with the same `SKIM_WALLET_PRIVATE_KEY` env var.
+
+## Tools
+
+### `read_url`
+
+Reads any URL and returns clean Markdown plus a YAML frontmatter block with
+metadata.
+
+**Input:**
+
+```json
+{ "url": "https://example.com/article" }
+```
+
+**Output (text):**
+
+```
+---
+title: Example article
+byline: Jane Doe
+published: 2025-01-15
+lang: en
+excerpt: A short summary...
+---
+
+# Example article
+
+The cleaned article body in Markdown...
+```
+
+## Environment variables
+
+| Variable                   | Required | Default                | Notes                                                                                                                          |
+| -------------------------- | -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `SKIM_WALLET_PRIVATE_KEY`  | **yes**  | —                      | Hex private key for the Base wallet that pays for reads. With or without `0x` prefix.                                          |
+| `SKIM_MAX_PRICE_USD`       | no       | `0.01`                 | Maximum USD per call. Caps how much the wallet will sign for in a single read. Skim is currently $0.002/call, well under this. |
+| `SKIM_API_URL`             | no       | `https://skim402.com`  | Override the API base URL. Mostly for development.                                                                             |
+
+## Security
+
+- Use a **dedicated wallet**, not your personal one. Fund it with only as much
+  USDC as you're willing to spend.
+- The private key never leaves your machine. It's only used locally to sign
+  EIP-3009 payment authorizations consumed by the Skim API.
+- Sweep the receive side periodically if you're running Skim yourself.
+
+## How it works
+
+1. The MCP server receives a `read_url` call from your AI agent.
+2. It POSTs to `https://skim402.com/api/v1/read`.
+3. The server replies `402 Payment Required` with x402 payment details.
+4. [`x402-fetch`](https://www.npmjs.com/package/x402-fetch) signs an EIP-3009
+   USDC transfer authorization using your wallet, attaches it as the
+   `X-PAYMENT` header, and retries.
+5. Skim verifies + settles via the Coinbase CDP facilitator and returns the
+   cleaned content.
+
+End-to-end latency is typically <2 seconds.
+
+## Links
+
+- Skim — https://skim402.com
+- x402 protocol — https://x402.org
+- Model Context Protocol — https://modelcontextprotocol.io
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { privateKeyToAccount } from "viem/accounts";
+import { wrapFetchWithPayment } from "x402-fetch";
+import { z } from "zod";
+const BASE_URL = (process.env.SKIM_API_URL ?? "https://skim402.com").replace(/\/+$/, "");
+const PRIVATE_KEY = process.env.SKIM_WALLET_PRIVATE_KEY;
+const MAX_PRICE_USD = process.env.SKIM_MAX_PRICE_USD ?? "0.01";
+let payFetch = fetch;
+let walletAddress = null;
+if (PRIVATE_KEY) {
+    const normalized = PRIVATE_KEY.startsWith("0x")
+        ? PRIVATE_KEY.slice(2)
+        : PRIVATE_KEY;
+    if (!/^[0-9a-fA-F]{64}$/.test(normalized)) {
+        process.stderr.write("skim-mcp: SKIM_WALLET_PRIVATE_KEY must be a 64-character hex string (with or without 0x prefix). Refusing to start.\n");
+        process.exit(1);
+    }
+    const account = privateKeyToAccount(`0x${normalized}`);
+    walletAddress = account.address;
+    payFetch = wrapFetchWithPayment(fetch, account, BigInt(Math.round(Number(MAX_PRICE_USD) * 1_000_000)));
+}
+const server = new McpServer({
+    name: "skim-mcp",
+    version: "0.1.0",
+});
+server.tool("read_url", "Fetch any URL and return clean, agent-ready Markdown via Skim (skim402.com). Strips nav, ads, and boilerplate; preserves the article body plus structured metadata (title, byline, published date, language, excerpt). Pays $0.002 per call in USDC on Base over the x402 protocol — no API keys, no signup. Use this whenever you need to read web content: articles, docs, blog posts, GitHub READMEs, research papers, etc.", {
+    url: z
+        .string()
+        .url()
+        .describe("The fully-qualified URL to fetch and clean (https://...)."),
+}, async ({ url }) => {
+    if (!PRIVATE_KEY) {
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: "Skim requires payment via x402. Set the SKIM_WALLET_PRIVATE_KEY environment variable to a Base wallet funded with USDC. See https://skim402.com for details.",
+                },
+            ],
+        };
+    }
+    let res;
+    try {
+        res = await payFetch(`${BASE_URL}/api/v1/read`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ url, mode: "basic" }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Skim request failed: ${msg}. Common causes: wallet has no USDC on Base, or the price exceeds SKIM_MAX_PRICE_USD (${MAX_PRICE_USD}).`,
+                },
+            ],
+        };
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Skim returned ${res.status} ${res.statusText}: ${body || "(no body)"}`,
+                },
+            ],
+        };
+    }
+    const data = (await res.json());
+    const metaLines = data.metadata
+        ? Object.entries(data.metadata)
+            .filter(([, v]) => v != null && v !== "")
+            .map(([k, v]) => `${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`)
+        : [];
+    const frontmatter = metaLines.length > 0 ? `---\n${metaLines.join("\n")}\n---\n\n` : "";
+    return {
+        content: [
+            {
+                type: "text",
+                text: frontmatter + (data.markdown ?? data.text ?? ""),
+            },
+        ],
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// Surface startup status on stderr so MCP clients can show it in their logs
+// without interfering with the stdio JSON-RPC stream.
+if (walletAddress) {
+    process.stderr.write(`skim-mcp ready — paying from ${walletAddress} (max $${MAX_PRICE_USD}/call) → ${BASE_URL}\n`);
+}
+else {
+    process.stderr.write(`skim-mcp ready (NO WALLET) — set SKIM_WALLET_PRIVATE_KEY to enable paid reads → ${BASE_URL}\n`);
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "skim-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Skim — clean web reader for AI agents. Pays $0.002 per call in USDC over x402. No signup, no API keys.",
+  "type": "module",
+  "bin": {
+    "skim-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "viem": "^2.21.0",
+    "x402-fetch": "^0.6.0",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "tsx": "catalog:",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "skim",
+    "ai",
+    "agent",
+    "reader",
+    "markdown",
+    "web-scraping",
+    "claude",
+    "cursor"
+  ],
+  "homepage": "https://skim402.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skim402/skim-mcp"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}