@naulon/wayfarer-mcp 0.2.0

package/README.md

@@ -0,0 +1,196 @@
+# @naulon/wayfarer-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets any
+LLM **discover, quote, pay, and cite** naulon-tolled sources — bring your own
+wallet, local stdio, the [wayfarer](../wayfarer) brain running in-process.
+
+Point any MCP-capable client at this server and the model gains tools to find
+tolled articles, get a quote, pay the `402` toll from a wallet you control, and
+cite what it bought — the same budgeted buying loop the CLI agent runs, exposed
+as callable tools and slash commands.
+
+Works with **any MCP client**: Claude Code, Claude Desktop, Cursor, Windsurf,
+Cline, VS Code, or your own host. Setup for each is below.
+
+---
+
+## Quick start
+
+```bash
+npx -y @naulon/wayfarer-mcp        # runs the stdio MCP server
+```
+
+The package is scoped (`@naulon/wayfarer-mcp`); the binary it installs is
+`wayfarer-mcp`. It runs **offline against mock settlement by default** — safe to
+try with zero config, no wallet, no spend. To pay real tolls, see
+[Configuration](#configuration).
+
+The canonical registration, which every client below is a variant of:
+
+```jsonc
+{
+  "mcpServers": {
+    "naulon": { "command": "npx", "args": ["-y", "@naulon/wayfarer-mcp"] }
+  }
+}
+```
+
+---
+
+## Slash commands (prompts)
+
+Every prompts-capable client surfaces these as native, argument-taking slash
+commands — no per-user config. In Claude Code / Desktop they appear as
+`/mcp__naulon__<name>` (the `naulon` segment is whatever you named the server):
+
+| Prompt | Argument | Does |
+|--------|----------|------|
+| `research` | `topic` | Discover sources, see prices, return a grounded cited answer within budget. |
+| `discover` | `topic` | List candidate sources — **free**, no payment. |
+| `verify` | `claim` | Fact-check a claim against tolled sources, citing what it paid for. |
+| `ask`\* | `question` | Hosted reading agent: pays per citation, returns a grounded answer. |
+
+\* `ask` is only present on the **hosted** endpoint (it drives the cloud
+`naulon_ask` tool). The stdio server exposes `research` / `discover` / `verify`.
+
+---
+
+## Per-client setup
+
+### Claude Code
+
+CLI (recommended — `--scope project` writes a shared `.mcp.json`, `user` makes it
+global across your projects):
+
+```bash
+claude mcp add naulon --scope user -- npx -y @naulon/wayfarer-mcp
+```
+
+Then `/mcp` inside Claude Code to confirm it connected, and type `/` to see the
+`research` / `discover` / `verify` prompts. Or add it by hand to `.mcp.json`
+(project) using the canonical block above.
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
+
+```jsonc
+{
+  "mcpServers": {
+    "naulon": { "command": "npx", "args": ["-y", "@naulon/wayfarer-mcp"] }
+  }
+}
+```
+
+Restart Claude Desktop. Prompts appear in the `+` / slash-command menu.
+
+### Cursor
+
+`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project), key
+`mcpServers` — same canonical block above.
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`, key `mcpServers` — same canonical block.
+
+### VS Code (native MCP / Copilot agent)
+
+`.vscode/mcp.json` (workspace). VS Code uses the `servers` key (not
+`mcpServers`); the `type` is inferred as stdio from `command`, so it's optional:
+
+```jsonc
+{
+  "servers": {
+    "naulon": { "command": "npx", "args": ["-y", "@naulon/wayfarer-mcp"] }
+  }
+}
+```
+
+### Cline
+
+Cline → MCP Servers → Configure (`cline_mcp_settings.json`), key `mcpServers` —
+same canonical block.
+
+### Any other MCP host
+
+Spawn the stdio binary and speak MCP over its stdio transport:
+
+```
+command: npx   args: ["-y", "@naulon/wayfarer-mcp"]
+```
+
+---
+
+## Hosted endpoint (no local wallet)
+
+naulon-cloud exposes the same brain over **Streamable HTTP** at `/_naulon/mcp`,
+authenticated with an agent token — tolls are signed by naulon's custody-free
+session key, so **no private key ever touches your machine**. This endpoint also
+adds the cloud-only `naulon_ask` tool + its `ask` prompt.
+
+Clients that support remote/HTTP MCP with headers:
+
+```bash
+# Claude Code
+claude mcp add --transport http naulon \
+  https://<your-naulon-host>/_naulon/mcp \
+  --header "Authorization: Bearer <AGENT_TOKEN>"
+```
+
+```jsonc
+// Generic HTTP MCP config
+{
+  "mcpServers": {
+    "naulon": {
+      "type": "http",
+      "url": "https://<your-naulon-host>/_naulon/mcp",
+      "headers": { "Authorization": "Bearer <AGENT_TOKEN>" }
+    }
+  }
+}
+```
+
+Mint the agent token from your naulon buyer wallet / dashboard. Spend is bounded
+by the server budget **and** the token's sub-cap — the model can lower a run's
+budget, never raise it past either.
+
+---
+
+## Configuration
+
+Env read by the stdio server (all optional — omit for the offline mock):
+
+| Var | Purpose |
+|-----|---------|
+| `PAYMENT_MODE` | `gateway` to pay real tolls over Circle Gateway on Arc Network (default: mock). |
+| `BUYER_PRIVATE_KEY` | The wallet the toll is paid from. BYO-key path; a hosted deploy signs through a cloud signer instead. |
+| `TOLLGATE_URL` | The gate every payment resolves against. Payments only ever flow here — a prompt-injected model cannot redirect them. |
+| `WAYFARER_BUDGET_USDC` | The session spend ceiling. The model can never raise it. |
+| `WAYFARER_ALLOW_DOMAINS` / `WAYFARER_DENY_DOMAINS` | Publisher allow/deny lists for `naulon_research`. |
+| `WAYFARER_PER_DOMAIN_CAP` | Max paid reads per publisher per session. |
+| `WAYFARER_KILL_SWITCH` | Hard stop — refuse all spend. |
+
+Budget and wallet are **server config, never tool arguments** — the model plans
+spend within the envelope but can't widen it.
+
+---
+
+## Tools
+
+| Tool | Cost | Does |
+|------|------|------|
+| `naulon_discover` | free | Candidate teasers for a topic (slug, title, summary). Start here. |
+| `naulon_appraise` | free | Relevance + rationale for teasers already held. |
+| `naulon_quote` | free | The x402 `402` probe — real price + terms, **no spend**. |
+| `naulon_pay_and_read` | **$** | Pays the toll, returns content + settlement ref + citation license. |
+| `naulon_read_held` | free | Re-read a held live license (PoP-signed if cnf-bound). |
+| `naulon_research` | **$** | One composite that runs the whole discover→quote→pay→ground loop. |
+| `naulon_ask`\* | **$** | Hosted-only reading agent — grounded, numbered-citation answer. |
+
+\* hosted endpoint only. All tools carry MCP annotations (`readOnlyHint` on the
+free ones) so clients render safe-vs-spends correctly.
+
+---
+
+MIT.

package/dist/cloud-signer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The cloud MemoSigner (BUY-2). Wires the wayfarer memo buyer to naulon's hosted, grant-checked
+ * signer instead of a local private key: each EIP-3009 leg is POSTed to `/_naulon/buyer-wallet/
+ * sign-memo`, which holds the encrypted session key, enforces the grant (cap + TTL), and returns just
+ * the signature. So the MCP process never touches a private key — the custody-free hosted path.
+ *
+ * The endpoint + token are SERVER-CONFIG (env), never LLM tool args — the model cannot point the
+ * signer elsewhere or raise its own spend ceiling. The chainId is taken from the request's own domain,
+ * so it can never drift from what wayfarer is paying against.
+ */
+import type { AgentWallet, MemoSigner } from "@naulon/wayfarer";
+/** The grant CAP/budget refused the spend — funding the session is the remedy. The message STARTS with the
+ *  raw code (`grant_exceeded`) so memo.ts's message-prefix classifier maps it to `needs_topup`, not a
+ *  retryable `origin_error` (mirrors in-process-signer.ts, which already throws code-prefixed messages). */
+export declare class GrantExceededError extends Error {
+    readonly remainingMicro?: number | undefined;
+    constructor(remainingMicro?: number | undefined);
+}
+/** The grant WINDOW lapsed though funds may be intact — RENEWING the session is the remedy, not a top-up.
+ *  Distinct class + code-prefixed message so the hosted agent renews rather than funds. */
+export declare class GrantExpiredError extends Error {
+    readonly remainingMicro?: number | undefined;
+    constructor(remainingMicro?: number | undefined);
+}
+/** Any other non-ok response from the signer BFF (bad_from, no_session, chain_mismatch, 5xx, …). */
+export declare class SignerError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, code?: string | undefined);
+}
+export interface CloudSignerOpts {
+    /** Cloud gate base URL, no trailing slash (e.g. https://gate.naulon.app). This is the
+     *  naulon gate origin that serves the `/_naulon/*` routes — NOT the REST/API edge. */
+    endpoint: string;
+    /** Per-session bearer token — server-config, never a tool arg. */
+    token: string;
+    /** The provisioned session EOA address (the `from` every leg signs as). */
+    address: `0x${string}`;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Build the cloud signer from environment — the hosted path is opt-in via SERVER-CONFIG, never a tool
+ * arg. All three of NAULON_CLOUD_ENDPOINT / NAULON_CLOUD_TOKEN / NAULON_BUYER_SESSION_ADDRESS must be
+ * present (and the address well-formed) or we return undefined and the caller falls back to the
+ * BYO-key path. This keeps the OSS default (local key) exactly as-is when the cloud isn't configured.
+ */
+export declare function cloudSignerFromEnv(env?: Record<string, string | undefined>): MemoSigner | undefined;
+export declare function cloudMemoSigner(opts: CloudSignerOpts): MemoSigner;
+/**
+ * The cloud PoP signer (Phase 4 / C2). A held re-read of a cnf-bound license must prove control of
+ * the paying wallet by signing an EIP-191 holder-of-key challenge. On the custody-free hosted path the
+ * paying identity is the session EOA, whose key lives encrypted in the cloud — so the proof is signed
+ * by `/_naulon/buyer-wallet/sign-pop` (the session key) rather than a local key. Returns an
+ * `AgentWallet` so `buildPopProof` consumes it exactly like the env wallet.
+ *
+ * Unlike `/sign-memo` this leg is GRANT-FREE: a PoP is a free re-read, not a spend, so there is no cap
+ * to debit. The BFF still authenticates the bearer, checks the `address` matches the session, AND
+ * constrains the signed bytes to a canonical `naulon-pop` challenge — the session key can never be
+ * coerced into signing an arbitrary message. The endpoint + token are SERVER-CONFIG, never a tool arg.
+ */
+export declare function cloudPopSigner(opts: CloudSignerOpts): AgentWallet;
+//# sourceMappingURL=cloud-signer.d.ts.map

package/dist/cloud-signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-signer.d.ts","sourceRoot":"","sources":["../src/cloud-signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;4GAE4G;AAC5G,qBAAa,kBAAmB,SAAQ,KAAK;aACf,cAAc,CAAC,EAAE,MAAM;gBAAvB,cAAc,CAAC,EAAE,MAAM,YAAA;CAIpD;AAED;2FAC2F;AAC3F,qBAAa,iBAAkB,SAAQ,KAAK;aACd,cAAc,CAAC,EAAE,MAAM;gBAAvB,cAAc,CAAC,EAAE,MAAM,YAAA;CAIpD;AAED,oGAAoG;AACpG,qBAAa,WAAY,SAAQ,KAAK;aAElB,MAAM,EAAE,MAAM;aACd,IAAI,CAAC,EAAE,MAAM;gBADb,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED,MAAM,WAAW,eAAe;IAC9B;0FACsF;IACtF,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,UAAU,GAAG,SAAS,CAOxB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,CAwCjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAoBjE"}

package/dist/cloud-signer.js

@@ -0,0 +1,125 @@
+/** The grant CAP/budget refused the spend — funding the session is the remedy. The message STARTS with the
+ *  raw code (`grant_exceeded`) so memo.ts's message-prefix classifier maps it to `needs_topup`, not a
+ *  retryable `origin_error` (mirrors in-process-signer.ts, which already throws code-prefixed messages). */
+export class GrantExceededError extends Error {
+    remainingMicro;
+    constructor(remainingMicro) {
+        super(`grant_exceeded${remainingMicro !== undefined ? ` (remaining ${remainingMicro})` : ""}`);
+        this.remainingMicro = remainingMicro;
+        this.name = "GrantExceededError";
+    }
+}
+/** The grant WINDOW lapsed though funds may be intact — RENEWING the session is the remedy, not a top-up.
+ *  Distinct class + code-prefixed message so the hosted agent renews rather than funds. */
+export class GrantExpiredError extends Error {
+    remainingMicro;
+    constructor(remainingMicro) {
+        super(`grant_expired${remainingMicro !== undefined ? ` (remaining ${remainingMicro})` : ""}`);
+        this.remainingMicro = remainingMicro;
+        this.name = "GrantExpiredError";
+    }
+}
+/** Any other non-ok response from the signer BFF (bad_from, no_session, chain_mismatch, 5xx, …). */
+export class SignerError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(`sign-memo failed: ${status}${code ? ` ${code}` : ""}`);
+        this.status = status;
+        this.code = code;
+        this.name = "SignerError";
+    }
+}
+/**
+ * Build the cloud signer from environment — the hosted path is opt-in via SERVER-CONFIG, never a tool
+ * arg. All three of NAULON_CLOUD_ENDPOINT / NAULON_CLOUD_TOKEN / NAULON_BUYER_SESSION_ADDRESS must be
+ * present (and the address well-formed) or we return undefined and the caller falls back to the
+ * BYO-key path. This keeps the OSS default (local key) exactly as-is when the cloud isn't configured.
+ */
+export function cloudSignerFromEnv(env = process.env) {
+    const endpoint = env.NAULON_CLOUD_ENDPOINT;
+    const token = env.NAULON_CLOUD_TOKEN;
+    const address = env.NAULON_BUYER_SESSION_ADDRESS;
+    if (!endpoint || !token || !address)
+        return undefined;
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address))
+        return undefined;
+    return cloudMemoSigner({ endpoint, token, address: address });
+}
+export function cloudMemoSigner(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    return {
+        address: opts.address,
+        async signTypedData(args) {
+            const m = args.message;
+            const res = await doFetch(`${opts.endpoint}/_naulon/buyer-wallet/sign-memo`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
+                // BigInt can't be JSON-serialized — send the EIP-3009 fields as decimal strings. The BFF
+                // rebuilds the domain + types authoritatively; we send only the leg's message primitives.
+                body: JSON.stringify({
+                    chainId: Number(args.domain.chainId),
+                    message: {
+                        from: m.from,
+                        to: m.to,
+                        value: m.value.toString(),
+                        validAfter: m.validAfter.toString(),
+                        validBefore: m.validBefore.toString(),
+                        nonce: m.nonce,
+                    },
+                }),
+            });
+            if (res.status === 402) {
+                // The BFF returns 402 for BOTH grant stops (sign.ts:57/60). Read `error` to pick the remedy:
+                // grant_expired ⇒ renew (funds intact); grant_exceeded / anything else ⇒ top up (fund the session).
+                const body = (await res.json().catch(() => ({})));
+                throw body.error === "grant_expired"
+                    ? new GrantExpiredError(body.remainingMicro)
+                    : new GrantExceededError(body.remainingMicro);
+            }
+            if (!res.ok) {
+                const body = (await res.json().catch(() => ({})));
+                throw new SignerError(res.status, body.error);
+            }
+            const body = (await res.json().catch(() => ({})));
+            if (!body.signature)
+                throw new SignerError(res.status, "no_signature");
+            return body.signature;
+        },
+    };
+}
+/**
+ * The cloud PoP signer (Phase 4 / C2). A held re-read of a cnf-bound license must prove control of
+ * the paying wallet by signing an EIP-191 holder-of-key challenge. On the custody-free hosted path the
+ * paying identity is the session EOA, whose key lives encrypted in the cloud — so the proof is signed
+ * by `/_naulon/buyer-wallet/sign-pop` (the session key) rather than a local key. Returns an
+ * `AgentWallet` so `buildPopProof` consumes it exactly like the env wallet.
+ *
+ * Unlike `/sign-memo` this leg is GRANT-FREE: a PoP is a free re-read, not a spend, so there is no cap
+ * to debit. The BFF still authenticates the bearer, checks the `address` matches the session, AND
+ * constrains the signed bytes to a canonical `naulon-pop` challenge — the session key can never be
+ * coerced into signing an arbitrary message. The endpoint + token are SERVER-CONFIG, never a tool arg.
+ */
+export function cloudPopSigner(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    return {
+        address: opts.address,
+        mock: false,
+        signMessage: async (message) => {
+            const res = await doFetch(`${opts.endpoint}/_naulon/buyer-wallet/sign-pop`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${opts.token}`, "content-type": "application/json" },
+                body: JSON.stringify({ address: opts.address, message }),
+            });
+            if (!res.ok) {
+                const body = (await res.json().catch(() => ({})));
+                throw new SignerError(res.status, body.error);
+            }
+            const body = (await res.json().catch(() => ({})));
+            if (!body.signature)
+                throw new SignerError(res.status, "no_signature");
+            return body.signature;
+        },
+    };
+}
+//# sourceMappingURL=cloud-signer.js.map

package/dist/cloud-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-signer.js","sourceRoot":"","sources":["../src/cloud-signer.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * stdio entry point — an MCP client (Claude Desktop, Cursor, …) spawns this as a
+ * child process and speaks JSON-RPC over stdin/stdout.
+ *
+ * Hard rule for stdio servers: stdout is the protocol channel. Nothing but
+ * JSON-RPC may be written there — all diagnostics go to stderr, or they corrupt
+ * the stream.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildServer } from "./server.js";
+async function main() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("naulon-wayfarer-mcp: listening on stdio\n");
+}
+main().catch((err) => {
+    process.stderr.write(`naulon-wayfarer-mcp: failed to start — ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,WAAW,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;AACpE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0CAA0C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrH,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/lib.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @naulon/wayfarer-mcp — public library surface.
+ *
+ * The side-effect-free barrel the package.json `exports` map points at. `index.ts`
+ * (the stdio bin) is a thin consumer of `buildServer`, never the other way round —
+ * so the cloud can `buildServer()` and wrap it over its own authenticated transport
+ * without dragging in the stdio bootstrap.
+ */
+export { buildServer, SERVER_NAME, SERVER_VERSION, type BuildServerOptions, type DecisionAuditEvent } from "./server.ts";
+export { cloudMemoSigner, cloudPopSigner, cloudSignerFromEnv, GrantExceededError, SignerError, type CloudSignerOpts, } from "./cloud-signer.ts";
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACzH,OAAO,EACL,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC"}

package/dist/lib.js

@@ -0,0 +1,11 @@
+/**
+ * @naulon/wayfarer-mcp — public library surface.
+ *
+ * The side-effect-free barrel the package.json `exports` map points at. `index.ts`
+ * (the stdio bin) is a thin consumer of `buildServer`, never the other way round —
+ * so the cloud can `buildServer()` and wrap it over its own authenticated transport
+ * without dragging in the stdio bootstrap.
+ */
+export { buildServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+export { cloudMemoSigner, cloudPopSigner, cloudSignerFromEnv, GrantExceededError, SignerError, } from "./cloud-signer.js";
+//# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAoD,MAAM,aAAa,CAAC;AACzH,OAAO,EACL,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,GAEZ,MAAM,mBAAmB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @naulon/wayfarer-mcp — the MCP server factory.
+ *
+ * Exposes naulon's pay-per-citation pipeline to any MCP-capable LLM. The wayfarer
+ * brain runs IN-PROCESS here (no remote service, BYO wallet never leaves the
+ * machine) — the deliberate contrast to a thin client that pays a hosted brain.
+ *
+ * Tools are deliberately GRANULAR and quote-first: the host model sees prices and
+ * plans spend before any payment, rather than calling one black-box "research"
+ * verb. The §3.1 surface (BUY-1.2) is:
+ *
+ *   naulon_discover     free — candidate teasers for a topic
+ *   naulon_appraise     free — relevance + rationale for teasers the model holds
+ *   naulon_quote        free — the x402 402 probe: real price + terms, NO spend
+ *   naulon_pay_and_read  $   — pays, returns content + settlementRef + license jti
+ *   naulon_read_held    free — re-read a held live license (PoP-signed if cnf-bound)
+ *   naulon_research      $   — one composite that runs the whole loop for lazy clients
+ *
+ * Two deliberate shapes vs the spec's conceptual `url(...)` signatures:
+ *   - Tools take a SLUG, never a raw URL. The server resolves it against the
+ *     server-configured gate (TOLLGATE_URL), so a prompt-injected model can never
+ *     redirect a payment to an attacker's endpoint — payment only ever flows to
+ *     the configured gate. (Same "config, not tool args" principle BUY-1.3 applies
+ *     to the budget + wallet.)
+ *   - `kind` is pinned to "citation": the MCP's purpose is grounded, citable
+ *     research, so every quote/pay/re-read asks for a citation license.
+ *
+ * Budget + wallet are SERVER-CONFIG, never tool args (BUY-1.3). The wallet comes
+ * from the env (`BUYER_PRIVATE_KEY` / the dev key) via `getWallet()`; the budget is
+ * a single ceiling (`WAYFARER_BUDGET_USDC`) the model cannot raise. Each server
+ * instance carries a SESSION SPEND ENVELOPE: every paid read debits a running total,
+ * the free tools report "$Y remaining", and a spend that would exceed the ceiling is
+ * refused (spending nothing). `naulon_research` accepts an optional `budgetUsdc` the
+ * server CLAMPS to what remains — the model can spend less, never more.
+ *
+ * The explicit toll-moved tolerance + validity-at-pay margin guards are BUY-1.4.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { AgentWallet, DecisionPolicy, GatewaySigner, HeldStore, MemoSigner, RailSigners } from "@naulon/wayfarer";
+export declare const SERVER_NAME = "naulon-wayfarer-mcp";
+/** Keep in step with this package's package.json `version` — it is what the MCP
+ *  handshake reports as `serverInfo.version`. */
+export declare const SERVER_VERSION = "0.2.0";
+/**
+ * Per-session options for the HOSTED path (BUY-4). The stdio funnel reads the
+ * wallet, budget, and policy from process env (one process = one buyer). The cloud
+ * host authenticates MANY buyer sessions over one process, so it injects each
+ * session's config here — and each injected value WINS over env, which stays only
+ * the default when the option is absent (so the stdio funnel is unchanged). One
+ * `buildServer(opts)` per authed session gives per-session budget envelopes for
+ * free, since the envelope is a closure over this call.
+ */
+/**
+ * One buyer spend DECISION, handed to a `BuildServerOptions.auditSink` (BUY-4.4). The
+ * hosted cloud injects a sink that writes each of these to its org-partitioned audit
+ * plane — the same immutable log the sell side uses. A PURE structured hook: the package
+ * never imports the cloud (the one-way dependency), so the sink is injected, not called.
+ *
+ * The four actions mirror the wayfarer decision engine exactly (pay · skip · approve ·
+ * cache). A kill-switch halt or a policy denial surfaces as a `skip` with the halt reason
+ * carried verbatim in `reason` — so nothing is lost to accountability even though it is
+ * not its own verb (the engine emits no distinct "kill"/"deny" action; adding one would
+ * be a decide.ts change, not an audit concern).
+ */
+export interface DecisionAuditEvent {
+    /** The source slug the decision was about. */
+    slug: string;
+    /** The engine decision: paid · skipped (policy/budget/relevance) · flagged for human approval · re-read a held license free. */
+    action: "pay" | "skip" | "approve" | "cache";
+    /** The engine's human-readable reason (carries the kill-switch / deny / budget nuance verbatim). */
+    reason: string;
+    /** The candidate's 0..1 relevance for the topic (research decisions). */
+    relevance?: number;
+    /** The advertised author-leg price in USDC, when known. */
+    priceUsdc?: number;
+    /** The author leg actually paid, in USDC (pay decisions only). */
+    paidUsdc?: number;
+    /** The true total debited across all settlement legs, in USDC (pay_and_read pays only). */
+    costUsdc?: number;
+    /** The on-chain / settlement reference (pay decisions only). */
+    settlementRef?: string;
+    /** The Citation License jti (pay decisions only). */
+    licenseId?: string;
+    /** The policy's agent tag, if configured — audit attribution, not identity. */
+    agentId?: string;
+}
+export interface BuildServerOptions {
+    /**
+     * This session's custody-free cloud signer (else `cloudSignerFromEnv()`). A `MemoSigner`
+     * (memo/Arc rail) or a `GatewaySigner` (memo-less Circle rails — Base + every Gateway
+     * chain); the cloud injects the one matching the active settlement network's rail, and
+     * `buildServer` routes it to the matching buyer (`supportsMemo(activeNetwork())`).
+     */
+    signer?: MemoSigner | GatewaySigner;
+    /**
+     * A mixed-fleet session's BOTH rail signers (RAS-B): the cloud injects a memo AND a gateway
+     * signer wrapping the same sealed session key, and `buildServer` builds a `railBuyer` that picks
+     * the rail from each tenant's advertised 402 — so one process serves an Arc-default fleet with a
+     * Base tenant. Takes precedence over `signer` when present; the single-rail `signer` path stays for
+     * the stdio funnel and any host that settles on one network. Both wrap the same key, so the payer
+     * identity is either signer's `address` (they are equal).
+     */
+    railSigners?: RailSigners;
+    /** This session's spend ceiling in USDC (else `WAYFARER_BUDGET_USDC`). */
+    budgetUsdc?: number;
+    /** This session's decision policy (else the env-derived policy over DEFAULT_POLICY). */
+    policy?: DecisionPolicy;
+    /**
+     * Per-decision audit hook (BUY-4.4). Invoked once per buyer spend decision — a pay, a
+     * skip, an approval-gate, a free cache re-read — with a structured `DecisionAuditEvent`.
+     * The cloud host injects a sink that writes to its org-partitioned audit plane; the stdio
+     * funnel leaves it unset (no sink ⇒ the OSS path is simply unaudited). A pure hook (the
+     * package never imports the cloud), and it is fired best-effort — a throwing sink must
+     * never break a paid read.
+     */
+    auditSink?: (event: DecisionAuditEvent) => void;
+    /**
+     * This session's gate (base URL) — the fleet tenant it settles into (else the env
+     * `TOLLGATE_URL`). The cloud host injects it per authed session so one process can
+     * serve many buyers, each accountable to a specific publisher's 402 (BUY-4.2, the
+     * moat: own both ends of the receipt). Server-config, never a tool arg — a
+     * prompt-injected model can no more redirect the gate than raise the budget.
+     */
+    tollgateUrl?: string;
+    /**
+     * This session's held-license backend. The stdio funnel leaves it unset (the
+     * process-global file `fileHeldStore`). The cloud host MUST inject a per-session
+     * store (e.g. `memoryHeldStore()`) so one process serving many buyers can never
+     * let session B re-read the license session A paid for — the file store is keyed
+     * by slug alone and shared, so without this the hosted path leaks licenses across
+     * buyers. Server-config, never a tool arg.
+     */
+    heldStore?: HeldStore;
+    /**
+     * The wallet that signs proof-of-possession for a cnf-bound held re-read. On a
+     * custody-free hosted deploy the paying identity is the cloud session EOA, but
+     * `getWallet()` (the fallback) returns a throwaway dev key when no
+     * `BUYER_PRIVATE_KEY` is set — so a PoP signed by it can never satisfy a license
+     * cnf-bound to the session address. The cloud injects a signer backed by its
+     * `/sign-pop` BFF (the session key). Absent ⇒ `getWallet()` (unchanged OSS path).
+     * Server-config, never a tool arg — the model cannot point the signer elsewhere.
+     */
+    popWallet?: AgentWallet;
+    /**
+     * Where the agent (or its operator) tops up / renews the funding session — surfaced on a
+     * `needs_topup` / `grant_expired` pay refusal so the refusal is ACTIONABLE, not a dead end. On
+     * the hosted path the cloud injects its portal wallet URL; the stdio funnel leaves it at the
+     * `/buyer/wallet` default. Server-config, never a tool arg. */
+    buyerWalletUrl?: string;
+}
+/**
+ * Build a fresh, unconnected MCP server with the tool surface registered. The
+ * caller connects it to a transport (stdio for the OSS funnel; the cloud wraps it
+ * over an authenticated HTTP transport). A factory — not a singleton — so tests
+ * can stand up an isolated server per case. `opts` supplies per-session config for
+ * the hosted path (BUY-4); absent, every value falls back to process env.
+ */
+export declare function buildServer(opts?: BuildServerOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA2BpE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAgB,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAIrI,eAAO,MAAM,WAAW,wBAAwB,CAAC;AACjD;iDACiD;AACjD,eAAO,MAAM,cAAc,UAAU,CAAC;AAgGtC;;;;;;;;GAQG;AACH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,gIAAgI;IAChI,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IAC7C,oGAAoG;IACpG,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,aAAa,CAAC;IACpC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAChD;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB;;;;mEAI+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,SAAS,CAuyBpE"}