@haven_ai/mcp 0.0.0-dev.202609031523.fd49e1a

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { HavenClient } from '@haven_ai/sdk';
+import { z } from 'zod/v3';
+
+interface HavenCredentialFile {
+    apiKey: string;
+    delegateKey: string;
+    agentId?: string;
+    safeAddress?: string;
+    delegateAddress?: string;
+    chainId?: number;
+    network?: string;
+    apiUrl?: string;
+    allowanceSummary?: readonly HavenCredentialAllowance[];
+    /**
+     * Absolute path the credentials were loaded from, if any. Set when the
+     * caller pointed at a JSON file via `--credentials` or `HAVEN_CREDENTIALS`;
+     * left undefined when credentials came purely from environment variables.
+     * The MCP server uses this to locate the consent sidecar
+     * (`<sourcePath>.ack.json`) so `--ack` works regardless of how the
+     * credential path was supplied.
+     */
+    sourcePath?: string;
+    identityPath?: string;
+    signerPath?: string;
+}
+interface HavenCredentialAllowance {
+    token: string;
+    amount: string;
+    resetMinutes: number | null;
+}
+interface HavenCredentialSource {
+    credentialsPath?: string;
+    identityPath?: string;
+    signerPath?: string;
+}
+/**
+ * Load Haven agent credentials for the MCP server.
+ *
+ * Resolution order — earlier sources win, later sources are fallbacks:
+ *
+ *   1. Explicit `path` argument (typically from `--credentials <path>`).
+ *   2. `HAVEN_CREDENTIALS` env var pointing at a credential JSON file.
+ *   3. Inline env vars: `HAVEN_API_KEY` + `HAVEN_DELEGATE_KEY` (+ optional
+ *      `HAVEN_AGENT_ID`, `HAVEN_SAFE_ADDRESS`, `HAVEN_API_URL`).
+ *
+ * The inline-env path exists so that runtime config snippets emitted by the
+ * Haven dashboard (Claude Desktop / Cursor / generic MCP configs) can be a
+ * single self-contained block — paste the snippet, restart the runtime, done.
+ * The values still live only in the agent operator's process environment;
+ * Haven's backend never sees the delegate key either way.
+ */
+declare function loadCredentials(source?: string | HavenCredentialSource | undefined): Promise<HavenCredentialFile>;
+
+/**
+ * Local (stdio) MCP tool handlers. This package runs in the AGENT OPERATOR'S
+ * OWN environment — it reads the local credential file and signs locally; the
+ * hosted backend is not in the loop for the merchant call. So `merchant_url`
+ * passed to `haven.fetch` below is NOT an SSRF surface: the agent is the
+ * principal paying a merchant IT chose, on its own machine — the same trust
+ * position as running `curl`. There is no server reflecting attacker input
+ * into an internal request. (Hosted, multi-tenant fetches live in mcp-server,
+ * which is where URL-hardening would matter.)
+ */
+
+type HavenMcpToolName = 'haven_send' | 'haven_pay_mcp_tool' | 'haven_quote_x402' | 'haven_pay_x402_quote' | 'haven_pay_x402' | 'haven_resume_x402_payment' | 'haven_get_payment_status' | 'haven_get_resume_state' | 'haven_get_agent' | 'haven_get_allowances' | 'haven_list_receipts' | 'haven_verify_receipt' | 'haven_sweep_delegate' | 'haven_discover_tools' | 'haven_submit_catalog_entry';
+declare const toolSchemas: Record<HavenMcpToolName, z.ZodRawShape>;
+/**
+ * MCP tool descriptions, composed from the shared semantic source in
+ * `@haven_ai/sdk`'s `tool-descriptions.ts`. Keeping both the SDK tool-calling
+ * surface and the MCP surface pointed at the same prose source means new
+ * guidance lands in both places at once and a parity test can catch drift.
+ */
+declare const toolDescriptions: Record<HavenMcpToolName, string>;
+interface ToolSuccess<T> {
+    success: true;
+    data: T;
+}
+interface ToolFailure {
+    success: false;
+    code: string;
+    message: string;
+    /** Structured hint pointing the agent at the correct tool for this operation. */
+    suggested_tool?: string;
+    statusCode?: number;
+    paymentId?: string;
+    status?: string;
+    phase?: string;
+    nextAction?: string;
+    resume_state?: unknown;
+    body?: unknown;
+}
+type ToolPayload<T = unknown> = ToolSuccess<T> | ToolFailure;
+declare function createToolHandlers(haven: HavenClient): Record<HavenMcpToolName, (input: unknown) => Promise<ToolPayload>>;
+
+/**
+ * First-launch consent gate for the Haven MCP server.
+ *
+ * Why this exists (option A of issue #163): an agent runtime that loads a
+ * Haven credential file is about to expose Haven payment tools to a model.
+ * Before the server starts taking JSON-RPC calls we want the operator to
+ * acknowledge — exactly once per credential + tool set — what those tools
+ * can do and what the on-chain budget actually is. The agent's budget
+ * delegation and its caveat enforcers remain the policy primitive; this gate
+ * is informational rather than enforcement.
+ *
+ * #2086: the copy below used to describe the legacy Safe AllowanceModule and
+ * an approval queue that would catch an over-budget payment. Both are gone —
+ * the AllowanceModule rail is retired (#1986) and the approval queue's table
+ * with it (#2055) — so the gate was promising an operator a human backstop
+ * that does not exist. It is now one accurate description of the delegation
+ * rail rather than rail-aware prose, because the delegation rail is the only
+ * rail that can pay at all: a legacy account gets HTTP 410 from the payment
+ * paths, so a second branch here would describe a state no reader can be in.
+ *
+ * Resolution:
+ *   - `HAVEN_MCP_ACK=<hash>` env var matching the current consent hash → pass.
+ *   - `HAVEN_MCP_ACK=skip` → pass (intended for CI / scripted setups).
+ *   - sidecar file `<credentials>.ack.json` containing `{ ack: <hash> }` → pass.
+ *   - `--ack` CLI flag → write the sidecar file, print the consent block, pass.
+ *   - otherwise → print the consent block to stderr and exit non-zero.
+ *
+ * The hash binds the api-key prefix to the registered tool set and the
+ * agent's current allowance summary, so a configuration change re-triggers
+ * the prompt.
+ */
+interface ConsentInput {
+    apiKeyPrefix: string;
+    /** Haven API base URL the credential will hit. */
+    apiUrl?: string;
+    /** Agent identity from the credential file, when present. */
+    agentId?: string;
+    /** Haven wallet (Safe) the agent spends from. */
+    safeAddress?: string;
+    /** Agent's delegate EOA — the local signer. */
+    delegateAddress?: string;
+    /** Chain the agent operates on. */
+    chainId?: number;
+    toolNames: readonly HavenMcpToolName[];
+    allowanceSummary: readonly {
+        token: string;
+        amount: string;
+        resetMinutes: number | null;
+    }[];
+}
+interface ConsentDecision {
+    /** True if the gate is satisfied and the server may start. */
+    ok: boolean;
+    /** Hash representing the current consent surface. */
+    hash: string;
+    /** Reason the gate accepted (or rejected) the run. */
+    reason: 'env_var_match' | 'env_var_skip' | 'ack_file_match' | 'wrote_ack_file' | 'env_var_mismatch' | 'no_acknowledgement';
+}
+interface ConsentOptions {
+    /** Path to the credential file; used to locate the sidecar `<path>.ack.json`. */
+    credentialsPath?: string;
+    /** When true, write the sidecar file with the current hash and accept. */
+    writeAck?: boolean;
+    /** Override the environment lookup (testing). */
+    env?: Record<string, string | undefined>;
+    /** Override the writable stream the consent block is printed to (testing). */
+    out?: {
+        write: (chunk: string) => unknown;
+    };
+}
+declare function computeConsentHash(input: ConsentInput): string;
+declare function renderConsentBlock(input: ConsentInput, hash: string): string;
+/** Resolve the consent gate. Does not exit the process; the caller decides. */
+declare function ensureConsent(input: ConsentInput, options?: ConsentOptions): Promise<ConsentDecision>;
+interface CredentialIdentitySeed {
+    apiKey: string;
+    apiUrl?: string;
+    agentId?: string;
+    /** Safe address from the credential file, used as a fallback. */
+    safeAddress?: string;
+    /** Delegate address from the credential file, used before live allowance metadata is available. */
+    delegateAddress?: string;
+    /** Chain from the credential file, used as a fallback. */
+    chainId?: number;
+    /** Intended agent budget from the setup flow, used before on-chain approval is visible. */
+    allowanceSummary?: readonly {
+        token: string;
+        amount: string;
+        resetMinutes: number | null;
+    }[];
+}
+/**
+ * Build the consent input from credential identity plus a live allowance
+ * lookup. The on-chain (or configured) allowance is what the operator
+ * actually cares about — that's the real spend ceiling — but we also bind
+ * the hash to the Haven wallet / delegate / chain so a credential swap
+ * cannot quietly reuse a prior sidecar acknowledgement.
+ *
+ * If `getAllowances()` fails (e.g. backend unreachable on first launch) we
+ * fall through to whatever identity fields the credential file provided,
+ * so the operator at least sees the tool list and the api-key prefix.
+ */
+declare function consentInputFromClient(haven: HavenClient, seed: CredentialIdentitySeed, toolNames: readonly HavenMcpToolName[]): Promise<ConsentInput>;
+/** Convenience: the canonical tool list registered by the server. */
+declare function registeredToolNames(): HavenMcpToolName[];
+
+interface HavenMcpServerOptions {
+    credentialsPath?: string;
+    identityPath?: string;
+    signerPath?: string;
+    credentials?: HavenCredentialFile;
+    /**
+     * When true, write the consent sidecar file (`<credentials>.ack.json`)
+     * with the current consent hash and proceed. Surfaced via the `--ack`
+     * CLI flag.
+     */
+    writeAck?: boolean;
+    /**
+     * When true, skip the consent gate entirely. Reserved for tests and
+     * controlled embedding — production CLIs should not set this.
+     */
+    skipConsent?: boolean;
+    /** Overridable so the Node-floor refusal is testable without spawning a Node. */
+    nodeVersion?: string;
+}
+interface ResolvedHavenClient {
+    client: HavenClient;
+    credentials: HavenCredentialFile;
+}
+declare function createHavenClient(options?: HavenMcpServerOptions): Promise<HavenClient>;
+declare function resolveHavenClient(options?: HavenMcpServerOptions): Promise<ResolvedHavenClient>;
+declare function createHavenMcpServer(options?: HavenMcpServerOptions): Promise<McpServer>;
+/**
+ * Build an MCP server bound to the supplied Haven client.
+ *
+ * Each tool dispatch is wrapped in `haven.withRequestContext` so every
+ * Haven API request the dispatch issues carries `X-Haven-MCP-Tool: <name>`
+ * — and *only* that dispatch's requests see the header. The SDK uses an
+ * `AsyncLocalStorage` for the context, so two tool calls running
+ * concurrently cannot leak headers into each other and the backend
+ * `agent_tool_invocations` rows are always attributed to the right tool.
+ */
+declare const MCP_NAME = "@haven_ai/mcp";
+declare const MCP_VERSION = "0.0.0-dev.202609031523.fd49e1a";
+/**
+ * Refuse to start on an unsupported Node (#1161).
+ *
+ * Same reasoning as the signer's identical guard: install-time enforcement
+ * cannot see a Node downgrade after setup, or a version manager handing the
+ * agent runtime a different Node than the shell that connected. The local MCP
+ * server drives payment construction against the signer, so it is held to the
+ * package's declared floor rather than whatever happens to boot.
+ */
+declare function assertSupportedNodeVersion(nodeVersion?: string): void;
+declare function runStdioServer(options?: HavenMcpServerOptions): Promise<void>;
+
+export { type ConsentDecision, type ConsentInput, type ConsentOptions, type CredentialIdentitySeed, type HavenCredentialAllowance, type HavenCredentialFile, type HavenCredentialSource, type HavenMcpServerOptions, type HavenMcpToolName, MCP_NAME, MCP_VERSION, type ToolFailure, type ToolPayload, type ToolSuccess, assertSupportedNodeVersion, computeConsentHash, consentInputFromClient, createHavenClient, createHavenMcpServer, createToolHandlers, ensureConsent, loadCredentials, registeredToolNames, renderConsentBlock, resolveHavenClient, runStdioServer, toolDescriptions, toolSchemas };