skim-mcp 0.1.2 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +102 -64
- package/dist/index.js +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,27 +1,22 @@
|
|
|
1
1
|
# skim-mcp
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
reader for AI agents. Pays **$0.002 per call in USDC on Base** over the
|
|
5
|
-
[x402](https://x402.org) protocol. No signup. No API keys. No monthly bills.
|
|
3
|
+
**Give your AI agent the ability to read any URL — clean Markdown, no ads, no nav, no boilerplate. Pays itself per call. No signup, no API key.**
|
|
6
4
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/skim-mcp)
|
|
6
|
+
[](https://registry.modelcontextprotocol.io/v0/servers?search=skim402)
|
|
7
|
+
[](LICENSE)
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
`skim-mcp` is the official Model Context Protocol server for [Skim](https://skim402.com) — the canonical [x402](https://x402.org) clean reader API. It exposes one tool, `read_url`, that your agent can call to fetch any web page as agent-ready Markdown plus structured metadata (title, byline, published date, language, excerpt). Each call costs **$0.002 in USDC on Base**, paid automatically by your local wallet over HTTP 402.
|
|
12
10
|
|
|
13
|
-
|
|
14
|
-
2. A **Base wallet private key** with a small amount of **USDC** in it. A dollar
|
|
15
|
-
funds ~500 reads. Use a fresh wallet — not your personal one.
|
|
11
|
+
> _A 30-second demo GIF coming here soon._
|
|
16
12
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Quickstart (60 seconds)
|
|
20
16
|
|
|
21
|
-
|
|
17
|
+
### 1. Add to your MCP-compatible client
|
|
22
18
|
|
|
23
|
-
|
|
24
|
-
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
19
|
+
**Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
25
20
|
|
|
26
21
|
```json
|
|
27
22
|
{
|
|
@@ -37,43 +32,45 @@ or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
|
37
32
|
}
|
|
38
33
|
```
|
|
39
34
|
|
|
40
|
-
|
|
41
|
-
any article and it'll fetch it through Skim and pay automatically.
|
|
35
|
+
**Cursor** — edit `~/.cursor/mcp.json` (or **Settings → MCP**) with the same JSON block.
|
|
42
36
|
|
|
43
|
-
|
|
37
|
+
**Cline, Continue, Zed, or any other MCP client** — same shape; the binary is `npx skim-mcp` with one env var.
|
|
44
38
|
|
|
45
|
-
|
|
39
|
+
### 2. Fund a Base wallet with $1 of USDC
|
|
40
|
+
|
|
41
|
+
A dollar funds roughly 500 reads. Full step-by-step (with screenshots, for non-crypto-native devs): **<https://skim402.com/wallet>**.
|
|
42
|
+
|
|
43
|
+
> **Use a fresh wallet, not your personal one.** This wallet's private key lives in a plaintext config file on your machine — treat it like a hot-wallet for paying $0.002 tolls, not a savings account.
|
|
44
|
+
|
|
45
|
+
### 3. Restart your client and ask it to read something
|
|
46
46
|
|
|
47
|
-
```json
|
|
48
|
-
{
|
|
49
|
-
"mcpServers": {
|
|
50
|
-
"skim": {
|
|
51
|
-
"command": "npx",
|
|
52
|
-
"args": ["-y", "skim-mcp"],
|
|
53
|
-
"env": {
|
|
54
|
-
"SKIM_WALLET_PRIVATE_KEY": "0xYOUR_BASE_WALLET_PRIVATE_KEY"
|
|
55
|
-
}
|
|
56
|
-
}
|
|
57
|
-
}
|
|
58
|
-
}
|
|
59
47
|
```
|
|
48
|
+
Claude, read https://en.wikipedia.org/wiki/HTTP_402 and summarize it.
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The agent will call `read_url`, your local wallet will sign an EIP-3009 USDC authorization for $0.002, Skim returns clean Markdown, and Claude summarizes. You'll see the payment receipt in your wallet's transaction history on [BaseScan](https://basescan.org/).
|
|
60
52
|
|
|
61
|
-
|
|
53
|
+
---
|
|
62
54
|
|
|
63
|
-
|
|
55
|
+
## Try it without an agent
|
|
56
|
+
|
|
57
|
+
Skeptical? Test the upstream endpoint directly — it'll return a 402 challenge so you can see the protocol in action:
|
|
64
58
|
|
|
65
59
|
```bash
|
|
66
|
-
|
|
60
|
+
curl -i -X POST https://skim402.com/api/v1/read \
|
|
61
|
+
-H 'content-type: application/json' \
|
|
62
|
+
-d '{"url":"https://en.wikipedia.org/wiki/HTTP_402"}'
|
|
67
63
|
```
|
|
68
64
|
|
|
69
|
-
|
|
65
|
+
You'll get back `HTTP/1.1 402 Payment Required` with the x402 challenge in the response body. To then *pay* the challenge from a script (not an agent), see [x402-fetch](https://www.npmjs.com/package/x402-fetch).
|
|
70
66
|
|
|
71
|
-
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## The tool
|
|
72
70
|
|
|
73
71
|
### `read_url`
|
|
74
72
|
|
|
75
|
-
Reads any URL and returns clean Markdown
|
|
76
|
-
metadata.
|
|
73
|
+
Reads any URL and returns clean Markdown with a YAML frontmatter block.
|
|
77
74
|
|
|
78
75
|
**Input:**
|
|
79
76
|
|
|
@@ -81,7 +78,7 @@ metadata.
|
|
|
81
78
|
{ "url": "https://example.com/article" }
|
|
82
79
|
```
|
|
83
80
|
|
|
84
|
-
**Output
|
|
81
|
+
**Output:**
|
|
85
82
|
|
|
86
83
|
```
|
|
87
84
|
---
|
|
@@ -97,40 +94,81 @@ excerpt: A short summary...
|
|
|
97
94
|
The cleaned article body in Markdown...
|
|
98
95
|
```
|
|
99
96
|
|
|
100
|
-
|
|
97
|
+
That's it. One tool, one input, one shape of output. Designed to drop into any agent's tool-calling loop with zero ceremony.
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Configuration
|
|
102
|
+
|
|
103
|
+
| Variable | Required | Default | Notes |
|
|
104
|
+
| ------------------------- | -------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
105
|
+
| `SKIM_WALLET_PRIVATE_KEY` | **yes** | — | Hex private key for the Base wallet that pays for reads. With or without `0x` prefix. Use a dedicated wallet — never your personal one. |
|
|
106
|
+
| `SKIM_MAX_PRICE_USD` | no | `0.01` | Hard cap on per-call price in USD. The wallet refuses to sign for anything above this. Skim is currently `$0.002`/call, well under the default cap — leave it alone unless tuning. |
|
|
107
|
+
| `SKIM_API_URL` | no | `https://skim402.com` | Override the API base URL. For self-hosting or local development. |
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## How it actually works
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
your agent ──► skim-mcp ──► POST https://skim402.com/api/v1/read
|
|
115
|
+
▲ │
|
|
116
|
+
│ ▼
|
|
117
|
+
│ 402 Payment Required
|
|
118
|
+
│ (x402 challenge)
|
|
119
|
+
│ │
|
|
120
|
+
▼ │
|
|
121
|
+
x402-fetch signs EIP-3009 ◄────────────┘
|
|
122
|
+
USDC transfer authorization
|
|
123
|
+
│
|
|
124
|
+
▼
|
|
125
|
+
retry POST with X-PAYMENT header
|
|
126
|
+
│
|
|
127
|
+
▼
|
|
128
|
+
Skim verifies + settles via Coinbase CDP facilitator
|
|
129
|
+
│
|
|
130
|
+
▼
|
|
131
|
+
200 OK + clean Markdown
|
|
132
|
+
```
|
|
101
133
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
| `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. |
|
|
106
|
-
| `SKIM_API_URL` | no | `https://skim402.com` | Override the API base URL. Mostly for development. |
|
|
134
|
+
End-to-end latency is typically **1.5–2 seconds** including settlement. Your private key never leaves your machine — it only signs authorizations locally.
|
|
135
|
+
|
|
136
|
+
---
|
|
107
137
|
|
|
108
138
|
## Security
|
|
109
139
|
|
|
110
|
-
-
|
|
111
|
-
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
140
|
+
- **Dedicated wallet, always.** Fund it with only as much USDC as you're willing to spend in a runaway loop. The `SKIM_MAX_PRICE_USD` cap catches accidental price escalations on the server side.
|
|
141
|
+
- **Plaintext config caveat.** MCP clients read the private key from a JSON file on disk in plaintext. Anyone with read access to your home directory can drain the wallet. This is a property of every MCP server that needs credentials — keep the wallet small.
|
|
142
|
+
- **No outbound telemetry from this package.** `skim-mcp` only talks to `skim402.com` (or whatever you set as `SKIM_API_URL`). No analytics, no error reporting, no phone-home.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Troubleshooting
|
|
115
147
|
|
|
116
|
-
|
|
148
|
+
**"No tool named `read_url` shows up in Claude/Cursor."**
|
|
149
|
+
Restart the client fully (quit, don't just reload the window). MCP servers are spawned at client startup. If still missing, run `npx skim-mcp` directly in a terminal — if you get a stack trace, it's likely Node < 18.
|
|
117
150
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
3. The server replies `402 Payment Required` with x402 payment details.
|
|
121
|
-
4. [`x402-fetch`](https://www.npmjs.com/package/x402-fetch) signs an EIP-3009
|
|
122
|
-
USDC transfer authorization using your wallet, attaches it as the
|
|
123
|
-
`X-PAYMENT` header, and retries.
|
|
124
|
-
5. Skim verifies + settles via the Coinbase CDP facilitator and returns the
|
|
125
|
-
cleaned content.
|
|
151
|
+
**"402 Payment Required loops forever."**
|
|
152
|
+
Your wallet is out of USDC on Base mainnet (or you set `SKIM_API_URL` to a server expecting payment on a different network). Check the balance on [BaseScan](https://basescan.org/), top up if needed.
|
|
126
153
|
|
|
127
|
-
|
|
154
|
+
**"insufficient funds for gas"**
|
|
155
|
+
Counter-intuitive but: x402 USDC transfers are gasless from your wallet's perspective (the facilitator pays gas, you only sign the authorization). If you see this error, you almost certainly funded the wrong wallet or the wrong network — verify the address in your config matches the one holding the USDC.
|
|
156
|
+
|
|
157
|
+
**"USDC is on Ethereum, not Base."**
|
|
158
|
+
This is the most common funding mistake. USDC on Ethereum mainnet does not work — Skim only accepts USDC on Base. See <https://skim402.com/wallet> for the bridging walkthrough.
|
|
159
|
+
|
|
160
|
+
---
|
|
128
161
|
|
|
129
162
|
## Links
|
|
130
163
|
|
|
131
|
-
- Skim — https://skim402.com
|
|
132
|
-
-
|
|
133
|
-
-
|
|
164
|
+
- **Skim website** — <https://skim402.com>
|
|
165
|
+
- **Wallet setup guide** — <https://skim402.com/wallet>
|
|
166
|
+
- **API docs** — <https://skim402.com/docs>
|
|
167
|
+
- **x402 protocol** — <https://x402.org>
|
|
168
|
+
- **Model Context Protocol** — <https://modelcontextprotocol.io>
|
|
169
|
+
- **GitHub** — <https://github.com/JessieJanie/skim402>
|
|
170
|
+
|
|
171
|
+
---
|
|
134
172
|
|
|
135
173
|
## License
|
|
136
174
|
|
package/dist/index.js
CHANGED
|
@@ -23,7 +23,7 @@ if (PRIVATE_KEY) {
|
|
|
23
23
|
}
|
|
24
24
|
const server = new McpServer({
|
|
25
25
|
name: "skim-mcp",
|
|
26
|
-
version: "0.1.
|
|
26
|
+
version: "0.1.3",
|
|
27
27
|
});
|
|
28
28
|
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.", {
|
|
29
29
|
url: z
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "skim-mcp",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"mcpName": "io.github.
|
|
3
|
+
"version": "0.1.4",
|
|
4
|
+
"mcpName": "io.github.JessieJanie/skim402",
|
|
5
5
|
"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.",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|