skim-mcp 0.2.0 → 0.2.3

package/README.md

@@ -6,7 +6,7 @@
 [![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), `watch_urls`, and `check_watch`. 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) — 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.
 
 > **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.
 
@@ -137,17 +137,59 @@ Structured JSON from a page. Pass a JSON Schema, or a preset: `article`, `produc
 
 Presets are sent as schemas on those extract routes (card lane has no live `/api/t/extract/{preset}` today). Align with skim402-web if that splits later.
 
+### `crawl_url`
+
+Crawl a site (origin or start URL) and return clean Markdown per page. Discovers `sitemap.xml` / `robots.txt` sitemaps plus same-origin links. Cap 25 pages. **1 credit per successful page**; failed pages are not charged.
+
+**Input:** `{ "url": "https://example.com", "maxPages": 10 }`
+
+Optional: `stripLinks`, `stripImages` (passed through to each page read). Bare hosts like `example.com` are treated as `https://example.com`.
+
+**Route:** `POST /api/t/crawl` (API key). No x402 `/v1` twin — wallet-only configs get a clear error; set `SKIM_API_KEY`.
+
+```
+Crawl https://example.com (max 10 pages) and list the page titles.
+```
+
+### `read_pdf`
+
+Fetch a public PDF URL and return clean Markdown plus an optional bookmark outline. Text comes only from the file. Image-only scans return **422** (no OCR). Files larger than **8 MB** return **413**. **3 credits**; failed conversions are not charged.
+
+**Input:** `{ "url": "https://example.com/paper.pdf" }`
+
+Optional: `outline` (default `true`).
+
+**Route:** `POST /api/t/read-pdf` (API key). No x402 `/v1` twin — set `SKIM_API_KEY`.
+
+```
+Read the PDF at https://example.com/paper.pdf and summarize the outline.
+```
+
 ### `watch_urls` / `check_watch`
 
 Register 1–20 URLs, then poll for content diffs. `watch_id` is a secret.
 
 **Input:** `{ "urls": ["https://competitor.com/pricing"], "note": "pricing" }` then `{ "watch_id": "w_…" }` (optional `status_only: true`)
 
-**Routes (API key, intended):** `POST /api/t/watch` · `GET /api/t/watch/diff?id=` · `GET /api/t/watch/status?id=`
+**Routes (API key):** `POST /api/t/watch` · `GET /api/t/watch/diff?id=` · `GET /api/t/watch/status?id=`
+
+**Routes (wallet):** `POST /api/v2/watch` · `GET /api/v2/watch/diff?id=` · `GET /api/v2/watch/status?id=`
+
+Card-lane `/api/t/watch*` is live (POST without a key returns `401`). Optional HTTPS `webhookUrl` is supported by the API; this MCP tool still sends `{ urls, note? }`.
+
+### `poll_signal`
+
+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.
 
-**Routes (wallet, live):** `POST /api/v2/watch` · `GET /api/v2/watch/diff?id=` · `GET /api/v2/watch/status?id=`
+**Input:** `{ "slug": "ai-news", "limit": 20 }`
 
-`/api/t/watch*` is documented on skim402-web (Signals: `POST /t/watch`) but was not serving on skim402.com when this package was wired. The MCP client still calls those paths so it works the moment they land — do not invent a different watch protocol.
+Optional documented filters: `forms` (SEC filings and campaign finance), `categories` (deals), `fields` (research), `states` (film incentives), and `committees` (campaign finance).
+
+```
+Poll the ai-news Signal for the latest 20 items.
+```
 
 ### Example agent prompts
 
@@ -158,6 +200,12 @@ Read these three pages and compare their pricing: https://a.example/pricing http
 
 Extract the product name, price, and availability from https://example.com/products/notebook as JSON.
 
+Crawl https://example.com (max 10 pages) and list the page titles.
+
+Read the PDF at https://example.com/paper.pdf and summarize it.
+
+Poll the ai-news Signal for the latest 20 items.
+
 Watch https://competitor.com/pricing and https://competitor.com/changelog, then check the watch for changes.
 ```
 

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.1.7";
+const VERSION = "0.2.3";
 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 ?? "";
@@ -151,6 +151,17 @@ function ok(text) {
 function authMissing() {
     return fail("Skim needs a payment method. Set SKIM_API_KEY (card plan, free tier at skim402.com/pricing) or SKIM_WALLET_PRIVATE_KEY (Base wallet with USDC). Card is easier — no crypto setup required.");
 }
+function cardLaneOnly(tool, path) {
+    return fail(`${tool} is card-lane only (${path}) — there is no x402 /v1 twin. Set SKIM_API_KEY (sk402_..., free tier at skim402.com/pricing). Wallet pay still works for read_url, read_urls, extract_url, and watch.`);
+}
+const SIGNAL_SLUGS = [
+    "ai-news", "sec-filings", "crypto-news", "macro", "security", "regulations",
+    "courts", "recalls", "deals", "launches", "trending", "research", "energy",
+    "entertainment", "studio-jobs", "campaign-finance", "film-incentives", "x402",
+];
+function signalPollPath(slug) {
+    return slug === "x402" ? "/api/t/feeds/x402/latest" : `/api/t/signal/${slug}/latest`;
+}
 function buildUrl(path, query) {
     const url = new URL(path, `${BASE_URL}/`);
     if (query) {
@@ -208,6 +219,42 @@ function formatRead(data) {
     const frontmatter = metaLines.length > 0 ? `---\n${metaLines.join("\n")}\n---\n\n` : "";
     return frontmatter + (data.markdown ?? data.text ?? "");
 }
+function formatCrawl(data) {
+    const meta = {};
+    if (data.url)
+        meta.url = data.url;
+    if (data.origin)
+        meta.origin = data.origin;
+    if (data.pageCount != null)
+        meta.pageCount = data.pageCount;
+    if (data.discovered != null)
+        meta.discovered = data.discovered;
+    if (data.capped != null)
+        meta.capped = data.capped;
+    if (data.maxPages != null)
+        meta.maxPages = data.maxPages;
+    if (data.sources?.length)
+        meta.sources = data.sources.join(", ");
+    if (data.charged != null)
+        meta.charged = data.charged;
+    if (data.fetchedAt)
+        meta.fetchedAt = data.fetchedAt;
+    const blocks = (data.pages ?? []).map((page) => {
+        if (page.ok !== false && (page.markdown || page.title)) {
+            const heading = page.title ? `${page.title} — ${page.url}` : page.url;
+            return `## ${heading}\n\n${page.markdown ?? ""}`;
+        }
+        const err = page.error;
+        const detail = typeof err === "string"
+            ? err
+            : err
+                ? `${err.status ?? ""} ${err.message ?? ""}`.trim()
+                : "unknown error";
+        return `## ${page.url}\n\nERROR: ${detail}`;
+    });
+    return (formatRead({ metadata: meta, markdown: blocks.join("\n\n---\n\n") }) ||
+        JSON.stringify(data, null, 2));
+}
 const server = new McpServer({
     name: "skim-mcp",
     version: VERSION,
@@ -316,7 +363,87 @@ server.tool("extract_url", "Extract structured JSON (or tables) from a URL via S
         return fail(requestFailedMessage(err));
     }
 });
-server.tool("watch_urls", "Register a private Skim Watch on 1–20 URLs. Returns a watch_id (treat it as a secret) used with check_watch. First check baselines each page; later checks report content diffs. Card lane: POST /api/t/watch (intended token path from skim402-web; may 404 until that route is live). Wallet lane: POST /api/v2/watch.", {
+server.tool("crawl_url", "Crawl a site (origin or start URL) and return clean Markdown for the important pages. Discovers sitemap.xml / robots.txt sitemaps plus same-origin links. Cap 25 pages. 1 credit per successful page; failed pages are not charged. Card lane only: POST /api/t/crawl. No x402 /v1 twin.", {
+    url: z
+        .string()
+        .min(1)
+        .describe("Site origin or start URL. Bare hosts like example.com are treated as https://example.com."),
+    maxPages: z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .optional()
+        .describe("Optional page cap, 1–25. Default 25."),
+    stripLinks: z
+        .boolean()
+        .optional()
+        .describe("If true, flatten markdown links to their anchor text on every page."),
+    stripImages: z
+        .boolean()
+        .optional()
+        .describe("If true, drop image markup from every page."),
+}, async ({ url, maxPages, stripLinks, stripImages }) => {
+    if (!hasAuth)
+        return authMissing();
+    if (!cardLane)
+        return cardLaneOnly("crawl_url", "POST /api/t/crawl");
+    try {
+        const res = await skimFetch("POST", "/api/t/crawl", {
+            body: {
+                url,
+                ...(maxPages !== undefined ? { maxPages } : {}),
+                ...(stripLinks !== undefined ? { stripLinks } : {}),
+                ...(stripImages !== undefined ? { stripImages } : {}),
+            },
+        });
+        const data = (await readJson(res));
+        return ok(formatCrawl(data));
+    }
+    catch (err) {
+        return fail(requestFailedMessage(err));
+    }
+});
+server.tool("read_pdf", "Fetch a public PDF URL and return clean Markdown plus an optional bookmark outline. Text comes only from the file — nothing is invented. Image-only scans return 422 (no OCR). Files larger than 8 MB return 413. 3 credits; failed conversions are not charged. Card lane only: POST /api/t/read-pdf. No x402 /v1 twin.", {
+    url: z
+        .string()
+        .url()
+        .describe("Absolute http(s) PDF URL to fetch and convert."),
+    outline: z
+        .boolean()
+        .optional()
+        .describe("If true (default), include the PDF bookmark outline when present. Set false to omit it."),
+}, async ({ url, outline }) => {
+    if (!hasAuth)
+        return authMissing();
+    if (!cardLane)
+        return cardLaneOnly("read_pdf", "POST /api/t/read-pdf");
+    try {
+        const res = await skimFetch("POST", "/api/t/read-pdf", {
+            body: {
+                url,
+                ...(outline !== undefined ? { outline } : {}),
+            },
+        });
+        const data = (await readJson(res));
+        return ok(formatRead({
+            markdown: data.markdown,
+            text: data.text,
+            metadata: {
+                ...(data.url ? { url: data.url } : {}),
+                ...(data.finalUrl ? { finalUrl: data.finalUrl } : {}),
+                ...(data.pageCount != null ? { pageCount: data.pageCount } : {}),
+                ...(data.charged != null ? { charged: data.charged } : {}),
+                ...(data.fetchedAt ? { fetchedAt: data.fetchedAt } : {}),
+                ...(data.outline != null ? { outline: data.outline } : {}),
+            },
+        }));
+    }
+    catch (err) {
+        return fail(requestFailedMessage(err));
+    }
+});
+server.tool("watch_urls", "Register a private Skim Watch on 1–20 URLs. Returns a watch_id (treat it as a secret) used with check_watch. First check baselines each page; later checks report content diffs. Card lane: POST /api/t/watch. Wallet lane: POST /api/v2/watch.", {
     urls: z
         .array(z.string().url())
         .min(1)
@@ -338,11 +465,7 @@ server.tool("watch_urls", "Register a private Skim Watch on 1–20 URLs. Returns
         return ok(JSON.stringify(data, null, 2));
     }
     catch (err) {
-        const msg = requestFailedMessage(err);
-        if (cardLane && /404/.test(msg)) {
-            return fail(`${msg}\n\nExpected card-lane path is POST /api/t/watch (see skim402-web Signals: POST /t/watch). That route is not live on skim402.com yet — align with skim402-web rather than inventing a different protocol. Wallet-lane POST /api/v2/watch is already live.`);
-        }
-        return fail(msg);
+        return fail(requestFailedMessage(err));
     }
 });
 server.tool("check_watch", "Poll a Skim Watch for content changes (or fetch registration status). Pass the watch_id from watch_urls. Card lane: GET /api/t/watch/diff?id= (or /status). Wallet lane: GET /api/v2/watch/diff?id= (or /status, which is free).", {
@@ -367,11 +490,42 @@ server.tool("check_watch", "Poll a Skim Watch for content changes (or fetch regi
         return ok(JSON.stringify(data, null, 2));
     }
     catch (err) {
-        const msg = requestFailedMessage(err);
-        if (cardLane && /404/.test(msg)) {
-            return fail(`${msg}\n\nExpected card-lane paths are GET /api/t/watch/diff?id= and GET /api/t/watch/status?id= (skim402-web). Those routes are not live on skim402.com yet. Wallet-lane GET /api/v2/watch/diff and /status are already live.`);
-        }
-        return fail(msg);
+        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."),
+}, 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).");
+    }
+    try {
+        const query = {};
+        if (limit !== undefined)
+            query.limit = String(limit);
+        if (forms)
+            query.forms = forms;
+        if (categories)
+            query.categories = categories;
+        if (fields)
+            query.fields = fields;
+        if (states)
+            query.states = states;
+        if (committees)
+            query.committees = committees;
+        const res = await skimFetch("GET", signalPollPath(slug), { query });
+        return ok(JSON.stringify(await readJson(res), null, 2));
+    }
+    catch (err) {
+        return fail(requestFailedMessage(err));
     }
 });
 const transport = new StdioServerTransport();

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "skim-mcp",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "mcpName": "io.github.JessieJanie/skim402",
-  "description": "MCP server for Skim — clean web reader for AI agents. Card API key or x402 wallet. Batch, extract, watch.",
+  "description": "MCP server for Skim — clean web reader for AI agents. Card API key or x402 wallet. Batch, extract, crawl, PDF, watch, signals.",
   "type": "module",
   "bin": {
     "skim-mcp": "dist/index.js"
@@ -13,13 +13,6 @@
     "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",
-    "postinstall": "npm install -g tsx@4.21.0"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "viem": "^2.21.0",
@@ -56,5 +49,11 @@
   "license": "MIT",
   "engines": {
     "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "postinstall": "npm install -g tsx@4.21.0"
   }
-}
+}