dexe-mcp 0.1.0

package/.mcp.example.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "dexe": {
+      "command": "npx",
+      "args": ["-y", "dexe-mcp"]
+    }
+  }
+}

package/FUTURE.md

@@ -0,0 +1,37 @@
+# Future work
+
+Tracking features deliberately deferred out of the Phase A / B roadmap.
+
+## `dexe_get_storage_layout` (dropped from v1)
+
+The current `DeXe-Protocol/hardhat.config.js` does not include `storageLayout` in `outputSelection`, so build-info files don't contain the data this tool would read.
+
+**To enable:** add `storageLayout` to `outputSelection` in DeXe-Protocol's hardhat config:
+
+```js
+solidity: {
+  compilers: [{
+    version: "0.8.20",
+    settings: {
+      outputSelection: {
+        "*": {
+          "*": ["storageLayout", /* ...existing */]
+        }
+      }
+    }
+  }]
+}
+```
+
+Then the tool becomes a short handler reading `output.contracts[file][name].storageLayout` from the matching build-info JSON.
+
+## `dexe_simulate_vote` (Phase B)
+
+Needs a managed `hardhat node --fork $DEXE_RPC_URL` child process owned by the MCP. See `src/fork.ts` (not yet created) per the execution plan at `C:\Users\edwar\.claude\plans\kind-rolling-pelican.md`.
+
+## Other ideas surfaced during design
+
+- **TypeChain integration** — the protocol already emits ethers-v5 TypeChain bindings. We intentionally parse ABI JSON directly (dexe-mcp uses ethers v6). Revisit if/when DeXe-Protocol moves to ethers v6.
+- **Custom `hardhat-migrate` wrappers** — out of scope per user decision (deployment tooling excluded).
+- **Gas reporter parsing** — the `hardhat-gas-reporter` plugin is already wired in the protocol; `dexe_test` could optionally parse its output for per-function gas numbers.
+- **Foundry fallback** — the repo is pure Hardhat today. Skip unless a Foundry config is added upstream.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edward Arinin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PLAN.md

@@ -0,0 +1,132 @@
+# Plan: `dexe-mcp` — MCP Server for DeXe Protocol Dev Tooling
+
+## Context
+
+DeXe Protocol (`D:\dev\DeXe-Protocol`) is a governance DAO protocol: 129 Solidity contracts (OpenZeppelin v4.9.2, Solidity 0.8.20, Hardhat 2.20.1), organized around `GovPool`, `GovSettings`, `GovUserKeeper`, `GovValidators`, proposal contracts (`DistributionProposal`, `StakingProposal`, `TokenSaleProposal`), voting-power libs (`LinearPower`, `PolynomialPower`), and a `ContractsRegistry` service locator.
+
+Day-to-day dev work on this repo currently means jumping between `npm run compile`, `hardhat test --grep`, reading TypeChain output, and hand-decoding proposal calldata against ABIs. We want an MCP server Claude Code can drive directly so an agent can compile, introspect contracts, and answer governance-domain questions (decode a proposal, read on-chain gov state, simulate a vote on a fork) without the human babysitting each shell command.
+
+**Decisions already made (from user):**
+- TypeScript / Node, `@modelcontextprotocol/sdk` v1.x, stdio transport
+- Separate repo (`dexe-mcp`) — not nested inside DeXe-Protocol
+- Scope: **build/test**, **contract introspection**, **governance domain**. Explicitly **out of scope**: deployment/migration tooling
+- Consumer: Claude Code (stdio)
+
+The server points at a DeXe-Protocol checkout via `DEXE_PROTOCOL_PATH`; it reads Hardhat artifacts off disk and shells out to `npm run <script>` in that directory. On-chain / fork interactions go through an injected RPC URL.
+
+## Repository Layout
+
+```
+dexe-mcp/
+├── package.json              # "bin": { "dexe-mcp": "dist/index.js" }
+├── tsconfig.json
+├── README.md                 # how to wire into Claude Code .mcp.json
+├── .mcp.example.json         # copy-paste snippet for users
+├── src/
+│   ├── index.ts              # McpServer + StdioServerTransport entrypoint
+│   ├── config.ts             # env: DEXE_PROTOCOL_PATH, RPC_URL, FORK_BLOCK
+│   ├── artifacts.ts          # load hardhat artifacts + build-info + storage layout
+│   ├── hardhat.ts            # spawn `npm run …` in DEXE_PROTOCOL_PATH, stream + cap output
+│   ├── rpc.ts                # ethers v6 Provider factory
+│   ├── fork.ts               # on-demand `hardhat node --fork` child process mgmt
+│   ├── lib/
+│   │   ├── selectors.ts      # 4byte index built from all compiled ABIs
+│   │   ├── decoders.ts       # proposal-executor decoders (Distribution/Staking/TokenSale)
+│   │   └── govAddresses.ts   # resolve GovPool ecosystem via ContractsRegistry
+│   └── tools/
+│       ├── index.ts          # registerAll(server)
+│       ├── build.ts          # compile / test / coverage / lint
+│       ├── introspect.ts     # abi / selectors / storage / natspec / source
+│       └── gov.ts            # decode_calldata / decode_proposal / read_gov_state / simulate_vote
+└── test/
+    └── tools.test.ts         # vitest; uses a tiny fixture hardhat project
+```
+
+## Dependencies
+
+- `@modelcontextprotocol/sdk` (v1.x) — `McpServer`, `StdioServerTransport`, `registerTool`
+- `zod` — input/output schemas (Standard Schema, per current MCP SDK docs)
+- `ethers` v6 — ABI parsing, `Interface.parseTransaction`, providers, impersonation
+- `execa` — child_process wrapper for hardhat shell-outs (timeout + stdout capping)
+- `p-limit` — guard concurrent hardhat invocations
+- Dev: `typescript`, `tsx`, `vitest`, `@types/node`
+
+## Tool Catalog
+
+All tools use `registerTool(name, {title, description, inputSchema, outputSchema}, handler)` with Zod schemas and return both `content` (text) and `structuredContent` (machine-readable).
+
+### Build / test (wraps `npm run …` in `DEXE_PROTOCOL_PATH`)
+
+| Tool | Input | Behavior |
+|---|---|---|
+| `dexe_compile` | `{ force?: boolean }` | Runs `npm run compile`. Parses solc errors/warnings; returns counts + first N diagnostics with file/line. |
+| `dexe_test` | `{ grep?: string, file?: string, bail?: boolean }` | Runs `npx hardhat test` (with `--grep` / file arg). Parses mocha output; returns pass/fail counts and up to 20 failures with stack traces. |
+| `dexe_coverage` | `{ grep?: string }` | Runs `npm run coverage`. Returns per-contract line/branch % summary parsed from `coverage/coverage-summary.json`. |
+| `dexe_lint` | `{ fix?: boolean }` | Runs `npm run lint-fix` (or dry-run). Returns changed-file list. |
+
+All build/test tools cap stdout at ~200 lines and write full logs to a tmp file, surfacing the path in `structuredContent.logFile`.
+
+### Contract introspection (reads artifacts, no network)
+
+`artifacts.ts` loads `${DEXE_PROTOCOL_PATH}/artifacts/contracts/**/*.json` and the matching `build-info/*.json` for storage layout + metadata.
+
+| Tool | Input | Behavior |
+|---|---|---|
+| `dexe_list_contracts` | `{ filter?: string, kind?: "contract"\|"interface"\|"library" }` | Enumerates compiled contracts, returning `{name, path, kind}`. |
+| `dexe_get_abi` | `{ contract: string }` | Returns ABI JSON for named contract. |
+| `dexe_get_selectors` | `{ contract: string }` | Returns list of `{signature, selector, type: "function"\|"event"\|"error"}` using `ethers.Interface.getFunction().selector`. |
+| `dexe_find_selector` | `{ selector: "0xXXXXXXXX" }` | Reverse-lookup against the prebuilt index in `lib/selectors.ts`; returns all matching signatures + contracts. |
+| `dexe_get_storage_layout` | `{ contract: string }` | Extracts storage layout from build-info `output.contracts[file][name].storageLayout`. |
+| `dexe_get_natspec` | `{ contract: string, member?: string }` | Returns `devdoc`/`userdoc` from artifact metadata, optionally scoped to one function. |
+| `dexe_get_source` | `{ contract: string, symbol?: string }` | Returns source path; if `symbol`, returns a slice around its definition using AST from build-info. |
+
+### Governance domain (the reason this MCP exists)
+
+| Tool | Input | Behavior |
+|---|---|---|
+| `dexe_decode_calldata` | `{ data: "0x...", contract?: string }` | Tries to decode calldata. Without `contract`, iterates all loaded ABIs by selector match. Returns decoded function + args (recursively decoding nested proposal executor calldata for `GovPool.createProposal` / `execute`). |
+| `dexe_decode_proposal` | `{ govPool: address, proposalId: number }` | Calls `GovPool.getProposals` via RPC, decodes every action's `data` against the matching executor (`DistributionProposal`, `TokenSaleProposal`, `StakingProposal`, or generic) using `lib/decoders.ts`. |
+| `dexe_read_gov_state` | `{ govPool: address, fields?: string[] }` | Aggregate read: `GovSettings` params, `GovUserKeeper` totals, `GovValidators` set, active proposal count. Resolved via `ContractsRegistry` (`lib/govAddresses.ts`). |
+| `dexe_simulate_vote` | `{ govPool: address, proposalId: number, voter: address, voteAmount: string, support: boolean }` | Starts/reuses a `hardhat node --fork $RPC_URL` child (managed by `fork.ts`), impersonates `voter`, calls `GovPool.vote`, returns the new proposal state + gas used. Fork is torn down on server shutdown. |
+| `dexe_list_gov_contract_types` | `{}` | Static catalog: names, roles, ABI pointers for the governance subsystem. Cheap orientation tool for agents new to the repo. |
+
+## Key Implementation Notes
+
+- **Single source of truth for artifacts.** `artifacts.ts` memoizes a `Map<contractName, {abi, bytecode, buildInfoPath}>` built once per `DEXE_PROTOCOL_PATH` mtime. Invalidated after `dexe_compile` completes.
+- **Selector index.** Built lazily on first introspection call by walking the artifact map and calling `new ethers.Interface(abi)` on each. Stored as `Map<selector, Array<{contract, signature}>>` — supports collisions.
+- **Proposal decoding is the crown jewel.** `lib/decoders.ts` must handle `GovPool`'s `ProposalAction[]` shape (`executor`, `value`, `data`), dispatching by `executor` address class to the proposal-specific ABIs. Fall back to generic ABI decode when executor is unknown. Unit-test this against real calldata captured from mainnet proposals.
+- **Fork lifecycle.** `fork.ts` owns at most one `hardhat node` child process. Tools that need fork state (`simulate_vote`) start it lazily; `server.onclose` kills it. No persistent state between tool calls beyond the running fork.
+- **Shell-out safety.** All child_process calls use `execa` with `cwd: DEXE_PROTOCOL_PATH`, fixed arg arrays (no shell interpolation), 10-minute timeout, and `maxBuffer` protection.
+- **Config.** `config.ts` reads `DEXE_PROTOCOL_PATH` (required), `DEXE_RPC_URL` (optional; needed for gov state / simulate), `DEXE_FORK_BLOCK` (optional). Fails fast on startup with a clear error if `DEXE_PROTOCOL_PATH` is missing or not a Hardhat project (no `hardhat.config.js`).
+- **Logging.** Per MCP convention, **all logs to stderr** (stdout is the protocol channel). Use `console.error` or a thin `pino` stderr stream.
+
+## Verification
+
+1. **Unit tests** (`vitest`): each tool handler tested against a tiny fixture Hardhat project committed under `test/fixtures/`. Covers ABI loading, selector index, calldata decoding (including nested proposal executors), stdout parsing for compile/test.
+2. **Smoke against the real repo.** With `DEXE_PROTOCOL_PATH=D:\dev\DeXe-Protocol` set, run the server under the official MCP Inspector: `npx @modelcontextprotocol/inspector node dist/index.js`. Manually exercise:
+   - `dexe_compile` → expect clean build
+   - `dexe_test { grep: "GovPool" }` → expect real pass/fail summary
+   - `dexe_list_contracts { filter: "Gov" }` → expect `GovPool`, `GovSettings`, etc.
+   - `dexe_get_abi { contract: "GovPool" }`
+   - `dexe_find_selector { selector: "<known GovPool selector>" }`
+   - `dexe_decode_calldata` against a captured real-world proposal createProposal calldata
+3. **End-to-end in Claude Code.** Add to `.mcp.json`:
+   ```json
+   {
+     "mcpServers": {
+       "dexe": {
+         "command": "node",
+         "args": ["D:/dev/dexe-mcp/dist/index.js"],
+         "env": { "DEXE_PROTOCOL_PATH": "D:/dev/DeXe-Protocol" }
+       }
+     }
+   }
+   ```
+   Restart Claude Code, confirm tools appear, ask it "compile the protocol and summarize any warnings" and "decode proposal 42 on GovPool 0x…".
+4. **Fork simulation test** (optional, needs RPC): set `DEXE_RPC_URL` to an Ethereum archive node, run `dexe_simulate_vote` against a real active proposal, verify no orphaned `hardhat node` processes after server shutdown.
+
+## Out of Scope (explicit, per user)
+
+- Deployment / migration tooling (`hardhat-migrate` wrappers, network configs under `deploy/config/configs/`, verification) — deliberately excluded.
+- TypeChain codegen orchestration, Go bindings, markup doc generation.
+- Remote / HTTP transport, auth, multi-tenant hosting.

package/README.md

@@ -0,0 +1,126 @@
+# dexe-mcp
+
+![npm](https://img.shields.io/npm/v/dexe-mcp.svg)
+
+MCP server for Claude Code / Antigravity that wraps the [DeXe Protocol](https://github.com/dexe-network/DeXe-Protocol) Hardhat codebase with build/test, contract introspection, and governance-domain tools.
+
+## Prerequisites
+
+- **Node.js >= 20**
+- **Git** (the server auto-clones DeXe-Protocol on first run)
+
+## Quick start
+
+Add this to your project's `.mcp.json` (or your MCP client config):
+
+```json
+{
+  "mcpServers": {
+    "dexe": {
+      "command": "npx",
+      "args": ["-y", "dexe-mcp"]
+    }
+  }
+}
+```
+
+Restart your MCP client. On first launch, `dexe-mcp` will automatically:
+
+1. Clone `dexe-network/DeXe-Protocol` to a local cache directory (~200 MB, shallow clone)
+2. Run `npm install` in the checkout
+
+Subsequent launches are instant. No manual setup needed.
+
+### Advanced: custom checkout path
+
+If you already have a DeXe-Protocol checkout or want to control its location:
+
+```json
+{
+  "mcpServers": {
+    "dexe": {
+      "command": "npx",
+      "args": ["-y", "dexe-mcp"],
+      "env": {
+        "DEXE_PROTOCOL_PATH": "/absolute/path/to/your/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.
+
+## Tool catalog
+
+### Build / test
+
+| Tool | Description |
+|------|-------------|
+| `dexe_compile` | Compile all contracts via Hardhat |
+| `dexe_test` | Run the test suite (optional grep filter) |
+| `dexe_coverage` | Run tests with solidity-coverage |
+| `dexe_lint` | Lint Solidity sources with solhint |
+
+### Contract introspection
+
+| Tool | Description |
+|------|-------------|
+| `dexe_list_contracts` | List all compiled contracts (filter by name/kind) |
+| `dexe_get_abi` | Get the full ABI for a contract |
+| `dexe_get_selectors` | List function selectors for a contract |
+| `dexe_find_selector` | Reverse-lookup: selector hex to function signature |
+| `dexe_get_natspec` | Read NatSpec documentation for a contract |
+| `dexe_get_source` | Read Solidity source code for a contract |
+
+### Governance domain
+
+| Tool | Description |
+|------|-------------|
+| `dexe_decode_calldata` | Decode arbitrary calldata against contract ABI |
+| `dexe_decode_proposal` | Fetch and decode a full on-chain proposal |
+| `dexe_read_gov_state` | Read governance pool state from chain |
+| `dexe_list_gov_contract_types` | List known governance contract type names |
+
+## Environment variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `DEXE_PROTOCOL_PATH` | no | Override the auto-managed DeXe-Protocol checkout path |
+| `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
+
+### "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"
+
+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`.
+
+### "DEXE_RPC_URL is not set"
+
+The governance tools `dexe_decode_proposal` and `dexe_read_gov_state` require an Ethereum JSON-RPC endpoint. Add `DEXE_RPC_URL` to your MCP env config.
+
+## Contributing
+
+```bash
+git clone https://github.com/edward-arinin-web-dev/dexe-mcp.git
+cd dexe-mcp
+npm install
+npm run build
+npm run typecheck
+npm run dev          # watch mode
+```
+
+## Roadmap
+
+Phase B (`dexe_simulate_vote` + Hardhat fork management) is planned for v0.2.0. See [FUTURE.md](./FUTURE.md) for all deferred features.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/artifacts.d.ts

@@ -0,0 +1,69 @@
+import type { DexeConfig } from "./config.js";
+/**
+ * Minimal artifact record loaded from a Hardhat artifact JSON.
+ *
+ * We intentionally don't pull the full Hardhat Artifact type off the bundle —
+ * keeps the dependency footprint small and works across Hardhat versions.
+ */
+export interface ArtifactRecord {
+    contractName: string;
+    sourceName: string;
+    abi: readonly unknown[];
+    bytecode: string;
+    deployedBytecode: string;
+    /** Absolute path to the artifact JSON on disk. */
+    artifactPath: string;
+    /** Inferred kind. "library" detection is best-effort; interfaces are reliable (bytecode === "0x"). */
+    kind: "contract" | "interface" | "library";
+}
+/** Structured error thrown when introspection tools run before `dexe_compile`. */
+export declare class ArtifactsMissingError extends Error {
+    readonly artifactsDir: string;
+    constructor(artifactsDir: string);
+}
+export declare class Artifacts {
+    private readonly config;
+    private cache;
+    constructor(config: DexeConfig);
+    /** Directory holding contract artifacts (not build-info). */
+    get contractsDir(): string;
+    /** Directory holding build-info JSON (used for natspec + AST). */
+    get buildInfoDir(): string;
+    /**
+     * Throws `ArtifactsMissingError` if `artifacts/contracts/` does not exist.
+     * Introspection tools call this before touching the cache.
+     */
+    requireArtifactsExist(): void;
+    /** Discard the in-memory index — called after `dexe_compile` succeeds. */
+    invalidate(): void;
+    /** Load (and memoize) all contract artifacts on disk. */
+    private load;
+    /** Enumerate all loaded artifacts, with optional filters. */
+    list(opts?: {
+        filter?: string;
+        kind?: ArtifactRecord["kind"];
+    }): ArtifactRecord[];
+    /**
+     * Look up an artifact by contract name. Returns the first match; if there
+     * are collisions (same contract name under different source paths), returns
+     * all of them so callers can disambiguate.
+     */
+    get(contractName: string): ArtifactRecord[];
+    /** Convenience: get exactly one artifact or throw. */
+    getOne(contractName: string): ArtifactRecord;
+    private readonly buildInfoCache;
+    /**
+     * Load the build-info file that holds the compiler output for a given
+     * artifact. Hardhat writes one build-info per compile per solc invocation;
+     * the artifact's `.dbg.json` points at the right one.
+     */
+    loadBuildInfoFor(record: ArtifactRecord): BuildInfoContract | null;
+    private loadBuildInfoFile;
+}
+export interface BuildInfoContract {
+    abi?: unknown[];
+    metadata?: string;
+    devdoc?: unknown;
+    userdoc?: unknown;
+}
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,SAAS,OAAO,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,sGAAsG;IACtG,IAAI,EAAE,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;CAC5C;AAED,kFAAkF;AAClF,qBAAa,qBAAsB,SAAQ,KAAK;aAClB,YAAY,EAAE,MAAM;gBAApB,YAAY,EAAE,MAAM;CAMjD;AAQD,qBAAa,SAAS;IAGR,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,KAAK,CAA4B;gBAEZ,MAAM,EAAE,UAAU;IAE/C,6DAA6D;IAC7D,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,kEAAkE;IAClE,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;OAGG;IACH,qBAAqB,IAAI,IAAI;IAM7B,0EAA0E;IAC1E,UAAU,IAAI,IAAI;IAKlB,yDAAyD;IACzD,OAAO,CAAC,IAAI;IAmDZ,6DAA6D;IAC7D,IAAI,CAAC,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;KAAO,GAAG,cAAc,EAAE;IAUrF;;;;OAIG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,EAAE;IAI3C,sDAAsD;IACtD,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc;IAmB5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoC;IAEnE;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,iBAAiB,GAAG,IAAI;IAiBlE,OAAO,CAAC,iBAAiB;CAmB1B;AAWD,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/artifacts.js

@@ -0,0 +1,181 @@
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join, sep, posix } from "node:path";
+/** Structured error thrown when introspection tools run before `dexe_compile`. */
+export class ArtifactsMissingError extends Error {
+    artifactsDir;
+    constructor(artifactsDir) {
+        super(`Hardhat artifacts not found at ${artifactsDir}. Run dexe_compile first to populate them.`);
+        this.artifactsDir = artifactsDir;
+        this.name = "ArtifactsMissingError";
+    }
+}
+export class Artifacts {
+    config;
+    cache = null;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Directory holding contract artifacts (not build-info). */
+    get contractsDir() {
+        return join(this.config.protocolPath, "artifacts", "contracts");
+    }
+    /** Directory holding build-info JSON (used for natspec + AST). */
+    get buildInfoDir() {
+        return join(this.config.protocolPath, "artifacts", "build-info");
+    }
+    /**
+     * Throws `ArtifactsMissingError` if `artifacts/contracts/` does not exist.
+     * Introspection tools call this before touching the cache.
+     */
+    requireArtifactsExist() {
+        if (!existsSync(this.contractsDir)) {
+            throw new ArtifactsMissingError(this.contractsDir);
+        }
+    }
+    /** Discard the in-memory index — called after `dexe_compile` succeeds. */
+    invalidate() {
+        this.cache = null;
+        this.buildInfoCache.clear();
+    }
+    /** Load (and memoize) all contract artifacts on disk. */
+    load() {
+        this.requireArtifactsExist();
+        const st = statSync(this.contractsDir);
+        if (this.cache && this.cache.mtimeMs === st.mtimeMs) {
+            return this.cache;
+        }
+        const all = [];
+        const byName = new Map();
+        for (const file of walk(this.contractsDir)) {
+            if (!file.endsWith(".json"))
+                continue;
+            if (file.endsWith(".dbg.json"))
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(file, "utf8"));
+            }
+            catch {
+                continue; // skip malformed JSON
+            }
+            if (!parsed.contractName || !parsed.sourceName || !Array.isArray(parsed.abi))
+                continue;
+            const bytecode = parsed.bytecode ?? "0x";
+            const record = {
+                contractName: parsed.contractName,
+                sourceName: parsed.sourceName,
+                abi: parsed.abi,
+                bytecode,
+                deployedBytecode: parsed.deployedBytecode ?? "0x",
+                artifactPath: file,
+                kind: inferKind(parsed.sourceName, bytecode),
+            };
+            all.push(record);
+            const list = byName.get(record.contractName);
+            if (list)
+                list.push(record);
+            else
+                byName.set(record.contractName, [record]);
+        }
+        this.cache = { mtimeMs: st.mtimeMs, all, byContractName: byName };
+        return this.cache;
+    }
+    /** Enumerate all loaded artifacts, with optional filters. */
+    list(opts = {}) {
+        const { all } = this.load();
+        const f = opts.filter?.toLowerCase();
+        return all.filter((r) => {
+            if (opts.kind && r.kind !== opts.kind)
+                return false;
+            if (f && !r.contractName.toLowerCase().includes(f))
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Look up an artifact by contract name. Returns the first match; if there
+     * are collisions (same contract name under different source paths), returns
+     * all of them so callers can disambiguate.
+     */
+    get(contractName) {
+        return this.load().byContractName.get(contractName) ?? [];
+    }
+    /** Convenience: get exactly one artifact or throw. */
+    getOne(contractName) {
+        const list = this.get(contractName);
+        if (list.length === 0) {
+            throw new Error(`Unknown contract: ${contractName}. Call dexe_list_contracts to see what's available.`);
+        }
+        if (list.length > 1) {
+            const paths = list.map((r) => r.sourceName).join(", ");
+            throw new Error(`Ambiguous contract name: ${contractName} exists in multiple sources (${paths}). ` +
+                `Pass a fully-qualified name like "${list[0].sourceName}:${contractName}" (not yet supported — open an issue).`);
+        }
+        return list[0];
+    }
+    // ---------- build-info ----------
+    buildInfoCache = new Map();
+    /**
+     * Load the build-info file that holds the compiler output for a given
+     * artifact. Hardhat writes one build-info per compile per solc invocation;
+     * the artifact's `.dbg.json` points at the right one.
+     */
+    loadBuildInfoFor(record) {
+        const dbgPath = record.artifactPath.replace(/\.json$/, ".dbg.json");
+        if (!existsSync(dbgPath))
+            return null;
+        let dbg;
+        try {
+            dbg = JSON.parse(readFileSync(dbgPath, "utf8"));
+        }
+        catch {
+            return null;
+        }
+        if (!dbg.buildInfo)
+            return null;
+        // dbg.buildInfo is a relative path from the .dbg.json's directory.
+        const biPath = join(dbgPath, "..", dbg.buildInfo);
+        return this.loadBuildInfoFile(biPath, record.sourceName, record.contractName);
+    }
+    loadBuildInfoFile(absPath, sourceName, contractName) {
+        let file = this.buildInfoCache.get(absPath);
+        if (!file) {
+            if (!existsSync(absPath))
+                return null;
+            try {
+                file = JSON.parse(readFileSync(absPath, "utf8"));
+            }
+            catch {
+                return null;
+            }
+            this.buildInfoCache.set(absPath, file);
+        }
+        const src = file.output?.contracts?.[sourceName];
+        if (!src)
+            return null;
+        return src[contractName] ?? null;
+    }
+}
+// ---------- helpers ----------
+function* walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            yield* walk(full);
+        }
+        else if (entry.isFile()) {
+            yield full;
+        }
+    }
+}
+function inferKind(sourceName, bytecode) {
+    // Reliable: interfaces have no deployable bytecode.
+    if (bytecode === "0x" || bytecode === "")
+        return "interface";
+    // Best-effort heuristic for libraries. True library detection needs AST.
+    const normalized = sourceName.split(sep).join(posix.sep);
+    if (/\/libs?\//i.test(normalized))
+        return "library";
+    return "contract";
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

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

package/dist/bootstrap.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Ensures a DeXe-Protocol checkout is available, returning its absolute path.
+ *
+ * Priority:
+ *  1. `DEXE_PROTOCOL_PATH` env var (power-user override)
+ *  2. Auto-managed clone in 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).
+ */
+export declare function ensureProtocolCheckout(): Promise<string>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +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"}