@arcnow/mcp 0.1.0

package/dist/client-options.js

@@ -0,0 +1,22 @@
+/**
+ * The options the SDK client is built from, out of a {@link ServerConfig}.
+ *
+ * Its own module, rather than three lines in `index.ts`, so the one thing that
+ * decides which deployment the server talks to — the preset or the network
+ * file, the endpoint override, the signer — is testable without starting a
+ * process.
+ *
+ * @module
+ */
+export function clientOptionsFor(config) {
+    const rpcUrl = config.rpcUrlForClient();
+    const account = config.account();
+    return {
+        // Already resolved by the SDK in loadConfig: the caps were checked against
+        // this same list of quote tokens, so the client must not resolve another.
+        network: config.networkConfig,
+        ...(rpcUrl === undefined ? {} : { rpcUrl }),
+        ...(account === undefined ? {} : { account }),
+    };
+}
+//# sourceMappingURL=client-options.js.map

package/dist/client-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-options.js","sourceRoot":"","sources":["../src/client-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,MAAM,UAAU,gBAAgB,CAC9B,MAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,EAAE,CAAC;IACxC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;IACjC,OAAO;QACL,2EAA2E;QAC3E,0EAA0E;QAC1E,OAAO,EAAE,MAAM,CAAC,aAAa;QAC7B,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3C,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,223 @@
+/**
+ * How this server is configured, and the one decision that matters.
+ *
+ * # A private key is never a tool argument
+ *
+ * Every write this server can do needs a key. That key is read **here**, from
+ * the process environment or from a file the operator names, and from nowhere
+ * else. No tool takes one, no tool schema has a field for one, and
+ * `test/unit/no-key-arguments.test.ts` walks every published schema to keep it
+ * that way.
+ *
+ * The reason is not that arguments are less secure than environment variables
+ * in general. It is that a tool argument is **written by a model, into a
+ * transcript**. It goes to the model provider, into whatever log the client
+ * keeps, into the context of every later turn, and into the bug report someone
+ * pastes into an issue. A key that has been through a tool call is a key that
+ * has been published, and there is no way to un-publish it. The environment is
+ * read by one process, in one place, at startup.
+ *
+ * The key never leaves this module either: {@link ServerConfig} holds a viem
+ * `Account` behind a private field and its `toJSON` is the redacted
+ * description, so a config object that ends up in a log line or an error dump
+ * carries an address and not a secret.
+ *
+ * # Read-only is the default, and writing is the operator's decision
+ *
+ * A key being present is **not** consent to spend it. Writing requires
+ * `--allow-writes` (or `ARCNOW_MCP_ALLOW_WRITES=1`) from whoever starts the
+ * process — a person editing a config file, not a model mid-conversation — and
+ * the mode is printed on stderr at startup and reported by the
+ * `arcnow_network` tool, so neither the operator nor the model has to guess.
+ *
+ * A key with no opt-in starts read-only and says so loudly. An opt-in with no
+ * key refuses to start: the operator asked for something this process cannot
+ * do, and a server that quietly downgrades is a server whose failures arrive
+ * later, as "why did it not buy".
+ *
+ * # Spend caps are per quote token, and a quote with no cap is refused
+ *
+ * A curve is priced in native USDC or an allowlisted ERC-20 such as EURC, and
+ * one number in USDC cannot cap a spend in EURC. So the operator sets one cap
+ * per quote token, each in that quote's own units:
+ *
+ * - `ARCNOW_MCP_MAX_SPEND_USDC` caps native USDC, and defaults to 100.
+ * - `ARCNOW_MCP_MAX_SPEND_<SYMBOL>` caps every other quote: `ARCNOW_MCP_MAX_SPEND_EURC=50`.
+ *   The symbol is the quote's symbol upper-cased, with anything but a letter
+ *   or a digit written as `_`.
+ *
+ * Fail-closed, in four ways. A quote with **no** cap is refused for every
+ * spending write — launch and buy — and non-native quotes get no default, so a
+ * cap can never be got round by switching quote. A symbol resolves **only**
+ * against the network's own `quoteTokens` (the SDK's `networks.json`, or the
+ * network file), never against a token's on-chain `symbol()`, so a token cannot
+ * call itself EURC and borrow EURC's cap; a quote the network does not list can
+ * have no cap and is always refused. A cap variable naming no quote token of
+ * the network is a startup error, which catches typos. And two quote tokens of
+ * the network sharing a symbol is a startup error, because their two caps would
+ * be one variable.
+ *
+ * # A network the SDK has no preset for
+ *
+ * `ARCNOW_MCP_NETWORK_FILE` names a JSON document in the SDK's `CustomNetwork`
+ * shape — `rpcUrl`, `chainId`, `contracts`, and optionally `quoteTokens` and
+ * `quoteAllowanceSlots` — for a local anvil stack or a fork. It is validated by
+ * the SDK's own `resolveNetwork`, and is mutually exclusive with a preset name.
+ *
+ * @module
+ */
+import type { Account, Address } from "viem";
+import type { NetworkConfig, QuoteTokenInfo } from "@arcnow/sdk";
+import { QuoteAmount } from "@arcnow/sdk";
+/** Bad configuration, phrased for the person who wrote it. */
+export declare class ConfigError extends Error {
+    readonly name = "ConfigError";
+}
+/** Read-only, or writing. There is no third state and nothing in between. */
+export type ServerMode = "read-only" | "write";
+/** How far back the launch-log scan is allowed to reach in one tool call. */
+export interface LogScanLimits {
+    readonly chunkBlocks: bigint;
+    readonly maxChunks: number;
+}
+/** The environment variable that caps native USDC. */
+export declare const NATIVE_CAP_VARIABLE = "ARCNOW_MCP_MAX_SPEND_USDC";
+/** Every per-quote cap variable starts with this. */
+export declare const CAP_VARIABLE_PREFIX = "ARCNOW_MCP_MAX_SPEND_";
+/** One quote token's cap, as the operator set it. */
+export interface SpendCap {
+    /** The quote, from the network's `quoteTokens`. */
+    readonly token: QuoteTokenInfo;
+    /** The environment variable that sets it. */
+    readonly variable: string;
+    /** The most one write call may spend in this quote. `undefined`: no cap, every spend refused. */
+    readonly cap: QuoteAmount | undefined;
+}
+/** The variable capping `token`: `ARCNOW_MCP_MAX_SPEND_USDC` if native, else `…_<SYMBOL>`. */
+export declare function capVariableFor(token: QuoteTokenInfo): string;
+/** The redacted view: everything about this server except the secret. */
+export interface ConfigDescription {
+    readonly network: string;
+    /** The network file the network came from, or null for a preset. */
+    readonly networkFile: string | null;
+    readonly rpcUrl: string;
+    readonly mode: ServerMode;
+    readonly signerAddress: Address | null;
+    /** The native USDC cap, as a decimal. */
+    readonly maxSpendPerCallUsdc: string;
+    /** Every quote token's cap by symbol, in its own units; `null` where none is set (refused). */
+    readonly maxSpendPerCall: Readonly<Record<string, string | null>>;
+    readonly logScan: {
+        readonly chunkBlocks: string;
+        readonly maxChunks: number;
+    };
+    readonly warnings: readonly string[];
+}
+/**
+ * The resolved configuration.
+ *
+ * Deliberately a class and not a plain object: the signing account lives in a
+ * `#` field that nothing can enumerate, and `toJSON` is the redacted
+ * description. Anything that stringifies this — a log line, an error cause, a
+ * crash dump — gets an address.
+ */
+export declare class ServerConfig {
+    #private;
+    /** The network's name: the preset's, or the network file's. */
+    readonly network: string;
+    /** The network, resolved by the SDK: what the client is built on and caps resolve against. */
+    readonly networkConfig: NetworkConfig;
+    /** The network file it came from, when it did. */
+    readonly networkFile: string | undefined;
+    /** Already redacted of any credential: this is the value that gets printed. */
+    readonly rpcUrl: string;
+    readonly mode: ServerMode;
+    readonly signerAddress: Address | undefined;
+    /**
+     * The ceiling this process will spend in any one write call, per quote token,
+     * whatever a tool argument asks for. The operator's numbers, not the model's.
+     */
+    readonly spendCaps: readonly SpendCap[];
+    readonly logScan: LogScanLimits;
+    /** Things worth saying at startup that are not fatal. */
+    readonly warnings: readonly string[];
+    constructor(init: {
+        network: string;
+        networkConfig: NetworkConfig;
+        networkFile: string | undefined;
+        rpcUrlRaw: string | undefined;
+        rpcUrlDisplay: string;
+        mode: ServerMode;
+        account: Account | undefined;
+        spendCaps: readonly SpendCap[];
+        logScan: LogScanLimits;
+        warnings: readonly string[];
+    });
+    /** The signer, when this server is in write mode. `undefined` otherwise. */
+    account(): Account | undefined;
+    /** The endpoint to actually connect to, credential and all. */
+    rpcUrlForClient(): string | undefined;
+    /**
+     * The cap for a quote token, by ADDRESS — never by symbol, so a token that
+     * calls itself EURC is not EURC. `undefined` for a quote the network does not
+     * list, which no variable can cap.
+     */
+    spendCapFor(token: QuoteTokenInfo | string): SpendCap | undefined;
+    /** The native USDC cap, which always exists: it defaults to 100. */
+    get maxSpendPerCallUsdc(): QuoteAmount;
+    /** True when write tools are published and callable. */
+    get canWrite(): boolean;
+    describe(): ConfigDescription;
+    /** Redacted by construction: whatever stringifies a config gets this. */
+    toJSON(): ConfigDescription;
+}
+/** Defaults, named so they can be quoted in documentation and in tests. */
+export declare const DEFAULTS: {
+    readonly network: "arc-testnet";
+    /**
+     * 100 USDC a call. Low enough that a prompt-injected "buy everything" is a
+     * bounded accident and not a bounded-by-your-balance one; high enough that
+     * the shipped 2 USDC launch fee plus a real first buy fits under it. An
+     * operator who means to spend more says so once, at startup, on purpose.
+     *
+     * Native USDC only. Every other quote has NO default: spending it is refused
+     * until the operator names a cap for it.
+     */
+    readonly maxSpendPerCallUsdc: "100";
+    /**
+     * Arc's public endpoint has not documented a `eth_getLogs` range limit, so
+     * the scan is chunked rather than asking for six million blocks and finding
+     * out. 10,000 blocks a request, twenty requests: a bounded amount of work for
+     * a tool call, and the result says how far back it actually reached instead
+     * of implying it saw everything.
+     */
+    readonly logChunkBlocks: 10000n;
+    readonly logMaxChunks: 20;
+};
+/**
+ * Strip anything secret out of an endpoint before it is ever printed.
+ *
+ * A private RPC endpoint is very often `https://host/v2/<api-key>` or
+ * `https://user:pass@host`. This server prints its endpoint at startup and in
+ * `arcnow_network`, and a model reads that output — so the path and the
+ * userinfo go, and what is left is the origin plus a marker saying something
+ * was there.
+ */
+export declare function redactUrl(raw: string): string;
+/**
+ * Turn an environment and a command line into a {@link ServerConfig}.
+ *
+ * Pure apart from the `readFile` it is handed, so the whole configuration
+ * surface — including every refusal — is testable without a process, a file or
+ * a key that is worth anything.
+ */
+export declare function loadConfig(env: Readonly<Record<string, string | undefined>>, argv?: readonly string[], readFile?: (path: string) => string): ServerConfig;
+/**
+ * The startup banner, on **stderr**.
+ *
+ * stdout belongs to the MCP transport and a stray byte there corrupts the
+ * protocol frame, so nothing in this server ever writes to it. The banner says
+ * the mode first, because that is the fact an operator is checking for.
+ */
+export declare function startupBanner(config: ServerConfig): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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