skim-mcp 0.2.3 → 0.2.5

package/README.md

@@ -1,12 +1,18 @@
 # skim-mcp
 
-**Give your AI agent the ability to read any URL — clean Markdown, ~4x smaller than raw HTML. No ads, no nav, no boilerplate.**
+**Skim turns URLs into clean markdown for agents. Get a free card key at [https://skim402.com](https://skim402.com) (`sk402_`). Wallet/x402 is optional.**
 
 [![npm version](https://img.shields.io/npm/v/skim-mcp.svg)](https://www.npmjs.com/package/skim-mcp)
 [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=skim402)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-`skim-mcp` is the official Model Context Protocol server for [Skim](https://skim402.com) — the clean reader API for AI agents. It exposes `read_url`, `read_urls` (batch), `extract_url` (structured / table), `crawl_url`, `read_pdf`, `watch_urls`, `check_watch`, and `poll_signal`. The default path is a card-plan API key (`SKIM_API_KEY`); x402 wallet pay stays optional.
+`skim-mcp` is the official Model Context Protocol server for [Skim](https://skim402.com). It turns any URL into clean, agent-ready Markdown (no ads, no nav, no boilerplate).
+
+**Default path: a card-plan API key.** Get a free `sk402_` key at [skim402.com](https://skim402.com) ([pricing](https://skim402.com/pricing)). Paste it as `SKIM_API_KEY`. A crypto wallet is **not** required.
+
+**Optional path: x402 wallet pay.** If you prefer pay-per-call in USDC on Base, you can set `SKIM_WALLET_PRIVATE_KEY` instead. Ignore this unless you want it.
+
+**Tools in this package:** `read_url`, `read_urls`, `extract_url`, `crawl_url`, `read_pdf`, `watch_urls`, `check_watch`, `poll_signal`.
 
 > **See it before you wire it:** [try Skim free in your browser](https://freeskims.skim402.com) — 10 free skims a day, no signup. Paste a URL, see exactly what your agent gets back.
 
@@ -74,6 +80,19 @@ Fund a dedicated Base wallet with a small USDC balance ($1 ≈ 500 reads). Full
 
 ---
 
+## FAQ
+
+**Do I need an API key?**
+Yes for the default path. Get a free `sk402_` key at [https://skim402.com](https://skim402.com). A wallet is optional.
+
+**Is this wallet-only? Do I need crypto?**
+No. Card API key is the default. x402 wallet pay is optional.
+
+**What tools can my agent call?**
+`read_url`, `read_urls` (batch), `extract_url`, `crawl_url`, `read_pdf`, `watch_urls`, `check_watch`, and `poll_signal`.
+
+---
+
 ## Try it without an agent
 
 Test the endpoint directly. With a card key:
@@ -181,12 +200,19 @@ Card-lane `/api/t/watch*` is live (POST without a key returns `401`). Optional H
 
 Poll a [Skim Signal](https://skim402.com/signals) and return the latest structured items (title, summary, source, timestamp, link, and entities). **2 credits** per successful poll; failed polls are refunded.
 
-**Requires `SKIM_API_KEY`.** The card-lane routes are `GET /api/t/signal/{slug}/latest?limit=` and `GET /api/t/feeds/x402/latest?limit=` for the x402 ecosystem feed.
+**Requires `SKIM_API_KEY`.** Wallet-only configs get a clear error: the live `GET /api/v2/...` wallet twin uses a v2 402 with an empty body, which the current `x402-fetch` wrapper does not handle.
 
 **Input:** `{ "slug": "ai-news", "limit": 20 }`
 
 Optional documented filters: `forms` (SEC filings and campaign finance), `categories` (deals), `fields` (research), `states` (film incentives), and `committees` (campaign finance).
 
+**Routes (API key):** `GET /api/t/signal/{slug}/latest?limit=` · `GET /api/t/feeds/x402/latest?limit=` (x402 is not `/signal/x402`)
+
+```bash
+curl -H 'Authorization: Bearer sk402_your_key_here' \
+  'https://skim402.com/api/t/signal/ai-news/latest?limit=20'
+```
+
 ```
 Poll the ai-news Signal for the latest 20 items.
 ```

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { privateKeyToAccount } from "viem/accounts";
 import { wrapFetchWithPayment } from "x402-fetch";
 import { z } from "zod";
-const VERSION = "0.2.3";
+const VERSION = "0.2.5";
 const BASE_URL = (process.env.SKIM_API_URL ?? "https://skim402.com").replace(/\/+$/, "");
 const API_KEY = process.env.SKIM_API_KEY ?? "";
 const PRIVATE_KEY = process.env.SKIM_WALLET_PRIVATE_KEY ?? "";
@@ -493,19 +493,19 @@ server.tool("check_watch", "Poll a Skim Watch for content changes (or fetch regi
         return fail(requestFailedMessage(err));
     }
 });
-server.tool("poll_signal", "Poll a Skim Signal feed and return the latest structured items. 2 credits per successful poll; failed polls are refunded. Requires SKIM_API_KEY because the wallet lane uses a v2 402 handshake that x402-fetch does not support for these GET feeds.", {
-    slug: z.enum(SIGNAL_SLUGS).describe("Signal slug. Use x402 for the ecosystem feed."),
-    limit: z.number().int().min(1).max(100).optional().describe("Max items, newest first. Default 50, capped at 100."),
-    forms: z.string().optional().describe("Comma-separated form filter for sec-filings or campaign-finance."),
-    categories: z.string().optional().describe("Comma-separated category filter for deals."),
-    fields: z.string().optional().describe("Comma-separated arXiv field filter for research."),
-    states: z.string().optional().describe("Comma-separated two-letter state filter for film-incentives."),
-    committees: z.string().optional().describe("Comma-separated committee-name filter for campaign-finance."),
+server.tool("poll_signal", "Poll a Skim Signal feed and return the latest structured items (title, summary, source, timestamp, link, entities). 2 credits per successful poll; failed polls are refunded. Card lane: GET /api/t/signal/{slug}/latest?limit= (filters: forms, categories, fields, states, committees). The x402 ecosystem feed is GET /api/t/feeds/x402/latest — never /signal/x402. Requires SKIM_API_KEY. No x402-fetch-compatible wallet twin (GET /api/v2/... returns a v2 402 with an empty body).", {
+    slug: z.enum(SIGNAL_SLUGS).describe("Signal slug from skim402.com/signals. Use x402 for the ecosystem feed, not /signal/x402."),
+    limit: z.number().int().min(1).max(100).optional().describe("Max items, newest-first. Default 50, capped at 100."),
+    forms: z.string().optional().describe("Comma-separated form filter. sec-filings: 8-K, S-1, 10-K, 10-Q, SC 13D, SC 13G, 4. campaign-finance: F1, F2, F3, F3P, F3X, F3L, F24, F5, F6, F9, F13, F99."),
+    categories: z.string().optional().describe("deals only. Comma-separated category terms (1–8, each 2–40 chars), e.g. laptop,gpu."),
+    fields: z.string().optional().describe("research only. Comma-separated arXiv fields: ai, ml, nlp, vision, robotics, agents, security, quantum."),
+    states: z.string().optional().describe("film-incentives only. Comma-separated two-letter states: CA, NY, GA, NM, TX."),
+    committees: z.string().optional().describe("campaign-finance only. Comma-separated committee-name substrings (1–8, each 2–60 chars), e.g. turning point,dnc."),
 }, async ({ slug, limit, forms, categories, fields, states, committees }) => {
     if (!hasAuth)
         return authMissing();
     if (!cardLane) {
-        return fail("poll_signal is card-lane only. Set SKIM_API_KEY (sk402_..., free tier at skim402.com/pricing).");
+        return fail("poll_signal is card-lane only (GET /api/t/signal/{slug}/latest or GET /api/t/feeds/x402/latest) — set SKIM_API_KEY (sk402_..., free tier at skim402.com/pricing). The wallet twin returns a v2 402 with an empty body, which the existing x402-fetch wrapper does not handle.");
     }
     try {
         const query = {};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "skim-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "mcpName": "io.github.JessieJanie/skim402",
-  "description": "MCP server for Skim — clean web reader for AI agents. Card API key or x402 wallet. Batch, extract, crawl, PDF, watch, signals.",
+  "description": "MCP server for Skim — URLs to clean markdown. Card API key (sk402_) default; wallet/x402 optional. Batch, extract, crawl, PDF, watch, signals.",
   "type": "module",
   "bin": {
     "skim-mcp": "dist/index.js"