agent-data-tools 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpellzCode
+
+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

@@ -1,3 +1,68 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# agent-data-tools
+
+Data tools for AI agents, one HTTP call each: PDF to text, web page to Markdown, web search, news, token prices, OFAC sanctions checks, chain reads on 18 networks, IP geolocation, hosted pages and about 550 more. No dependencies. 25 free calls with no signup, then card credits or USDC per call; failed calls are not charged.
+
+## Use it in your AI client
+
+One command per client. Each connects the client to the MCP server at `https://agent-data-tools.revmesh2074.workers.dev/mcp`.
+
+```sh
+npx agent-data-tools setup claude-code      # prints the `claude mcp add --transport http ...` command to run
+npx agent-data-tools setup claude-desktop   # adds the server to claude_desktop_config.json
+npx agent-data-tools setup cursor           # adds the server to ~/.cursor/mcp.json
+npx agent-data-tools setup vscode           # adds the server to .vscode/mcp.json in the current folder
+```
+
+`--print` shows the change without writing anything. When a file is changed, other servers in it are kept and the previous version stays next to it as `.bak`; a file that is not plain JSON is left alone and the lines to add are printed.
+
+Without a key the server gives 25 free calls. With a prepaid key:
+
+```sh
+npx agent-data-tools credits            # where to get a key (card or USDC)
+npx agent-data-tools key adt_...        # saves it to ~/.agent-data-tools/config.json
+npx agent-data-tools key                # shows the last 4 characters and the balance
+npx agent-data-tools setup cursor --key adt_...
+```
+
+`setup --key` puts the key into the client's own user-level configuration (a header for Claude Code and Cursor, the server's environment for Claude Desktop). It is never written to `.vscode/mcp.json`, which is a project file: there the entry is the local command below, which reads the saved key.
+
+`npx agent-data-tools mcp` is a stdio MCP server that forwards to the remote one, for clients that only start local commands. It reads the key from `--key`, then `AGENT_DATA_TOOLS_KEY`, then `~/.agent-data-tools/config.json`. The package holds no payment or wallet code.
+
+## From the command line and from code
+
+```sh
+npx agent-data-tools list pdf
+npx agent-data-tools pdf_text url=https://arxiv.org/pdf/1706.03762 pages=2
+```
+
+```js
+import { AgentDataTools } from "agent-data-tools";
+
+const adt = new AgentDataTools();
+const weather = await adt.call("/weather", { city: "London" });
+const matches = await adt.tools({ search: "sanctions" });
+```
+
+## Give the tools to a model
+
+`openAiTools()` returns OpenAI function-calling definitions; [examples/openai-agent.mjs](examples/openai-agent.mjs) is a complete loop in 30 lines.
+
+```js
+const tools = await adt.openAiTools(["extract", "pdf_text", "search"]);
+// When the model calls one:
+const answer = await adt.call(call.function.name, JSON.parse(call.function.arguments));
+```
+
+## Paying
+
+| How | Setup |
+|---|---|
+| Free calls | None. 25 successful calls per caller; AI media, rendering and search tools are paid only. |
+| Card credits | Buy a key at [/credits](https://agent-data-tools.revmesh2074.workers.dev/credits), then `npx agent-data-tools key adt_...`, `new AgentDataTools({ apiKey })` or the `ADT_API_KEY` environment variable. |
+| USDC per call (x402) | Pass a fetch that pays HTTP 402, such as `@x402/fetch` around your own wallet: `new AgentDataTools({ fetch: paying })`. Set your spending limits in that wrapper. |
+
+When payment is needed and none is set up, `call()` throws `PaymentRequired` with `priceUsd` and `buyUrl`. Other failures throw `ToolError` with `status` and `body`. The package never reads a wallet key and sends your API key only to the service origin.
+
+## Also
+
+Full catalog and prices: [`/tools`](https://agent-data-tools.revmesh2074.workers.dev/tools), [`/openapi.json`](https://agent-data-tools.revmesh2074.workers.dev/openapi.json). MCP server: `https://agent-data-tools.revmesh2074.workers.dev/mcp`. Terms: [`/terms`](https://agent-data-tools.revmesh2074.workers.dev/terms).

package/cli.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// npx agent-data-tools setup [client]          put the tools into Claude Code, Claude Desktop, Cursor or VS Code
+// npx agent-data-tools mcp                     stdio MCP server that forwards to the remote one
+// npx agent-data-tools key [adt_...]           save a prepaid key, or show whether one is set and its balance
+// npx agent-data-tools credits                 where to get a key
+// npx agent-data-tools list [words]            tools and prices
+// npx agent-data-tools <tool> key=value …      call a tool (name or /path); prints its JSON
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { AgentDataTools, ORIGIN, PaymentRequired, ToolError } from "./index.mjs";
+
+const NAME = "agent-data-tools";
+const STDIO = { command: "npx", args: ["-y", NAME, "mcp"] };
+const TARGETS = ["claude-code", "claude-desktop", "cursor", "vscode"];
+
+const origin = () => (process.env.AGENT_DATA_TOOLS_ORIGIN || ORIGIN).replace(/\/$/, "");
+const configFile = () => join(homedir(), ".agent-data-tools", "config.json");
+const tail = (key) => `…${key.slice(-4)}`;
+const validKey = (key) => typeof key === "string" && /^adt_\S+$/.test(key);
+
+function readConfig() {
+  try { const c = JSON.parse(readFileSync(configFile(), "utf8").replace(/^/, "")); return c && typeof c === "object" && !Array.isArray(c) ? c : {}; } catch { return {}; }
+}
+
+/** The key and where it came from: --key, AGENT_DATA_TOOLS_KEY, the config file, then ADT_API_KEY (the library's variable). */
+function resolveKey(flag) {
+  if (flag) return { key: flag, source: "--key" };
+  if (process.env.AGENT_DATA_TOOLS_KEY) return { key: process.env.AGENT_DATA_TOOLS_KEY, source: "AGENT_DATA_TOOLS_KEY" };
+  const saved = readConfig().key;
+  if (typeof saved === "string" && saved) return { key: saved, source: configFile() };
+  if (process.env.ADT_API_KEY) return { key: process.env.ADT_API_KEY, source: "ADT_API_KEY" };
+  return { key: undefined, source: undefined };
+}
+
+/** Split `--key <value>`, `--key=<value>` and `--print` from the other arguments. */
+function parseArgs(args) {
+  const rest = [];
+  let key, print = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--print") print = true;
+    else if (a === "--key") { key = args[++i]; if (!key) throw new ToolError("--key needs a value (adt_...)", 400, null); }
+    else if (a.startsWith("--key=")) key = a.slice(6);
+    else rest.push(a);
+  }
+  if (key !== undefined && !validKey(key)) throw new ToolError("the key must start with adt_", 400, null);
+  return { rest, key, print };
+}
+
+const HELP = `Usage:
+  agent-data-tools setup [claude-code|claude-desktop|cursor|vscode] [--key adt_...] [--print]
+                                         add the tools to that client (--print shows the change without writing)
+  agent-data-tools mcp [--key adt_...]   stdio MCP server that forwards to ${ORIGIN}/mcp
+  agent-data-tools key [adt_...]         save a prepaid key; without a key, show whether one is set and its balance
+  agent-data-tools credits               where to get a prepaid key (card or USDC)
+  agent-data-tools list [words]          tools and prices
+  agent-data-tools <tool> key=value ...  call a tool by name or /path; prints its JSON
+
+25 free calls without any setup. A prepaid key is read from --key, then AGENT_DATA_TOOLS_KEY,
+then ~/.agent-data-tools/config.json, then ADT_API_KEY.`;
+
+function menu() {
+  return `Add the tools to a client:
+  agent-data-tools setup claude-code      prints the \`claude mcp add\` command to run
+  agent-data-tools setup claude-desktop   writes claude_desktop_config.json
+  agent-data-tools setup cursor           writes ~/.cursor/mcp.json
+  agent-data-tools setup vscode           writes .vscode/mcp.json in the current folder
+
+Add --print to see the change without writing, and --key adt_... to connect with a prepaid key.
+Without a key the server gives 25 free calls. Keys: agent-data-tools credits`;
+}
+
+function desktopConfigPath() {
+  if (process.platform === "win32") return join(process.env.APPDATA || join(homedir(), "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+  if (process.platform === "darwin") return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+}
+
+/** Add one server entry to a JSON config file, keeping everything else; a copy of the old file stays next to it as .bak. */
+function mergeInto(file, section, entry, print) {
+  const snippet = JSON.stringify({ [section]: { [NAME]: entry } }, null, 2);
+  if (print) { console.log(`${file}\n${snippet}`); return false; }
+  let json = {};
+  const exists = existsSync(file);
+  if (exists) {
+    try { json = JSON.parse(readFileSync(file, "utf8").replace(/^/, "")); } catch { json = null; }
+    const usable = json && typeof json === "object" && !Array.isArray(json) && (json[section] === undefined || (json[section] && typeof json[section] === "object" && !Array.isArray(json[section])));
+    if (!usable) {
+      console.error(`${file} is not JSON this command can edit, so it was left unchanged. Add this to it yourself:\n${snippet}`);
+      process.exitCode = 1;
+      return false;
+    }
+    copyFileSync(file, `${file}.bak`);
+  } else mkdirSync(dirname(file), { recursive: true });
+  json[section] = { ...(json[section] ?? {}), [NAME]: entry };
+  writeFileSync(file, `${JSON.stringify(json, null, 2)}\n`);
+  console.log(`${exists ? "Updated" : "Created"} ${file}${exists ? ` (previous version: ${file}.bak)` : ""}`);
+  return true;
+}
+
+function setup(target, { key, print }) {
+  if (!target) { console.log(menu()); return; }
+  if (!TARGETS.includes(target)) throw new ToolError(`unknown client "${target}"; use one of: ${TARGETS.join(", ")}`, 400, null);
+  const url = `${origin()}/mcp`;
+  const saved = key ? undefined : resolveKey().key;
+  const savedNote = `A key is already saved for this computer; pass it with --key to connect ${target} with it.`;
+  if (target === "claude-code") {
+    console.log(`claude mcp add --transport http ${NAME} ${url}${key ? ` --header "Authorization: Bearer ${key}"` : ""}`);
+    console.error(`Run the command above in a terminal; it registers the server with Claude Code.${saved ? `\n${savedNote}` : ""}`);
+  } else if (target === "claude-desktop") {
+    // Claude Desktop starts local commands; the stdio server reads the key from its environment or the config file.
+    const entry = key ? { ...STDIO, env: { AGENT_DATA_TOOLS_KEY: key } } : STDIO;
+    if (mergeInto(desktopConfigPath(), "mcpServers", entry, print)) console.error(`Restart Claude Desktop to load it.${key ? ` The key (${tail(key)}) is in the server's env.` : saved ? " The saved key is used." : ""}`);
+  } else if (target === "cursor") {
+    const entry = key ? { url, headers: { Authorization: `Bearer ${key}` } } : { url };
+    if (mergeInto(join(homedir(), ".cursor", "mcp.json"), "mcpServers", entry, print)) console.error(`Cursor reads it for every project.${key ? ` The key (${tail(key)}) is sent as a header.` : saved ? `\n${savedNote}` : ""}`);
+  } else {
+    // A project file may be committed, so a key never goes into it: with a key, the entry is the stdio command, which reads the key itself.
+    const entry = key || saved ? { type: "stdio", ...STDIO } : { type: "http", url };
+    const done = mergeInto(resolve(".vscode", "mcp.json"), "servers", entry, print);
+    if (key) console.error(`The key is not written to the project file. Save it once with \`${NAME} key <your key>\` (or set AGENT_DATA_TOOLS_KEY); the command in the file reads it from there.`);
+    else if (saved && done) console.error("The command in the file reads your saved key; nothing secret is in the project file.");
+  }
+}
+
+async function keyCommand(value) {
+  if (value !== undefined) {
+    if (!validKey(value)) throw new ToolError("the key must start with adt_", 400, null);
+    const file = configFile();
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    writeFileSync(file, `${JSON.stringify({ ...readConfig(), key: value }, null, 2)}\n`, { mode: 0o600 });
+    try { chmodSync(file, 0o600); } catch { /* not supported on this file system */ }
+    console.log(`Saved the key ending in ${tail(value)} to ${file}`);
+    return;
+  }
+  const { key, source } = resolveKey();
+  if (!key) { console.log(`No key is set. The server gives 25 free calls without one. Get a key: ${NAME} credits`); return; }
+  console.log(`A key is set (ends in ${tail(key)}), from ${source}.`);
+  try {
+    const res = await fetch(`${origin()}/credits/balance`, { headers: { accept: "application/json", "x-api-key": key } });
+    const body = await res.json().catch(() => null);
+    if (res.ok && body && typeof body.balanceCredits === "number") console.log(`Balance: ${body.balanceCredits} credits (${body.calls ?? 0} calls so far).`);
+    else console.log(`Balance not available: ${typeof body?.error === "string" ? body.error : `HTTP ${res.status}`}`);
+  } catch (e) {
+    console.log(`Balance not available: ${e?.cause?.code ?? e?.message ?? "network error"}`);
+  }
+}
+
+function credits() {
+  const o = origin();
+  console.log(`Card: ${o}/credits
+  Open it in a browser to buy a prepaid key with a card.
+USDC, $1:  ${o}/credits/usdc/1
+USDC, $5:  ${o}/credits/usdc/5
+USDC, $20: ${o}/credits/usdc/20
+  Each is an x402 route: an x402 client that pays it gets a key back. This command does not pay.
+
+Then: ${NAME} key adt_...   saves the key for \`${NAME} mcp\` and for tool calls.
+Balance: ${NAME} key`);
+}
+
+const [command, ...rest] = process.argv.slice(2);
+try {
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    console.log(HELP);
+  } else if (command === "mcp") {
+    // Nothing but JSON-RPC may reach stdout here.
+    const { key } = parseArgs(rest);
+    const { runStdioProxy } = await import("./mcp-stdio.mjs");
+    await runStdioProxy({ origin: origin(), key: resolveKey(key).key });
+  } else if (command === "setup") {
+    const args = parseArgs(rest);
+    setup(args.rest[0], args);
+  } else if (command === "key") {
+    await keyCommand(rest[0]);
+  } else if (command === "credits") {
+    credits();
+  } else {
+    const adt = new AgentDataTools({ apiKey: resolveKey().key, origin: origin() });
+    if (command === "list") {
+      for (const t of await adt.tools({ search: rest.join(" ") })) console.log(`${t.name.padEnd(30)} ${t.price.padEnd(8)} ${t.summary}`);
+    } else {
+      const inputs = {};
+      for (const arg of rest) {
+        const eq = arg.indexOf("=");
+        if (eq < 1) throw new ToolError(`expected key=value, got "${arg}"`, 400, null);
+        inputs[arg.slice(0, eq)] = arg.slice(eq + 1);
+      }
+      console.log(JSON.stringify(await adt.call(command, inputs), null, 2));
+    }
+  }
+} catch (e) {
+  console.error(e instanceof PaymentRequired || e instanceof ToolError ? e.message : e);
+  process.exitCode = 1;
+}

package/examples/openai-agent.mjs

@@ -0,0 +1,22 @@
+// A minimal agent: any OpenAI-compatible chat API plus Agent Data Tools. Needs OPENAI_API_KEY (and optionally OPENAI_BASE_URL, OPENAI_MODEL).
+//   node examples/openai-agent.mjs "What does the first page of https://arxiv.org/pdf/1706.03762 say?"
+import { AgentDataTools } from "agent-data-tools";
+
+const adt = new AgentDataTools();
+const tools = await adt.openAiTools(["extract", "pdf_text", "weather", "price_token"]);
+const messages = [{ role: "user", content: process.argv[2] ?? "What is the weather in Stockholm?" }];
+
+for (let turn = 0; turn < 6; turn++) {
+  const res = await fetch(`${process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${process.env.OPENAI_API_KEY}` },
+    body: JSON.stringify({ model: process.env.OPENAI_MODEL ?? "gpt-4o-mini", messages, tools }),
+  });
+  const message = (await res.json()).choices[0].message;
+  messages.push(message);
+  if (!message.tool_calls?.length) { console.log(message.content); break; }
+  for (const call of message.tool_calls) {
+    const result = await adt.call(call.function.name, JSON.parse(call.function.arguments)).catch((e) => ({ error: e.message }));
+    messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result).slice(0, 20000) });
+  }
+}

package/index.mjs

@@ -0,0 +1,92 @@
+// Client for Agent Data Tools: pay-per-call data tools for AI agents. No dependencies; Node 20+, Deno, Bun, Workers and browsers.
+export const ORIGIN = "https://agent-data-tools.revmesh2074.workers.dev";
+const MAX_URL = 6000;
+
+/** A tool call that did not return data. `status` is the HTTP status; `body` is the parsed answer. */
+export class ToolError extends Error {
+  constructor(message, status, body) { super(message); this.name = "ToolError"; this.status = status; this.body = body; }
+}
+/** HTTP 402: the free calls are used up (or the tool has none) and no way to pay was configured. */
+export class PaymentRequired extends ToolError {
+  constructor(message, status, body, priceUsd, buyUrl) { super(message, status, body); this.name = "PaymentRequired"; this.priceUsd = priceUsd; this.buyUrl = buyUrl; }
+}
+
+const priceOf = (body) => { const a = Number(body?.accepts?.[0]?.amount); return Number.isFinite(a) ? a / 1e6 : null; };
+
+export class AgentDataTools {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.apiKey] Prepaid card-credit key (adt_…) from /credits; default: the ADT_API_KEY environment variable.
+   * @param {typeof fetch} [options.fetch] A fetch that pays HTTP 402 itself, such as @x402/fetch's wrapper around your wallet.
+   * @param {string} [options.origin] Service origin.
+   * Without a key or a paying fetch, calls use the free trial (25 successful calls per caller; AI media, rendering and search tools excluded).
+   */
+  constructor({ apiKey, fetch: paying, origin = ORIGIN } = {}) {
+    this.apiKey = apiKey ?? globalThis.process?.env?.ADT_API_KEY;
+    this.paying = paying;
+    this.fetch = paying ?? globalThis.fetch;
+    this.origin = origin.replace(/\/$/, "");
+    this.catalog = null;
+  }
+
+  /** Every tool: `{ name, path, price, summary, description, params }`. `search` keeps those whose text holds every word. */
+  async tools({ search } = {}) {
+    if (!this.catalog) {
+      const res = await globalThis.fetch(`${this.origin}/openapi.json`, { headers: { accept: "application/json" } });
+      if (!res.ok) throw new ToolError(`could not read the catalog: HTTP ${res.status}`, res.status, null);
+      const api = await res.json();
+      this.catalog = Object.entries(api.paths).flatMap(([path, ops]) => {
+        const op = ops.get;
+        const amount = op?.["x-payment-info"]?.price?.amount;
+        if (!op?.operationId || amount === undefined) return [];
+        return [{ name: op.operationId, path, price: `$${amount}`, summary: op.summary ?? "", description: op.description ?? "", params: (op.parameters ?? []).filter((p) => p.in === "query").map((p) => ({ name: p.name, required: Boolean(p.required), type: p.schema?.type ?? "string", description: p.description ?? "" })) }];
+      });
+    }
+    if (!search) return this.catalog;
+    const words = search.toLowerCase().split(/\s+/).filter(Boolean);
+    return this.catalog.filter((t) => { const text = `${t.name} ${t.summary} ${t.description}`.toLowerCase(); return words.every((w) => text.includes(w)); });
+  }
+
+  /** Call a tool by path (`/weather`) or name (`pdf_text`) with its inputs; resolves to the tool's JSON answer. */
+  async call(tool, inputs = {}) {
+    let path = tool;
+    if (!tool.startsWith("/")) {
+      const hit = (await this.tools()).find((t) => t.name === tool);
+      if (!hit) throw new ToolError(`no tool named "${tool}"; see tools()`, 404, null);
+      path = hit.path;
+    }
+    const headers = { accept: "application/json" };
+    if (this.apiKey) headers.authorization = `Bearer ${this.apiKey}`;
+    const query = new URLSearchParams();
+    for (const [k, v] of Object.entries(inputs)) if (v !== undefined && v !== null) query.set(k, typeof v === "object" ? JSON.stringify(v) : String(v));
+    if (!this.apiKey && !this.paying) query.set("trial", "1");
+    const url = `${this.origin}${path}?${query}`;
+    // Long inputs (a page to publish, a document to summarise) go as a flat JSON body, which the service reads the same way.
+    const res = url.length <= MAX_URL
+      ? await this.fetch(url, { headers })
+      : await this.fetch(`${this.origin}${path}`, { method: "POST", headers: { ...headers, "content-type": "application/json" }, body: JSON.stringify(Object.fromEntries(query)) });
+    const text = await res.text();
+    let body;
+    try { body = JSON.parse(text); } catch { body = text; }
+    if (res.status === 402) {
+      const price = priceOf(body);
+      throw new PaymentRequired(`${path} needs payment${price === null ? "" : ` ($${price})`}: pass apiKey (card credits from ${this.origin}/credits, from $1) or a paying fetch (x402)`, 402, body, price, `${this.origin}/credits`);
+    }
+    if (!res.ok) throw new ToolError(`${path} answered HTTP ${res.status}: ${body?.error ?? String(text).slice(0, 200)}`, res.status, body);
+    return body;
+  }
+
+  /** The named tools as OpenAI function-calling definitions; pass the model's tool call to `call(name, JSON.parse(arguments))`. */
+  async openAiTools(names) {
+    const all = await this.tools();
+    const picked = names ? names.map((n) => { const t = all.find((x) => x.name === n || x.path === n); if (!t) throw new ToolError(`no tool named "${n}"`, 404, null); return t; }) : all;
+    return picked.map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description.slice(0, 1000),
+        parameters: { type: "object", properties: Object.fromEntries(t.params.map((p) => [p.name, { type: p.type, description: p.description }])), required: t.params.filter((p) => p.required).map((p) => p.name) },
+      },
+    }));
+  }
+}

package/mcp-stdio.mjs

@@ -0,0 +1,97 @@
+// `agent-data-tools mcp`: a stdio MCP server that forwards every JSON-RPC message to the remote server at <origin>/mcp
+// (streamable HTTP) and writes the answers back, one JSON message per line. No dependencies.
+// Only JSON-RPC lines go to stdout; everything else goes to stderr.
+
+const log = (...a) => { try { process.stderr.write(`agent-data-tools mcp: ${a.join(" ")}\n`); } catch { /* stderr closed */ } };
+const isRequest = (m) => m && typeof m === "object" && typeof m.method === "string" && m.id !== undefined && m.id !== null;
+
+/** Parse an SSE body as it arrives and hand each `data:` payload (joined across lines of one event) to `onData`. */
+async function readSse(body, onData) {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const flush = (block) => {
+    const data = block.split("\n").filter((l) => l.startsWith("data:")).map((l) => l.slice(5).replace(/^ /, "")).join("\n");
+    if (data) onData(data);
+  };
+  for await (const chunk of body) {
+    buffer = (buffer + decoder.decode(chunk, { stream: true })).replace(/\r\n?/g, "\n");
+    let cut;
+    while ((cut = buffer.indexOf("\n\n")) >= 0) { flush(buffer.slice(0, cut)); buffer = buffer.slice(cut + 2); }
+  }
+  buffer = (buffer + decoder.decode()).replace(/\r\n?/g, "\n");
+  if (buffer.trim()) flush(buffer);
+}
+
+/**
+ * Forward one client message (or batch) and write whatever comes back.
+ * @param {{ url: string, key?: string, session: { id?: string, protocol?: string }, write: (m: unknown) => void, fetch?: typeof fetch }} ctx
+ */
+export async function forward(ctx, message) {
+  const requests = (Array.isArray(message) ? message : [message]).filter(isRequest);
+  const answered = new Set();
+  const out = (m) => {
+    for (const one of Array.isArray(m) ? m : [m]) {
+      if (!one || typeof one !== "object") continue;
+      if (one.id !== undefined && one.id !== null && !one.method) answered.add(one.id);
+      const protocol = one.result?.protocolVersion;
+      if (typeof protocol === "string" && requests.some((r) => r.method === "initialize" && r.id === one.id)) ctx.session.protocol = protocol;
+      ctx.write(one);
+    }
+  };
+  const fail = (text) => { for (const r of requests) if (!answered.has(r.id)) ctx.write({ jsonrpc: "2.0", id: r.id, error: { code: -32000, message: text } }); };
+  try {
+    const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
+    if (ctx.key) headers.authorization = `Bearer ${ctx.key}`;
+    if (ctx.session.id) headers["mcp-session-id"] = ctx.session.id;
+    if (ctx.session.protocol) headers["mcp-protocol-version"] = ctx.session.protocol;
+    const res = await (ctx.fetch ?? globalThis.fetch)(ctx.url, { method: "POST", headers, body: JSON.stringify(message) });
+    const session = res.headers.get("mcp-session-id");
+    if (session) ctx.session.id = session;
+    const type = (res.headers.get("content-type") ?? "").toLowerCase();
+    if (res.ok && type.includes("text/event-stream") && res.body) {
+      await readSse(res.body, (data) => { try { out(JSON.parse(data)); } catch { log("ignored an event that is not JSON"); } });
+      if (requests.some((r) => !answered.has(r.id))) fail("the server closed the stream without an answer");
+      return;
+    }
+    const text = await res.text();
+    let body;
+    try { body = text ? JSON.parse(text) : undefined; } catch { body = undefined; }
+    const rpc = (Array.isArray(body) ? body : [body]).every((m) => m && typeof m === "object" && m.jsonrpc === "2.0");
+    if (body !== undefined && rpc) { out(body); if (res.ok) return; }
+    if (res.ok) { if (requests.length) fail("the server answered without a JSON-RPC message"); return; }
+    const detail = typeof body?.error === "string" ? body.error : text.replace(/\s+/g, " ").trim().slice(0, 200);
+    log(`HTTP ${res.status}`);
+    fail(`the server answered HTTP ${res.status}${detail ? `: ${detail}` : ""}`);
+  } catch (e) {
+    log(`request failed: ${e?.message ?? e}`);
+    fail(`could not reach the server: ${e?.cause?.code ?? e?.message ?? "network error"}`);
+  }
+}
+
+/** Run the proxy on stdin/stdout until stdin closes. */
+export async function runStdioProxy({ origin, key, input = process.stdin, output = process.stdout }) {
+  const ctx = { url: `${origin.replace(/\/$/, "")}/mcp`, key, session: {}, write: (m) => output.write(`${JSON.stringify(m)}\n`) };
+  log(`forwarding to ${ctx.url}${key ? " with a key" : " without a key (free calls)"}`);
+  const pending = new Set();
+  let gate = Promise.resolve(); // initialize finishes before anything after it is sent, so the session id is known
+  const handle = (line) => {
+    if (!line.trim()) return;
+    let message;
+    try { message = JSON.parse(line); } catch { ctx.write({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } }); return; }
+    const first = Array.isArray(message) ? message.some((m) => m?.method === "initialize") : message?.method === "initialize";
+    const run = gate.then(() => forward(ctx, message)).catch((e) => log(`unexpected: ${e?.message ?? e}`));
+    if (first) gate = run;
+    pending.add(run);
+    run.finally(() => pending.delete(run));
+  };
+  let buffer = "";
+  input.setEncoding("utf8");
+  input.on("data", (chunk) => {
+    buffer += chunk;
+    let cut;
+    while ((cut = buffer.indexOf("\n")) >= 0) { handle(buffer.slice(0, cut)); buffer = buffer.slice(cut + 1); }
+  });
+  await new Promise((done) => { input.on("end", done); input.on("close", done); input.on("error", done); });
+  if (buffer.trim()) handle(buffer);
+  while (pending.size) await Promise.allSettled([...pending]);
+}

package/package.json

@@ -1,6 +1,52 @@
-{
-  "name": "agent-data-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "agent-data-tools",
+  "version": "1.1.0",
+  "description": "Data tools for AI agents, one call each: PDF to text, web page to Markdown, web search, news, token prices, OFAC sanctions checks, chain reads, IP geolocation, hosted pages. 25 free calls, then card credits or x402.",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "bin": {
+    "agent-data-tools": "cli.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "cli.mjs",
+    "mcp-stdio.mjs",
+    "examples",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://agent-data-tools.revmesh2074.workers.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nutshell2000/agent-data-tools.git",
+    "directory": "clients/agent-data-tools"
+  },
+  "keywords": [
+    "ai-agent",
+    "agent-tools",
+    "function-calling",
+    "openai-tools",
+    "mcp",
+    "mcp-server",
+    "claude",
+    "cursor",
+    "x402",
+    "pdf-to-text",
+    "web-scraping",
+    "html-to-markdown",
+    "web-search",
+    "news-api",
+    "token-price",
+    "crypto-price",
+    "ofac",
+    "sanctions-screening",
+    "ip-geolocation",
+    "llm-tools"
+  ]
+}