dexe-mcp 0.7.1 → 0.8.0

package/dist/index.js

@@ -1,23 +1,43 @@
 #!/usr/bin/env node
 import { resolve, dirname } from "node:path";
-import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig } from "./config.js";
 import { registerAll } from "./tools/index.js";
-// Load .env from project root if present — ensures env vars reach the process
-// regardless of how the MCP host launches us (Claude Code drops most env vars
-// from its settings.json "env" block on Windows).
+import { loadEnvFile, writeStartupBanner } from "./env/loader.js";
+import { envKeys } from "./env/schema.js";
+// Snapshot DEXE_* schema keys already in process.env BEFORE we load .env.
+// Anything found here was injected by the MCP host (Claude Code's
+// .claude.json `env` block) and will SHADOW the .env file —
+// `process.loadEnvFile()` does NOT override pre-set keys. The startup banner
+// (and dexe_doctor) surface the collision so users don't chase a phantom
+// "I edited .env and nothing changed" bug.
+//
+// This must run BEFORE the CLI subcommand dispatch below: `npx dexe-mcp
+// doctor` invoked directly from a shell needs the same env as the MCP
+// startup path, otherwise the diagnostic sees an empty config.
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const dotenvPath = resolve(__dirname, "..", ".env");
-if (existsSync(dotenvPath)) {
-    try {
-        process.loadEnvFile(dotenvPath);
-    }
-    catch {
-        // Node < 21.7 or other issue — fall through to process.env as-is
-    }
+const prevSnapshot = new Set(envKeys().filter(k => !!process.env[k]?.trim()));
+const envReport = loadEnvFile(dotenvPath, prevSnapshot);
+writeStartupBanner(envReport);
+// CLI subcommand dispatch. `npx dexe-mcp` (no args) → MCP server.
+// `npx dexe-mcp doctor` → run diagnostics and exit.
+// `npx dexe-mcp init`   → run the onboarding wizard and exit.
+// Keeps a single bin entry instead of shipping parallel scripts.
+// Subcommands must be handled BEFORE the stdio transport opens — the MCP
+// host passes no args, so any argv[2] means a human/CI invoked directly.
+const subcommand = process.argv[2];
+if (subcommand === "doctor") {
+    const mod = await import("./cli/doctor.js");
+    await mod.run();
+    process.exit(0);
+}
+if (subcommand === "init") {
+    const mod = await import("./cli/init.js");
+    await mod.run();
+    process.exit(0);
 }
 async function main() {
     const config = await loadConfig();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,8EAA8E;AAC9E,8EAA8E;AAC9E,kDAAkD;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACpD,IAAI,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;IACnE,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAElC,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,EACtC;QACE,YAAY,EACV,mRAAmR;KACtR,CACF,CAAC;IAEF,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,qDAAqD;IACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,qDAAqD,MAAM,CAAC,YAAY,GACtE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EACrC,IAAI,CACL,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,GAAG,IAAI,CAAC,CAAC;IAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/requireEnv.d.ts

@@ -0,0 +1,30 @@
+import { type EnvKey } from "../env/schema.js";
+/**
+ * Result of a soft env guard. `ok` carries the resolved value; the error
+ * branch carries both a one-line `error` and a multi-line `remediation`
+ * with paste-ready fixes. Tool handlers fold these into MCP `errorResult`.
+ *
+ * Modeled on the long-standing `requirePinata` pattern in
+ * `src/tools/ipfs.ts:129-137` so existing call sites need only a minimal
+ * refactor.
+ */
+export type EnvGuardResult<T> = {
+    ok: T;
+} | {
+    error: string;
+    remediation: string;
+};
+/**
+ * Soft env-var guard. Returns `{ ok }` only when every listed key is present
+ * and non-blank in `process.env`; otherwise returns a remediation hint that
+ * names the missing keys and the flows they unlock.
+ */
+export declare function requireEnv<K extends EnvKey>(keys: readonly K[]): EnvGuardResult<Record<K, string>>;
+/**
+ * Build a human-readable remediation string for a list of (possibly missing)
+ * env keys. Pulls per-key documentation and flow-enable metadata out of
+ * ENV_SPEC and tacks on the restart reminder so MCP clients don't keep
+ * retrying without picking up the new env.
+ */
+export declare function hintFor(keys: readonly EnvKey[]): string;
+//# sourceMappingURL=requireEnv.d.ts.map

package/dist/lib/requireEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireEnv.d.ts","sourceRoot":"","sources":["../../src/lib/requireEnv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,IAAI,EAAE,SAAS,CAAC,EAAE,GACjB,cAAc,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAkBnC;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAevD"}

package/dist/lib/requireEnv.js

@@ -0,0 +1,48 @@
+import { ENV_REGISTRY } from "../env/schema.js";
+/**
+ * Soft env-var guard. Returns `{ ok }` only when every listed key is present
+ * and non-blank in `process.env`; otherwise returns a remediation hint that
+ * names the missing keys and the flows they unlock.
+ */
+export function requireEnv(keys) {
+    const missing = [];
+    const out = {};
+    for (const k of keys) {
+        const v = process.env[k]?.trim();
+        if (!v) {
+            missing.push(k);
+        }
+        else {
+            out[k] = v;
+        }
+    }
+    if (missing.length > 0) {
+        return {
+            error: `Missing required env: ${missing.join(", ")}`,
+            remediation: hintFor(missing),
+        };
+    }
+    return { ok: out };
+}
+/**
+ * Build a human-readable remediation string for a list of (possibly missing)
+ * env keys. Pulls per-key documentation and flow-enable metadata out of
+ * ENV_SPEC and tacks on the restart reminder so MCP clients don't keep
+ * retrying without picking up the new env.
+ */
+export function hintFor(keys) {
+    const parts = [];
+    for (const k of keys) {
+        const spec = ENV_REGISTRY[k];
+        if (!spec)
+            continue;
+        const flowHint = spec.enablesFlows?.length
+            ? ` (enables: ${spec.enablesFlows.join(", ")})`
+            : "";
+        parts.push(`Set ${k} in .env — ${spec.doc}${flowHint}`);
+    }
+    parts.push("After editing .env, restart the MCP server (Claude Code: quit + relaunch). " +
+        "Run dexe_doctor to verify the new values were picked up.");
+    return parts.join("\n");
+}
+//# sourceMappingURL=requireEnv.js.map

package/dist/lib/requireEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireEnv.js","sourceRoot":"","sources":["../../src/lib/requireEnv.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAe,MAAM,kBAAkB,CAAC;AAa7D;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,IAAkB;IAElB,MAAM,OAAO,GAAQ,EAAE,CAAC;IACxB,MAAM,GAAG,GAAG,EAAuB,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,KAAK,EAAE,yBAAyB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YACpD,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC;SAC9B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,IAAuB;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM;YACxC,CAAC,CAAC,cAAc,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAC/C,CAAC,CAAC,EAAE,CAAC;QACP,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,CAAC,GAAG,GAAG,QAAQ,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,KAAK,CAAC,IAAI,CACR,6EAA6E;QAC3E,0DAA0D,CAC7D,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/lib/signer.d.ts

@@ -1,5 +1,6 @@
 import { Wallet } from "ethers";
 import { type DexeConfig } from "../config.js";
+import { type EnvGuardResult } from "./requireEnv.js";
 /**
  * Per-chain signer cache. The private key is chain-agnostic; only the
  * provider differs per chain.
@@ -22,6 +23,13 @@ export declare class SignerManager {
      * omitted the default chain is used.
      */
     requireSigner(chainId?: number): Wallet;
+    /**
+     * Soft variant of `requireSigner` — returns a structured `{error, remediation}`
+     * instead of throwing when the key or RPC is missing. Hot tool paths use
+     * this so missing env surfaces as a clean MCP error with fix instructions
+     * instead of a thrown stack trace.
+     */
+    trySigner(chainId?: number): EnvGuardResult<Wallet>;
     private failNoKey;
 }
 //# sourceMappingURL=signer.d.ts.map

package/dist/lib/signer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/lib/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,MAAM,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAE7D;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;gBAExB,MAAM,EAAE,UAAU;IAK9B,SAAS,IAAI,OAAO;IAIpB,wFAAwF;IACxF,SAAS,IAAI,UAAU;IAIvB;;;OAGG;IACH,UAAU,IAAI,MAAM;IAKpB;;;OAGG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;IAYvC,OAAO,CAAC,SAAS;CAMlB"}
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/lib/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,MAAM,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE/D;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;gBAExB,MAAM,EAAE,UAAU;IAK9B,SAAS,IAAI,OAAO;IAIpB,wFAAwF;IACxF,SAAS,IAAI,UAAU;IAIvB;;;OAGG;IACH,UAAU,IAAI,MAAM;IAKpB;;;OAGG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;IAYvC;;;;;OAKG;IACH,SAAS,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC;IAWnD,OAAO,CAAC,SAAS;CAMlB"}

package/dist/lib/signer.js

@@ -1,5 +1,6 @@
 import { JsonRpcProvider, Wallet } from "ethers";
 import { resolveChain } from "../config.js";
+import { hintFor } from "./requireEnv.js";
 /**
  * Per-chain signer cache. The private key is chain-agnostic; only the
  * provider differs per chain.
@@ -44,6 +45,23 @@ export class SignerManager {
         }
         return wallet;
     }
+    /**
+     * Soft variant of `requireSigner` — returns a structured `{error, remediation}`
+     * instead of throwing when the key or RPC is missing. Hot tool paths use
+     * this so missing env surfaces as a clean MCP error with fix instructions
+     * instead of a thrown stack trace.
+     */
+    trySigner(chainId) {
+        try {
+            return { ok: this.requireSigner(chainId) };
+        }
+        catch (err) {
+            return {
+                error: err instanceof Error ? err.message : String(err),
+                remediation: hintFor(["DEXE_PRIVATE_KEY"]),
+            };
+        }
+    }
     failNoKey() {
         const dexeEnvKeys = Object.keys(process.env).filter(k => k.startsWith("DEXE_")).join(", ");
         throw new Error(`DEXE_PRIVATE_KEY not set. Available DEXE_* env vars: [${dexeEnvKeys}]. Configure it in MCP server env to enable transaction signing.`);

package/dist/lib/signer.js.map

@@ -1 +1 @@
-{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/lib/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,YAAY,EAAmB,MAAM,cAAc,CAAC;AAE7D;;;GAGG;AACH,MAAM,OAAO,aAAa;IACP,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAClC,GAAG,CAAqB;IACxB,MAAM,CAAa;IAEpC,YAAY,MAAkB;QAC5B,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,SAAS;QACP,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;IACpB,CAAC;IAED,wFAAwF;IACxF,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,OAAgB;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjD,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACnD,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,SAAS;QACf,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3F,MAAM,IAAI,KAAK,CACb,yDAAyD,WAAW,kEAAkE,CACvI,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/lib/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,YAAY,EAAmB,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAuB,MAAM,iBAAiB,CAAC;AAE/D;;;GAGG;AACH,MAAM,OAAO,aAAa;IACP,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAClC,GAAG,CAAqB;IACxB,MAAM,CAAa;IAEpC,YAAY,MAAkB;QAC5B,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,SAAS;QACP,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;IACpB,CAAC;IAED,wFAAwF;IACxF,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,IAAI,CAAC,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,OAAgB;QAC5B,IAAI,CAAC,IAAI,CAAC,GAAG;YAAE,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjD,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,QAAQ,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACnD,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,SAAS,CAAC,OAAgB;QACxB,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;gBACvD,WAAW,EAAE,OAAO,CAAC,CAAC,kBAAkB,CAAC,CAAC;aAC3C,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,SAAS;QACf,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3F,MAAM,IAAI,KAAK,CACb,yDAAyD,WAAW,kEAAkE,CACvI,CAAC;IACJ,CAAC;CACF"}

package/dist/rpc.d.ts

@@ -1,5 +1,6 @@
 import { JsonRpcProvider } from "ethers";
 import { type DexeConfig } from "./config.js";
+import type { EnvGuardResult } from "./lib/requireEnv.js";
 /**
  * Lazy ethers v6 provider factory. Gov tools that need an RPC endpoint call
  * `requireProvider(chainId?)`; tools that don't (decode_calldata,
@@ -13,6 +14,13 @@ export declare class RpcProvider {
     private readonly cache;
     constructor(config: DexeConfig);
     requireProvider(chainId?: number): JsonRpcProvider;
+    /**
+     * Soft variant of `requireProvider` — returns a structured
+     * `{error, remediation}` instead of throwing when no RPC is configured
+     * for the requested chain. Hot read paths use this so missing env surfaces
+     * as a clean MCP error with fix instructions instead of a thrown stack.
+     */
+    tryProvider(chainId?: number): EnvGuardResult<JsonRpcProvider>;
     /** Returns the resolved chain id (after applying the default). Cheap. */
     resolveChainId(chainId?: number): number;
 }

package/dist/rpc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;;;;GAOG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;gBAE/B,MAAM,EAAE,UAAU;IAE/C,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe;IAUlD,yEAAyE;IACzE,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;CAGzC"}
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;GAOG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;gBAE/B,MAAM,EAAE,UAAU;IAE/C,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe;IAUlD;;;;;OAKG;IACH,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,cAAc,CAAC,eAAe,CAAC;IAa9D,yEAAyE;IACzE,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;CAGzC"}

package/dist/rpc.js

@@ -23,6 +23,24 @@ export class RpcProvider {
         }
         return provider;
     }
+    /**
+     * Soft variant of `requireProvider` — returns a structured
+     * `{error, remediation}` instead of throwing when no RPC is configured
+     * for the requested chain. Hot read paths use this so missing env surfaces
+     * as a clean MCP error with fix instructions instead of a thrown stack.
+     */
+    tryProvider(chainId) {
+        try {
+            return { ok: this.requireProvider(chainId) };
+        }
+        catch (err) {
+            return {
+                error: err instanceof Error ? err.message : String(err),
+                remediation: "Set DEXE_RPC_URL_TESTNET / DEXE_RPC_URL_MAINNET / DEXE_RPC_URL_<chainId> in .env, " +
+                    "then restart the MCP server (Claude Code: quit + relaunch). Run dexe_doctor to verify.",
+            };
+        }
+    }
     /** Returns the resolved chain id (after applying the default). Cheap. */
     resolveChainId(chainId) {
         return resolveChain(this.config, chainId).chainId;

package/dist/rpc.js.map

@@ -1 +1 @@
-{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IAGO;IAFZ,KAAK,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE5D,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD,eAAe,CAAC,OAAgB;QAC9B,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjD,IAAI,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,yEAAyE;IACzE,cAAc,CAAC,OAAgB;QAC7B,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IACpD,CAAC;CACF"}
+{"version":3,"file":"rpc.js","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzC,OAAO,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AAG5D;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IAGO;IAFZ,KAAK,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE5D,YAA6B,MAAkB;QAAlB,WAAM,GAAN,MAAM,CAAY;IAAG,CAAC;IAEnD,eAAe,CAAC,OAAgB;QAC9B,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjD,IAAI,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;OAKG;IACH,WAAW,CAAC,OAAgB;QAC1B,IAAI,CAAC;YACH,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;gBACvD,WAAW,EACT,oFAAoF;oBACpF,wFAAwF;aAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,cAAc,CAAC,OAAgB;QAC7B,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IACpD,CAAC;CACF"}

package/dist/tools/doctor.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DexeConfig } from "../config.js";
+/**
+ * `dexe_doctor` — first stop when an MCP tool reports an env-related failure.
+ * Walks ENV_SPEC, runs network reachability for everything configured, and
+ * returns a structured report with paste-ready remediation hints.
+ *
+ * Read-only. Never broadcasts. Safe to call at session start.
+ */
+export declare function registerDoctorTool(server: McpServer, config: DexeConfig): void;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/tools/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/tools/doctor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AA2B/C;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAkC9E"}

package/dist/tools/doctor.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { runAllChecks, } from "../diag/checks.js";
+function tally(results) {
+    let passed = 0;
+    let warnings = 0;
+    let failures = 0;
+    for (const r of results) {
+        if (r.status === "pass")
+            passed++;
+        else if (r.status === "warn")
+            warnings++;
+        else
+            failures++;
+    }
+    const status = failures > 0 ? "fail" : warnings > 0 ? "warn" : "pass";
+    return { passed, warnings, failures, status };
+}
+/**
+ * `dexe_doctor` — first stop when an MCP tool reports an env-related failure.
+ * Walks ENV_SPEC, runs network reachability for everything configured, and
+ * returns a structured report with paste-ready remediation hints.
+ *
+ * Read-only. Never broadcasts. Safe to call at session start.
+ */
+export function registerDoctorTool(server, config) {
+    server.tool("dexe_doctor", "Diagnose env-var setup. Runs presence + reachability checks (RPC, Pinata, IPFS gateway DNS, subgraph, backend) and returns a pass/warn/fail report with remediation hints. " +
+        "Call FIRST when the user reports an env-related failure — it pinpoints the missing or invalid value. " +
+        "Read-only: never broadcasts, never writes. ", {
+        _placeholder: z
+            .boolean()
+            .optional()
+            .describe("Unused; tool takes no input."),
+    }, async () => {
+        const checks = await runAllChecks({ config });
+        const summary = tally(checks);
+        const remediationSummary = checks
+            .filter(c => c.status !== "pass" && c.remediation)
+            .map(c => `${c.id}: ${c.remediation.split("\n")[0]}`);
+        const startupTime = new Date(Date.now() - process.uptime() * 1000).toISOString();
+        const structured = {
+            summary,
+            checks,
+            remediationSummary,
+            startupTime,
+            uptimeSec: Math.round(process.uptime()),
+        };
+        return {
+            content: [{ type: "text", text: renderText(structured) }],
+            structuredContent: structured,
+        };
+    });
+}
+function renderText(r) {
+    const lines = [];
+    lines.push(`dexe-mcp doctor — ${r.summary.status.toUpperCase()}: ${r.summary.passed} pass / ${r.summary.warnings} warn / ${r.summary.failures} fail`);
+    lines.push(`server started ${r.startupTime} (uptime ${r.uptimeSec}s). ` +
+        `If you just edited .env, restart Claude Code so the new values load.`);
+    lines.push("");
+    for (const c of r.checks) {
+        const tag = c.status === "pass" ? " OK " : c.status === "warn" ? "WARN" : "FAIL";
+        lines.push(`  [${tag}] ${c.id}  ${c.message}`);
+        if (c.remediation) {
+            for (const rl of c.remediation.split("\n")) {
+                lines.push(`         → ${rl}`);
+            }
+        }
+    }
+    if (r.remediationSummary.length) {
+        lines.push("");
+        lines.push("To fix:");
+        r.remediationSummary.forEach((m, i) => lines.push(`  ${i + 1}) ${m}`));
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=doctor.js.map

package/dist/tools/doctor.js.map

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

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAmC/C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAuCvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAoC/C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAyCvE"}

package/dist/tools/index.js

@@ -19,6 +19,7 @@ import { registerDaoDeployTools } from "./daoDeploy.js";
 import { registerSubgraphTools } from "./subgraph.js";
 import { registerTxTools } from "./txSend.js";
 import { registerGetConfigTool } from "./getConfig.js";
+import { registerDoctorTool } from "./doctor.js";
 import { registerWalletConnectTools } from "./walletconnectStatus.js";
 import { registerFlowTools } from "./flow.js";
 import { registerMerkleTools } from "./merkle.js";
@@ -63,6 +64,8 @@ export function registerAll(server, config) {
     const wc = new WalletConnectManager(config);
     registerTxTools(server, config, signer, wc);
     registerGetConfigTool(server, config, signer);
+    // Diagnostics — call dexe_doctor first when env-related failures show up.
+    registerDoctorTool(server, config);
     registerWalletConnectTools(server, config, signer, wc);
     registerFlowTools(server, ctx, signer);
     registerOtcTools(server, ctx, signer);

package/dist/tools/index.js.map

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

package/dist/tools/read.js

@@ -89,7 +89,10 @@ function registerMulticall(server, rpc) {
         },
     }, async ({ calls }) => {
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const batch = calls.map((c) => {
                 if (!isAddress(c.target))
                     throw new Error(`Invalid target: ${c.target}`);
@@ -147,7 +150,10 @@ function registerTreasury(server, rpc) {
         if (!isAddress(holder))
             return errorResult(`Invalid holder: ${holder}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const native = (await provider.getBalance(holder)).toString();
             const iface = new Interface(ERC20_ABI);
             const calls = [];
@@ -198,7 +204,10 @@ function registerValidators(server, rpc) {
         if (candidate && !isAddress(candidate))
             return errorResult(`Invalid candidate: ${candidate}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const gp = new Interface(GOV_POOL_ABI);
             const v = new Interface(GOV_VALIDATORS_ABI);
             const [helpersR] = await multicall(provider, [
@@ -255,7 +264,10 @@ function registerSettings(server, rpc) {
         if (!isAddress(govPool))
             return errorResult(`Invalid govPool: ${govPool}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const gp = new Interface(GOV_POOL_ABI);
             const s = new Interface(GOV_SETTINGS_ABI);
             const [helpersR] = await multicall(provider, [
@@ -312,7 +324,10 @@ function registerExpertStatus(server, rpc) {
         if (!isAddress(user))
             return errorResult(`Invalid user: ${user}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const gp = new Interface(GOV_POOL_ABI);
             const babt = new Interface(BABT_ABI);
             const [expertR, nftR] = await multicall(provider, [
@@ -361,7 +376,10 @@ function registerTokenSaleTiers(server, rpc) {
         if (!isAddress(tokenSaleProposal))
             return errorResult(`Invalid tokenSaleProposal: ${tokenSaleProposal}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const iface = new Interface(TOKEN_SALE_READ_ABI);
             const [countR] = await multicall(provider, [
                 { target: tokenSaleProposal, iface, method: "latestTierId", args: [], allowFailure: true },
@@ -403,7 +421,10 @@ function registerTokenSaleUser(server, rpc) {
         if (!isAddress(user))
             return errorResult(`Invalid user: ${user}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const iface = new Interface(TOKEN_SALE_READ_ABI);
             const [viewsR] = await multicall(provider, [
                 {
@@ -442,7 +463,10 @@ function registerDistributionStatus(server, rpc) {
         if (!isAddress(voter))
             return errorResult(`Invalid voter: ${voter}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const iface = new Interface(DISTRIBUTION_READ_ABI);
             const calls = [];
             for (const pid of proposalIds) {
@@ -485,7 +509,10 @@ function registerStakingInfo(server, rpc) {
         if (user && !isAddress(user))
             return errorResult(`Invalid user: ${user}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const iface = new Interface(STAKING_READ_ABI);
             const baseCalls = [
                 { target: stakingProposal, iface, method: "stakingsCount", args: [], allowFailure: true },
@@ -525,7 +552,10 @@ function registerPrivacyPolicyStatus(server, rpc) {
         if (!isAddress(user))
             return errorResult(`Invalid user: ${user}`);
         try {
-            const provider = rpc.requireProvider();
+            const pr = rpc.tryProvider();
+            if ("error" in pr)
+                return errorResult(`${pr.error}\n${pr.remediation}`);
+            const provider = pr.ok;
             const iface = new Interface(USER_REGISTRY_READ_ABI);
             const [hashR, agreedR] = await multicall(provider, [
                 { target: userRegistry, iface, method: "documentHash", args: [], allowFailure: true },