dexe-mcp 0.1.1 → 0.1.2

package/.mcp.example.json

@@ -1,8 +1,8 @@
 {
+  "_comment": "Mac/Linux: use `dexe-mcp` directly. Windows: replace with { command: 'cmd', args: ['/c', 'dexe-mcp'] }. See README.md for the full install matrix.",
   "mcpServers": {
     "dexe": {
-      "command": "npx",
-      "args": ["-y", "dexe-mcp"]
+      "command": "dexe-mcp"
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.2
+
+### Fixed
+- **Server no longer hangs / fails on first launch.** The heavy `git clone` + `npm install` bootstrap is now lazy — it runs only when a build tool (`dexe_compile`, `dexe_test`, `dexe_coverage`, `dexe_lint`) is first invoked, not inside MCP `initialize()`. Previously the MCP handshake would block for minutes or time out, and crash outright on hosts where `npm` / `git` were not on the spawned process's PATH.
+- **PATH-independent spawning of `npm` and `hardhat`.** The runner now invokes `node <npm-cli.js>` and `node <protocol>/node_modules/hardhat/internal/cli/cli.js` directly via `process.execPath`, so it works on Windows installs where `npm.cmd` / `npx.cmd` aren't on the MCP client's spawn PATH (common with nvm-windows and with stripped `node.exe`-only installs).
+- **Actionable error messages** when `git` is not installed, when `DEXE_PROTOCOL_PATH` points at a non-Hardhat directory, or when the user-managed checkout is missing `node_modules`.
+- Concurrent build-tool calls now coalesce into a single bootstrap instead of racing `git clone` / `npm install`.
+
+### Changed
+- `loadConfig()` no longer hard-fails when the DeXe-Protocol checkout is missing or incomplete at startup — it logs a soft warning to stderr and defers preparation to the first build-tool invocation.
+- `src/bootstrap.ts` split into `resolveProtocolPath()` (cheap, startup-safe) and `ensureBuildReady()` (lazy, idempotent).
+- New `src/runtime.ts` with portable `npmCommand()` / `hardhatCommand()` / `hasGit()` helpers.
+
+### Docs
+- README now has an OS-specific install matrix (Mac/Linux vs. Windows) and a "dev / local checkout" recipe. Troubleshooting section updated for the new lazy-bootstrap behavior and the `process.execPath` npm resolution.
+
 ## 0.1.1
 
 ### Added

package/README.md

@@ -6,41 +6,101 @@ MCP server for Claude Code / Antigravity that wraps the [DeXe Protocol](https://
 
 ## Prerequisites
 
-- **Node.js >= 20**
-- **Git** (the server auto-clones DeXe-Protocol on first run)
+- **Node.js >= 20** (with a bundled `npm` — i.e. any official installer, nvm, nvm-windows, or Homebrew build)
+- **Git** — only needed on first run, to clone DeXe-Protocol. If you already have a local checkout, point `DEXE_PROTOCOL_PATH` at it and git is optional.
 
-## Quick start
+## Install
 
-Add this to your project's `.mcp.json` (or your MCP client config):
+### 1. Install the package globally
+
+```bash
+npm install -g dexe-mcp
+```
+
+This installs a `dexe-mcp` binary on your PATH. Verify:
+
+```bash
+dexe-mcp --version   # or:  where dexe-mcp   (Windows)  /  which dexe-mcp   (Mac/Linux)
+```
+
+### 2. Register the MCP server
+
+#### Mac / Linux
+
+```bash
+claude mcp add dexe -- dexe-mcp
+```
+
+Or add to your MCP client config (`.mcp.json`, `claude_desktop_config.json`, etc.):
 
 ```json
 {
   "mcpServers": {
     "dexe": {
-      "command": "npx",
-      "args": ["-y", "dexe-mcp"]
+      "command": "dexe-mcp"
     }
   }
 }
 ```
 
-Restart your MCP client. On first launch, `dexe-mcp` will automatically:
+#### Windows
 
-1. Clone `dexe-network/DeXe-Protocol` to a local cache directory (~200 MB, shallow clone)
-2. Run `npm install` in the checkout
+Windows `CreateProcess` does not resolve `.cmd` shims from a bare command name, so wrap the call with `cmd /c`:
 
-Subsequent launches are instant. No manual setup needed.
+```bash
+claude mcp add dexe -- cmd /c dexe-mcp
+```
+
+Or in JSON:
 
-### Advanced: custom checkout path
+```json
+{
+  "mcpServers": {
+    "dexe": {
+      "command": "cmd",
+      "args": ["/c", "dexe-mcp"]
+    }
+  }
+}
+```
 
-If you already have a DeXe-Protocol checkout or want to control its location:
+**Absolute-path fallback** (works everywhere, zero PATH dependency):
 
 ```json
 {
   "mcpServers": {
     "dexe": {
-      "command": "npx",
-      "args": ["-y", "dexe-mcp"],
+      "command": "node",
+      "args": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/dexe-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### 3. Restart your MCP client
+
+On the first build-tool call (e.g. `dexe_compile`), `dexe-mcp` will automatically:
+
+1. Shallow-clone `dexe-network/DeXe-Protocol` into a platform cache directory (~200 MB)
+2. Run `npm install` in that checkout (a few minutes, one time)
+
+The MCP server itself starts instantly — the heavy work is deferred until you actually need it. Cache locations:
+
+| OS | Path |
+|----|------|
+| Windows | `%LOCALAPPDATA%\dexe-mcp\DeXe-Protocol` |
+| macOS | `~/Library/Caches/dexe-mcp/DeXe-Protocol` |
+| Linux | `$XDG_CACHE_HOME/dexe-mcp/DeXe-Protocol` (or `~/.cache/dexe-mcp/DeXe-Protocol`) |
+
+### Advanced: existing DeXe-Protocol checkout
+
+If you already have a DeXe-Protocol clone you want to reuse (and have run `npm install` there at least once), set `DEXE_PROTOCOL_PATH`:
+
+```json
+{
+  "mcpServers": {
+    "dexe": {
+      "command": "dexe-mcp",
       "env": {
         "DEXE_PROTOCOL_PATH": "/absolute/path/to/your/DeXe-Protocol"
       }
@@ -49,9 +109,36 @@ If you already have a DeXe-Protocol checkout or want to control its location:
 }
 ```
 
+With this set, dexe-mcp will **not** clone or install anything — it trusts the path you gave it. On Windows, wrap `command` with `cmd /c` as above.
+
+### Dev mode (working on dexe-mcp itself)
+
+Clone this repo, build, and point the MCP command at the local `dist/index.js`:
+
+```bash
+git clone https://github.com/edward-arinin-web-dev/dexe-mcp.git
+cd dexe-mcp
+npm install
+npm run build
+```
+
+```json
+{
+  "mcpServers": {
+    "dexe": {
+      "command": "node",
+      "args": ["/absolute/path/to/dexe-mcp/dist/index.js"],
+      "env": {
+        "DEXE_PROTOCOL_PATH": "/absolute/path/to/DeXe-Protocol"
+      }
+    }
+  }
+}
+```
+
 ## First run
 
-Before introspection tools work, run `dexe_compile` once per session to populate `DeXe-Protocol/artifacts/`. You will get a clear "artifacts not found" error otherwise.
+Before introspection tools work, run `dexe_compile` once per session to populate `DeXe-Protocol/artifacts/`. You will get a clear "artifacts not found" error otherwise. On a brand-new install the first `dexe_compile` also triggers the clone + `npm install` steps described above.
 
 ## Tool catalog
 
@@ -89,19 +176,37 @@ Before introspection tools work, run `dexe_compile` once per session to populate
 
 | Variable | Required | Purpose |
 |----------|----------|---------|
-| `DEXE_PROTOCOL_PATH` | no | Override the auto-managed DeXe-Protocol checkout path |
+| `DEXE_PROTOCOL_PATH` | no | Use an existing DeXe-Protocol checkout; disables auto clone/install |
 | `DEXE_RPC_URL` | no | JSON-RPC endpoint for `dexe_decode_proposal` and `dexe_read_gov_state` |
 | `DEXE_FORK_BLOCK` | no | Pin the fork to a specific block (Phase B) |
 
 ## Troubleshooting
 
+### "`git` is not on PATH"
+
+Install git from <https://git-scm.com/downloads> and restart your MCP client. Alternatively, clone DeXe-Protocol manually and set `DEXE_PROTOCOL_PATH` to skip the clone step entirely.
+
+### "`npm install` failed inside DeXe-Protocol"
+
+Usually means your Node install lacks a bundled `npm` (e.g. a stripped `node.exe` dropped on PATH without the rest of the install). Reinstall Node from <https://nodejs.org> or via nvm / nvm-windows and retry. dexe-mcp invokes npm via `process.execPath` so it uses whichever Node is running it — it does not need `npm` on the spawn PATH.
+
+### "Failed to connect" in Claude Code (Windows)
+
+Claude Code spawns MCP servers with `CreateProcess`, which can't resolve `.cmd` shims from a bare name. Wrap the command:
+
+```json
+{ "command": "cmd", "args": ["/c", "dexe-mcp"] }
+```
+
+Or use the absolute-path fallback pointing at `node` + `dist/index.js` directly.
+
 ### "Hardhat artifacts not found — run dexe_compile first"
 
 Introspection tools require compiled artifacts. Run `dexe_compile` once after the initial setup to populate them.
 
-### "Failed to clone DeXe-Protocol"
+### "DEXE_PROTOCOL_PATH=… is missing node_modules"
 
-Make sure `git` is installed and available on your PATH, and that you have internet access. The server clones from `https://github.com/dexe-network/DeXe-Protocol.git`.
+You pointed `DEXE_PROTOCOL_PATH` at a checkout that hasn't been installed yet. `cd` into it and run `npm install` once, then retry.
 
 ### "DEXE_RPC_URL is not set"
 

package/dist/bootstrap.d.ts

@@ -1,12 +1,30 @@
 /**
- * Ensures a DeXe-Protocol checkout is available, returning its absolute path.
+ * Cheap, synchronous resolution of where the DeXe-Protocol checkout *should*
+ * live. **Does not** clone or install anything — safe to call at MCP startup.
  *
  * Priority:
  *  1. `DEXE_PROTOCOL_PATH` env var (power-user override)
- *  2. Auto-managed clone in the platform cache directory
+ *  2. Auto-managed path inside the platform cache directory
  *
- * On first run the clone + npm install may take a few minutes.
- * Progress is logged to stderr (stdout is the MCP protocol channel).
+ * The returned path may not exist yet on disk. Call `ensureBuildReady()`
+ * before invoking tools that require hardhat.
  */
-export declare function ensureProtocolCheckout(): Promise<string>;
+export declare function resolveProtocolPath(): string;
+/**
+ * True if `protocolPath` looks like a hardhat project with installed deps.
+ * Used by build/test tools to short-circuit the lazy bootstrap.
+ */
+export declare function isBuildReady(protocolPath: string): boolean;
+/**
+ * Lazy, expensive bootstrap: ensures a DeXe-Protocol checkout exists at
+ * `protocolPath` and that its npm dependencies are installed. Idempotent.
+ *
+ * Only called from build/test tools. MCP startup must **not** await this.
+ *
+ * Skipped entirely when `DEXE_PROTOCOL_PATH` points at a user-managed
+ * checkout — we trust the user to keep it in shape.
+ *
+ * Throws with an actionable message if `git` or `npm` are unavailable.
+ */
+export declare function ensureBuildReady(protocolPath: string): Promise<void>;
 //# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC,CAgD9D"}
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAO1D;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuF1E"}

package/dist/bootstrap.js

@@ -1,7 +1,10 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir, platform } from "node:os";
-import { execSync } from "node:child_process";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { hasGit, npmCommand } from "./runtime.js";
+const execFileAsync = promisify(execFile);
 const REPO_URL = "https://github.com/dexe-network/DeXe-Protocol.git";
 const CACHE_DIR_NAME = "dexe-mcp";
 const CHECKOUT_DIR = "DeXe-Protocol";
@@ -21,63 +24,119 @@ function getCacheDir() {
     if (os === "darwin") {
         return join(homedir(), "Library", "Caches", CACHE_DIR_NAME);
     }
-    // Linux / others — respect XDG_CACHE_HOME
     const base = process.env.XDG_CACHE_HOME || join(homedir(), ".cache");
     return join(base, CACHE_DIR_NAME);
 }
 function log(msg) {
     process.stderr.write(`[dexe-mcp] ${msg}\n`);
 }
-function runSync(cmd, cwd) {
-    execSync(cmd, { cwd, stdio: ["ignore", "pipe", "pipe"] });
-}
 /**
- * Ensures a DeXe-Protocol checkout is available, returning its absolute path.
+ * Cheap, synchronous resolution of where the DeXe-Protocol checkout *should*
+ * live. **Does not** clone or install anything — safe to call at MCP startup.
  *
  * Priority:
  *  1. `DEXE_PROTOCOL_PATH` env var (power-user override)
- *  2. Auto-managed clone in the platform cache directory
+ *  2. Auto-managed path inside the platform cache directory
  *
- * On first run the clone + npm install may take a few minutes.
- * Progress is logged to stderr (stdout is the MCP protocol channel).
+ * The returned path may not exist yet on disk. Call `ensureBuildReady()`
+ * before invoking tools that require hardhat.
  */
-export async function ensureProtocolCheckout() {
-    // ---- explicit override ----
+export function resolveProtocolPath() {
     const explicit = process.env.DEXE_PROTOCOL_PATH?.trim();
     if (explicit)
         return explicit;
-    // ---- auto-managed clone ----
-    const cacheDir = getCacheDir();
-    const protocolPath = join(cacheDir, CHECKOUT_DIR);
-    if (!existsSync(cacheDir)) {
-        mkdirSync(cacheDir, { recursive: true });
-    }
-    const gitDir = join(protocolPath, ".git");
-    if (!existsSync(gitDir)) {
-        log(`Cloning DeXe-Protocol (shallow, ~200 MB) into ${protocolPath} …`);
-        log("This only happens once. Subsequent launches will be instant.");
-        try {
-            runSync(`git clone --depth 1 ${REPO_URL} "${CHECKOUT_DIR}"`, cacheDir);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(`Failed to clone DeXe-Protocol. Make sure git is installed and you have internet access.\n${msg}`);
-        }
-        log("Clone complete.");
-    }
-    // Ensure npm dependencies are installed
-    const nodeModules = join(protocolPath, "node_modules");
-    if (!existsSync(nodeModules)) {
-        log("Installing DeXe-Protocol npm dependencies (first run only) …");
+    return join(getCacheDir(), CHECKOUT_DIR);
+}
+/**
+ * True if `protocolPath` looks like a hardhat project with installed deps.
+ * Used by build/test tools to short-circuit the lazy bootstrap.
+ */
+export function isBuildReady(protocolPath) {
+    if (!existsSync(protocolPath))
+        return false;
+    const hasConfig = existsSync(join(protocolPath, "hardhat.config.js")) ||
+        existsSync(join(protocolPath, "hardhat.config.ts"));
+    const hasNodeModules = existsSync(join(protocolPath, "node_modules"));
+    return hasConfig && hasNodeModules;
+}
+// Promise-coalescing: if two tools call ensureBuildReady() concurrently,
+// they should share a single clone+install, not race.
+let inflightEnsure = null;
+/**
+ * Lazy, expensive bootstrap: ensures a DeXe-Protocol checkout exists at
+ * `protocolPath` and that its npm dependencies are installed. Idempotent.
+ *
+ * Only called from build/test tools. MCP startup must **not** await this.
+ *
+ * Skipped entirely when `DEXE_PROTOCOL_PATH` points at a user-managed
+ * checkout — we trust the user to keep it in shape.
+ *
+ * Throws with an actionable message if `git` or `npm` are unavailable.
+ */
+export async function ensureBuildReady(protocolPath) {
+    if (isBuildReady(protocolPath))
+        return;
+    if (inflightEnsure)
+        return inflightEnsure;
+    inflightEnsure = (async () => {
         try {
-            runSync("npm install", protocolPath);
+            const explicit = process.env.DEXE_PROTOCOL_PATH?.trim();
+            if (explicit) {
+                // User-managed checkout: don't touch it. Give a clear diagnosis.
+                if (!existsSync(protocolPath)) {
+                    throw new Error(`DEXE_PROTOCOL_PATH points at ${protocolPath}, but that directory does not exist.`);
+                }
+                if (!existsSync(join(protocolPath, "hardhat.config.js")) &&
+                    !existsSync(join(protocolPath, "hardhat.config.ts"))) {
+                    throw new Error(`DEXE_PROTOCOL_PATH=${protocolPath} is not a Hardhat project (no hardhat.config.{js,ts}).`);
+                }
+                if (!existsSync(join(protocolPath, "node_modules"))) {
+                    throw new Error(`DEXE_PROTOCOL_PATH=${protocolPath} is missing node_modules. Run \`npm install\` there once and retry.`);
+                }
+                return;
+            }
+            // Auto-managed cache path: we own it, we can clone + install into it.
+            const cacheDir = getCacheDir();
+            if (!existsSync(cacheDir))
+                mkdirSync(cacheDir, { recursive: true });
+            if (!existsSync(join(protocolPath, ".git"))) {
+                if (!(await hasGit())) {
+                    throw new Error("`git` is not on PATH. Install git (https://git-scm.com/downloads) and retry — dexe-mcp needs it to fetch the DeXe-Protocol sources on first run.");
+                }
+                log(`Cloning DeXe-Protocol (shallow, ~200 MB) into ${protocolPath} …`);
+                log("This only happens once. Subsequent calls will be instant.");
+                try {
+                    await execFileAsync("git", ["clone", "--depth", "1", REPO_URL, CHECKOUT_DIR], { cwd: cacheDir, windowsHide: true });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    throw new Error(`Failed to clone DeXe-Protocol. Check internet access and git credentials.\n${msg}`);
+                }
+                log("Clone complete.");
+            }
+            if (!existsSync(join(protocolPath, "node_modules"))) {
+                log("Installing DeXe-Protocol npm dependencies (first run only) — this takes a few minutes …");
+                const npm = npmCommand();
+                try {
+                    await execFileAsync(npm.command, [...npm.prefixArgs, "install", "--no-audit", "--no-fund"], {
+                        cwd: protocolPath,
+                        windowsHide: true,
+                        maxBuffer: 64 * 1024 * 1024,
+                    });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    throw new Error(`\`npm install\` failed inside ${protocolPath}.\n` +
+                        `If your Node install lacks a bundled npm (e.g. a stripped node.exe), ` +
+                        `install Node from https://nodejs.org or via nvm and retry.\n${msg}`);
+                }
+                log("Dependencies installed.");
+            }
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(`npm install failed in DeXe-Protocol checkout.\n${msg}`);
+        finally {
+            inflightEnsure = null;
         }
-        log("Dependencies installed.");
-    }
-    return protocolPath;
+    })();
+    return inflightEnsure;
 }
 //# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

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

package/dist/config.d.ts

@@ -1,5 +1,5 @@
 export interface DexeConfig {
-    /** Absolute, normalized path to the DeXe-Protocol checkout. */
+    /** Absolute, normalized path to the DeXe-Protocol checkout (may not exist yet). */
     protocolPath: string;
     /** Optional JSON-RPC endpoint for on-chain gov tools. */
     rpcUrl?: string;
@@ -7,13 +7,10 @@ export interface DexeConfig {
     forkBlock?: number;
 }
 /**
- * Validates environment and returns a frozen config.
- *
- * If `DEXE_PROTOCOL_PATH` is set, uses it directly (power-user override).
- * Otherwise, auto-clones DeXe-Protocol into a platform cache directory.
- *
- * Exported primarily for the MCP entrypoint; tests can construct their own
- * config objects directly.
+ * Reads environment and returns a frozen config. **Fast and side-effect-free**
+ * — safe to await during MCP `initialize`. Does not clone, install, or shell
+ * out. The protocol checkout may not exist yet; `ensureBuildReady` handles
+ * that lazily from inside build/test tools.
  */
 export declare function loadConfig(): Promise<DexeConfig>;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CA4BtD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,UAAU;IACzB,mFAAmF;IACnF,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CA4BtD"}

package/dist/config.js

@@ -1,25 +1,22 @@
-import { existsSync, statSync } from "node:fs";
-import { resolve, join } from "node:path";
-import { ensureProtocolCheckout } from "./bootstrap.js";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { resolveProtocolPath, isBuildReady } from "./bootstrap.js";
 /**
- * Validates environment and returns a frozen config.
- *
- * If `DEXE_PROTOCOL_PATH` is set, uses it directly (power-user override).
- * Otherwise, auto-clones DeXe-Protocol into a platform cache directory.
- *
- * Exported primarily for the MCP entrypoint; tests can construct their own
- * config objects directly.
+ * Reads environment and returns a frozen config. **Fast and side-effect-free**
+ * — safe to await during MCP `initialize`. Does not clone, install, or shell
+ * out. The protocol checkout may not exist yet; `ensureBuildReady` handles
+ * that lazily from inside build/test tools.
  */
 export async function loadConfig() {
-    const raw = await ensureProtocolCheckout();
-    const protocolPath = resolve(raw);
-    if (!existsSync(protocolPath) || !statSync(protocolPath).isDirectory()) {
-        fatal(`DeXe-Protocol path does not exist or is not a directory: ${protocolPath}`);
+    const protocolPath = resolve(resolveProtocolPath());
+    // Soft warning only — don't block startup. The lazy bootstrap will either
+    // create the checkout (auto-managed path) or surface a clear error when a
+    // build tool is actually invoked (DEXE_PROTOCOL_PATH override).
+    if (!existsSync(protocolPath)) {
+        process.stderr.write(`[dexe-mcp] DeXe-Protocol checkout not found at ${protocolPath} — will be prepared on first dexe_compile call.\n`);
     }
-    const hardhatConfig = join(protocolPath, "hardhat.config.js");
-    const hardhatConfigTs = join(protocolPath, "hardhat.config.ts");
-    if (!existsSync(hardhatConfig) && !existsSync(hardhatConfigTs)) {
-        fatal(`DeXe-Protocol path is not a Hardhat project — no hardhat.config.{js,ts} found at ${protocolPath}`);
+    else if (!isBuildReady(protocolPath)) {
+        process.stderr.write(`[dexe-mcp] DeXe-Protocol checkout at ${protocolPath} is incomplete (missing node_modules or hardhat.config) — will be prepared on first dexe_compile call.\n`);
     }
     const rpcUrl = process.env.DEXE_RPC_URL?.trim() || undefined;
     let forkBlock;

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAWxD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,GAAG,GAAG,MAAM,sBAAsB,EAAE,CAAC;IAC3C,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAElC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACvE,KAAK,CAAC,4DAA4D,YAAY,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;IAC9D,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,CAAC;IAChE,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QAC/D,KAAK,CACH,oFAAoF,YAAY,EAAE,CACnG,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAE7D,IAAI,SAA6B,CAAC;IAClC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,KAAK,CAAC,wDAAwD,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC;QAC/F,CAAC;QACD,SAAS,GAAG,CAAC,CAAC;IAChB,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,KAAK,CAAC,GAAW;IACxB,oDAAoD;IACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAWnE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,YAAY,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAEpD,0EAA0E;IAC1E,0EAA0E;IAC1E,gEAAgE;IAChE,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kDAAkD,YAAY,mDAAmD,CAClH,CAAC;IACJ,CAAC;SAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,CAAC;QACvC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wCAAwC,YAAY,0GAA0G,CAC/J,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAE7D,IAAI,SAA6B,CAAC;IAClC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACjC,KAAK,CAAC,wDAAwD,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC;QAC/F,CAAC;QACD,SAAS,GAAG,CAAC,CAAC;IAChB,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,KAAK,CAAC,GAAW;IACxB,oDAAoD;IACpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/hardhat.d.ts

@@ -17,9 +17,19 @@ export interface RunResult {
 export declare class HardhatRunner {
     private readonly config;
     constructor(config: DexeConfig);
-    /** Run `npm run <script>` in the protocol directory. */
+    /**
+     * Run `npm run <script>` in the protocol directory.
+     *
+     * Uses `node <npm-cli.js>` under the hood so this works regardless of
+     * whether `npm` is on the MCP's spawn PATH.
+     */
     runNpmScript(script: string, extraArgs?: string[]): Promise<RunResult>;
-    /** Run `npx hardhat <subcommand> <args...>` in the protocol directory. */
+    /**
+     * Run `hardhat <subcommand> <args...>` in the protocol directory.
+     *
+     * Uses `node <protocol>/node_modules/hardhat/internal/cli/cli.js` so this
+     * doesn't require `npx` on PATH.
+     */
     runHardhat(subcommand: string, args?: string[]): Promise<RunResult>;
     private run;
 }

package/dist/hardhat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hardhat.d.ts","sourceRoot":"","sources":["../src/hardhat.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,sDAAsD;AACtD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAiBD,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAE/C,wDAAwD;IACxD,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAQ1E,0EAA0E;IAC1E,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAIvE,OAAO,CAAC,GAAG;CAuDZ"}
+{"version":3,"file":"hardhat.d.ts","sourceRoot":"","sources":["../src/hardhat.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C,sDAAsD;AACtD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAiBD,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,UAAU;IAE/C;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAQhF;;;;;OAKG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,SAAS,CAAC;IAW7E,OAAO,CAAC,GAAG;CAuDZ"}

package/dist/hardhat.js

@@ -3,6 +3,8 @@ import pLimit from "p-limit";
 import { writeFileSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { ensureBuildReady } from "./bootstrap.js";
+import { hardhatCommand, npmCommand } from "./runtime.js";
 const HARDHAT_TIMEOUT_MS = 10 * 60 * 1000;
 const STDOUT_TAIL_LINES = 200;
 const STDERR_TAIL_LINES = 100;
@@ -21,17 +23,33 @@ export class HardhatRunner {
     constructor(config) {
         this.config = config;
     }
-    /** Run `npm run <script>` in the protocol directory. */
-    runNpmScript(script, extraArgs = []) {
-        const args = ["run", script];
-        if (extraArgs.length > 0) {
+    /**
+     * Run `npm run <script>` in the protocol directory.
+     *
+     * Uses `node <npm-cli.js>` under the hood so this works regardless of
+     * whether `npm` is on the MCP's spawn PATH.
+     */
+    async runNpmScript(script, extraArgs = []) {
+        await ensureBuildReady(this.config.protocolPath);
+        const npm = npmCommand();
+        const args = [...npm.prefixArgs, "run", script];
+        if (extraArgs.length > 0)
             args.push("--", ...extraArgs);
-        }
-        return this.run("npm", args, `npm-run-${script}`);
+        return this.run(npm.command, args, `npm-run-${script}`);
     }
-    /** Run `npx hardhat <subcommand> <args...>` in the protocol directory. */
-    runHardhat(subcommand, args = []) {
-        return this.run("npx", ["hardhat", subcommand, ...args], `hardhat-${subcommand}`);
+    /**
+     * Run `hardhat <subcommand> <args...>` in the protocol directory.
+     *
+     * Uses `node <protocol>/node_modules/hardhat/internal/cli/cli.js` so this
+     * doesn't require `npx` on PATH.
+     */
+    async runHardhat(subcommand, args = []) {
+        await ensureBuildReady(this.config.protocolPath);
+        const hh = hardhatCommand(this.config.protocolPath);
+        if (!hh) {
+            throw new Error(`Hardhat is not installed inside ${this.config.protocolPath}. This should have been fixed by ensureBuildReady — did npm install fail?`);
+        }
+        return this.run(hh.command, [...hh.prefixArgs, subcommand, ...args], `hardhat-${subcommand}`);
     }
     run(command, args, label) {
         return limit(async () => {

package/dist/hardhat.js.map

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

package/dist/index.js

@@ -5,7 +5,7 @@ import { loadConfig } from "./config.js";
 import { registerAll } from "./tools/index.js";
 async function main() {
     const config = await loadConfig();
-    const server = new McpServer({ name: "dexe-mcp", version: "0.1.1" }, {
+    const server = new McpServer({ name: "dexe-mcp", version: "0.1.2" }, {
         instructions: "Tools for the DeXe Protocol governance-DAO codebase. Before calling any dexe_get_* / dexe_list_contracts / dexe_find_selector tool, ensure artifacts exist by calling dexe_compile once per session. dexe_decode_proposal and dexe_read_gov_state require DEXE_RPC_URL to be set.",
     });
     registerAll(server, config);

package/dist/runtime.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Portable runtime helpers for spawning `npm`, `npx`, `hardhat`, and `git`
+ * without depending on the MCP process's PATH.
+ *
+ * Claude Code (and other MCP clients) spawn servers with a minimal PATH.
+ * On Windows in particular, `npm`/`npx` are `.cmd` shims that `CreateProcess`
+ * won't find unless they're on that PATH. We side-step the whole problem by
+ * invoking JS entry points (`npm-cli.js`, `hardhat/internal/cli/cli.js`)
+ * directly through `process.execPath`.
+ */
+/**
+ * Locate the `npm-cli.js` that ships with the currently-running Node.
+ *
+ * Layouts we handle:
+ *  - Windows (official installer / nvm-windows):
+ *      <execDir>\node_modules\npm\bin\npm-cli.js
+ *  - Unix (nvm, homebrew, official installer):
+ *      <execDir>/../lib/node_modules/npm/bin/npm-cli.js
+ *
+ * Returns `null` if nothing is found — caller should fall back to `npm` on PATH.
+ */
+export declare function resolveNpmCli(): string | null;
+/**
+ * Locate Hardhat's CLI entry point inside a protocol checkout.
+ * Returns `null` if `node_modules` isn't installed yet.
+ */
+export declare function resolveHardhatCli(protocolPath: string): string | null;
+export declare function hasGit(): Promise<boolean>;
+/**
+ * Describe the PATH-independent command we'd use to run `npm` / `npx`.
+ * Returns the `[command, prefixArgs]` tuple so callers can append script args.
+ *
+ * If `npm-cli.js` is found, we return `(process.execPath, [cliPath])`.
+ * Otherwise we fall back to `("npm", [])` which requires PATH — and may fail
+ * on machines where npm isn't on the spawn PATH, but that's strictly better
+ * than crashing at startup.
+ */
+export declare function npmCommand(): {
+    command: string;
+    prefixArgs: string[];
+};
+/**
+ * Describe the command we'd use to run Hardhat against a given protocol path.
+ *
+ * Prefers `node <protocolPath>/node_modules/hardhat/internal/cli/cli.js` which
+ * has zero PATH dependency. Falls back to `npx hardhat` (requires PATH).
+ *
+ * Returns `null` if the protocol's `node_modules` isn't installed — caller
+ * should trigger `ensureBuildReady` first.
+ */
+export declare function hardhatCommand(protocolPath: string): {
+    command: string;
+    prefixArgs: string[];
+} | null;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAKA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAa7C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrE;AAID,wBAAgB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAQzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAItE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,GACnB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAIlD"}

package/dist/runtime.js

@@ -0,0 +1,90 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { platform } from "node:os";
+import { execFile } from "node:child_process";
+/**
+ * Portable runtime helpers for spawning `npm`, `npx`, `hardhat`, and `git`
+ * without depending on the MCP process's PATH.
+ *
+ * Claude Code (and other MCP clients) spawn servers with a minimal PATH.
+ * On Windows in particular, `npm`/`npx` are `.cmd` shims that `CreateProcess`
+ * won't find unless they're on that PATH. We side-step the whole problem by
+ * invoking JS entry points (`npm-cli.js`, `hardhat/internal/cli/cli.js`)
+ * directly through `process.execPath`.
+ */
+/**
+ * Locate the `npm-cli.js` that ships with the currently-running Node.
+ *
+ * Layouts we handle:
+ *  - Windows (official installer / nvm-windows):
+ *      <execDir>\node_modules\npm\bin\npm-cli.js
+ *  - Unix (nvm, homebrew, official installer):
+ *      <execDir>/../lib/node_modules/npm/bin/npm-cli.js
+ *
+ * Returns `null` if nothing is found — caller should fall back to `npm` on PATH.
+ */
+export function resolveNpmCli() {
+    const execDir = dirname(process.execPath);
+    const candidates = platform() === "win32"
+        ? [join(execDir, "node_modules", "npm", "bin", "npm-cli.js")]
+        : [
+            join(execDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+            join(execDir, "..", "libexec", "lib", "node_modules", "npm", "bin", "npm-cli.js"),
+        ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+/**
+ * Locate Hardhat's CLI entry point inside a protocol checkout.
+ * Returns `null` if `node_modules` isn't installed yet.
+ */
+export function resolveHardhatCli(protocolPath) {
+    const p = join(protocolPath, "node_modules", "hardhat", "internal", "cli", "cli.js");
+    return existsSync(p) ? p : null;
+}
+/** Detect whether `git` is available on PATH. Cached per-process. */
+let gitAvailable = null;
+export function hasGit() {
+    if (gitAvailable !== null)
+        return Promise.resolve(gitAvailable);
+    return new Promise((resolvePromise) => {
+        execFile("git", ["--version"], { windowsHide: true }, (err) => {
+            gitAvailable = !err;
+            resolvePromise(gitAvailable);
+        });
+    });
+}
+/**
+ * Describe the PATH-independent command we'd use to run `npm` / `npx`.
+ * Returns the `[command, prefixArgs]` tuple so callers can append script args.
+ *
+ * If `npm-cli.js` is found, we return `(process.execPath, [cliPath])`.
+ * Otherwise we fall back to `("npm", [])` which requires PATH — and may fail
+ * on machines where npm isn't on the spawn PATH, but that's strictly better
+ * than crashing at startup.
+ */
+export function npmCommand() {
+    const cli = resolveNpmCli();
+    if (cli)
+        return { command: process.execPath, prefixArgs: [cli] };
+    return { command: platform() === "win32" ? "npm.cmd" : "npm", prefixArgs: [] };
+}
+/**
+ * Describe the command we'd use to run Hardhat against a given protocol path.
+ *
+ * Prefers `node <protocolPath>/node_modules/hardhat/internal/cli/cli.js` which
+ * has zero PATH dependency. Falls back to `npx hardhat` (requires PATH).
+ *
+ * Returns `null` if the protocol's `node_modules` isn't installed — caller
+ * should trigger `ensureBuildReady` first.
+ */
+export function hardhatCommand(protocolPath) {
+    const cli = resolveHardhatCli(protocolPath);
+    if (cli)
+        return { command: process.execPath, prefixArgs: [cli] };
+    return null;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,UAAU,GACd,QAAQ,EAAE,KAAK,OAAO;QACpB,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;QAC7D,CAAC,CAAC;YACE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC;YACtE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,CAAC;SAClF,CAAC;IACR,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,UAAU,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAoB;IACpD,MAAM,CAAC,GAAG,IAAI,CAAC,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrF,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAClC,CAAC;AAED,qEAAqE;AACrE,IAAI,YAAY,GAAmB,IAAI,CAAC;AACxC,MAAM,UAAU,MAAM;IACpB,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAChE,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,EAAE;QACpC,QAAQ,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,EAAE,EAAE;YAC5D,YAAY,GAAG,CAAC,GAAG,CAAC;YACpB,cAAc,CAAC,YAAY,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;IAC5B,IAAI,GAAG;QAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IACjE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;AACjF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,YAAoB;IAEpB,MAAM,GAAG,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAC5C,IAAI,GAAG;QAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IACjE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dexe-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "MCP server wrapping DeXe Protocol for Claude Code dev tooling (build/test, contract introspection, governance-domain tools)",
   "type": "module",
   "license": "MIT",