datasieve-mcp 0.4.0 → 0.4.1

package/llms-install.md

@@ -0,0 +1,97 @@
+# datasieve-mcp — installation guide for AI agents
+
+This file is for an AI assistant (Cline, Claude, Cursor, …) installing the
+DataSieve MCP server on a user's behalf. Follow it top to bottom; every step is
+non-interactive.
+
+## What this server does
+
+DataSieve is standing infrastructure for agents, paid per use over x402 (HTTP
+402 + USDC on Base — no account, no API key, the wallet is the identity):
+
+- **Watch the chain** — wallet activity, whale transfers, price crossings, new pools (Base)
+- **Watch the web** — url-change monitoring, scoped by CSS selector or regex
+- **Dead-man switches** — the user's agent pings a URL; silence fires an alert
+- **Cron schedules** — fire a webhook every N seconds, at a time, or on a cron expression
+- **Multi-agent coordination** — barriers (fan-in) and locks with auto-expiring leases
+
+Most tools are **free** (status, event drain, heartbeat pings, receipt
+verification, health). Only the buying tools spend money, and failed calls are
+never billed.
+
+## Step 1 — install with no wallet (always works)
+
+Requires Node 22+. No build step, no clone needed — the package is on npm.
+
+```json
+{
+  "mcpServers": {
+    "datasieve": {
+      "command": "npx",
+      "args": ["-y", "datasieve-mcp"]
+    }
+  }
+}
+```
+
+For Claude Code: `claude mcp add datasieve -- npx -y datasieve-mcp`
+
+Verify: call the `service_health` tool. It is free and returns the live
+scanner state. If it succeeds, installation is complete.
+
+## Step 2 (optional) — enable purchases
+
+Only needed when the user wants to buy watches. Ask the user for a **dedicated
+burner wallet key** holding a few dollars of USDC on Base (payments are gasless
+EIP-3009 — no ETH needed). Never accept their main wallet key.
+
+Write the key to a file rather than embedding it in config:
+
+```sh
+echo '0xTHEIR_BURNER_KEY' > ~/.datasieve/key.txt && chmod 600 ~/.datasieve/key.txt
+```
+
+Then add the environment variable to the server config:
+
+```json
+{
+  "mcpServers": {
+    "datasieve": {
+      "command": "npx",
+      "args": ["-y", "datasieve-mcp"],
+      "env": { "DATASIEVE_PRIVATE_KEY_FILE": "/home/USER/.datasieve/key.txt" }
+    }
+  }
+}
+```
+
+Verify: call `payment_status` — it reports the wallet address, USDC balance,
+and all prices without spending anything.
+
+## Step 3 (optional) — sandbox rehearsal
+
+To test purchases with free faucet USDC (https://faucet.circle.com, Base
+Sepolia), add a second server entry with
+`"DATASIEVE_API_URL": "https://staging.datasieve.xyz"`. Sandbox watches last
+1 hour.
+
+## Troubleshooting
+
+- **`npx` cannot find the package** — ensure Node ≥ 22 (`node --version`).
+- **`payment_status` shows no wallet** — the key file path in `env` must be
+  absolute; `~` is not expanded.
+- **A paid call returned 402 repeatedly** — the wallet lacks USDC on Base
+  (mainnet) or Base Sepolia (sandbox). Check `payment_status.balance`.
+- **Purchases fail but the user was not charged** — correct behavior: failed
+  settlements roll back their side effects and are never billed. Retry with a
+  fresh request.
+
+## Tool inventory
+
+Free: `service_health`, `payment_status`, `watch_status`, `drain_events`,
+`ping_heartbeat`, `pause_watch`, `resume_watch`, `verify_receipt`,
+`delete_watch`, `coord_barrier`, `coord_arrive`, `coord_lock`, `coord_release`,
+`coord_events`.
+
+Paid: `create_watch` ($0.10–$0.85 by tier), `renew_watch` (tier price),
+`coord_workspace` ($0.25), `cron_next` ($0.001), `x402_ping` ($0.001).

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "datasieve-mcp",
-  "version": "0.4.0",
-  "description": "MCP server for DataSieve — standing infrastructure for agents over x402: on-chain watches, url-change web monitoring, dead-man switches, cron schedules, coordination, signed receipts. No account; your wallet key stays on your machine.",
+  "version": "0.4.1",
+  "description": "MCP server for DataSieve \u2014 standing infrastructure for agents over x402: on-chain watches, url-change web monitoring, dead-man switches, cron schedules, coordination, signed receipts. No account; your wallet key stays on your machine.",
   "license": "MIT",
-  "repository": "github:gitwormq/datasieve",
+  "repository": "github:gitwormq/datasieve-mcp",
   "homepage": "https://datasieve.xyz",
   "mcpName": "io.github.gitwormq/datasieve",
   "type": "module",
@@ -15,7 +15,8 @@
     "dist",
     "skill",
     "server.json",
-    "README.md"
+    "README.md",
+    "llms-install.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -47,6 +48,8 @@
     "zod": "^3.25.0"
   },
   "devDependencies": {
-    "@types/node": "^22.13.0"
+    "@types/node": "^22.13.0",
+    "tsx": "4.23.0",
+    "typescript": "5.9.3"
   }
 }

package/server.json

@@ -3,17 +3,17 @@
   "name": "io.github.gitwormq/datasieve",
   "description": "Standing infrastructure for agents over x402: on-chain watches on Base, url-change web monitoring, dead-man switches, cron schedules, multi-agent coordination, signed receipts. No account — wallet is identity.",
   "repository": {
-    "url": "https://github.com/gitwormq/datasieve",
+    "url": "https://github.com/gitwormq/datasieve-mcp",
     "source": "github"
   },
-  "version": "0.4.0",
+  "version": "0.4.1",
   "websiteUrl": "https://datasieve.xyz",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "datasieve-mcp",
-      "version": "0.4.0",
+      "version": "0.4.1",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         {