dexe-mcp 0.1.5 → 0.3.0

package/.mcp.example.json

@@ -1,8 +1,18 @@
 {
-  "_comment": "Mac/Linux: use `dexe-mcp` directly. Windows: replace with { command: 'cmd', args: ['/c', 'dexe-mcp'] }. See README.md for the full install matrix.",
+  "_comment": "Mac/Linux: use `dexe-mcp` directly. Windows: use the absolute-path form (node.exe + dist/index.js). See README.md. Env vars are all optional — tools that need them fail with a clear message.",
   "mcpServers": {
     "dexe": {
-      "command": "dexe-mcp"
+      "command": "dexe-mcp",
+      "env": {
+        "DEXE_PROTOCOL_PATH": "/absolute/path/to/DeXe-Protocol",
+        "DEXE_RPC_URL": "https://bsc-dataseed.binance.org",
+        "DEXE_CHAIN_ID": "56",
+        "DEXE_PINATA_JWT": "<your Pinata JWT>",
+        "DEXE_IPFS_GATEWAY": "https://<your-subdomain>.mypinata.cloud",
+        "DEXE_IPFS_GATEWAYS_FALLBACK": "https://dweb.link,https://ipfs.io",
+        "DEXE_SUBGRAPH_INTERACTIONS_URL": "https://api.studio.thegraph.com/query/.../dao-interactions/...",
+        "DEXE_BACKEND_API_URL": "https://api.dexe.io"
+      }
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.3.0
+
+End-to-end testnet validation. Every proposal-builder tool is now exercised by an automated swarm scenario on BSC testnet, and the harness itself ships in-repo so external integrators can run it. **111 tools** total, **41 swarm scenarios**, full sweep green.
+
+### Added
+
+**Swarm test harness (`tests/swarm/` + `scripts/swarm/`)**
+- `scripts/swarm/orchestrator.ts` — scenario loader + dispatcher. Inline ethers dispatchers for the no-IPFS toolset (vote_user_power, read_delegation_map, build_undelegate, build_withdraw, build_withdraw_all, build_erc20_approve, build_deposit, build_delegate, build_vote). Generic MCP-stdio fallback (`mcpFallbackDispatcher`) routes anything else through the dexe-mcp child server, so adding a scenario for a new tool is JSON-only — no code changes.
+- Loop expansion (`spec.loop.over` × `appliesToSteps`), template engine (`{{dao}}`, `{{firstAllowlistedToken}}`, `{{firstAllowlistedDao}}`, `{{secondAllowlistedDao}}`, `{{dao.<helper>}}`, `{{agent:X:address}}`, `{{capture.path}}`, `{{capture.0.field}}`), `skipIf` evaluator with limited expressions, deferred-cascade for chained captures, wallet semaphore for parallel-safe broadcasts, per-scenario `prefund` hook that tops up agents from `AGENT_FUNDER_PK` before each scenario runs.
+- `scripts/swarm/preflight.ts` + `scripts/swarm/fund-pool.ts` — wallet-readiness check + token allowlist–enforced top-up. Hard-refuses to send to any non-pool address or any token not on the allowlist.
+- `scripts/swarm/nightly.sh` — Phase 5 cron runner. Pulls main, runs preflight + full sweep, tails the run report, posts the one-line summary to `SWARM_SUMMARY_WEBHOOK` and/or `SWARM_SUMMARY_ISSUE` (gh CLI), runs a triage stub on failure (with `SWARM_FIXER=1` opt-in for auto-fix), and rotates run-report dirs older than 30 days while keeping the latest 50.
+- `scripts/swarm/orchestrator.ts` emits a single greppable summary line after `writeReport`: `SWARM <runId> <pass>/<total> <mode> <chainTag> <reportPath>` — consumed by nightly.sh and any external poster.
+- `scripts/swarm/one-shot-execute.mjs` — closes a proposal lifecycle once it reaches `SucceededFor`. Polls + caps `wait()` at 90 s to avoid sandbox hangs.
+- 41 scenario JSONs covering: reset, delegation chain, validator pass / veto / full lifecycle, expert / participation / staking / validator / catalog / cross-DAO / multi-proposal-state read snapshots, cancel-vote, decode-and-introspect, build-only sanity for every external + internal proposal type from `dexe_proposal_catalog`.
+- Role prompts: `proposer`, `voter`, `delegator`, `reporter`, `triage`, `validator`, `expert`, `fixer`, plus `_shared.md` and the dao-personas fixture. Fixer prompt encodes the CLAUDE.md auto-fix loop verbatim — branch `swarm-fix/<YYYY-MM-DD>`, never push to main, diff scope hard-bounded to `src/tools/`, `src/lib/`, `tests/swarm/`.
+
+**Composite + signing tools**
+- `dexe_proposal_create` — full prerequisite handling: balance check, ERC20 approve, deposit, IPFS metadata upload, `createProposalAndVote`. When `DEXE_PRIVATE_KEY` is set the tool signs and broadcasts; otherwise returns the ordered `TxPayload` list. Supports `proposalType: 'modify_dao_profile' | 'custom'`.
+- `dexe_proposal_vote_and_execute` — vote-then-execute composite with `autoExecute` + `depositFirst` flags.
+- `dexe_tx_send` + `dexe_tx_status` — opt-in signer surface that uses the configured `DEXE_PRIVATE_KEY` when present. Calls remain calldata-by-default; users opt in by setting the env var.
+- `dexe_dao_build_deploy` predicted-address auto-wiring: `govToken` flowed into `userKeeperParams.tokenAddress` and `distributionProposal` + `govTokenSale` into `additionalProposalExecutors` automatically. LINEAR / POLYNOMIAL `votePower` initData auto-encoded.
+
+**Reads + introspection**
+- `dexe_read_dao_list`, `_dao_members`, `_dao_experts`, `_user_activity`, `_distribution_status`, `_token_sale_tiers`, `_token_sale_user`, `_staking_info`, `_validator_list`, `_privacy_policy_status`, `_delegation_map` — fill out the DAO read surface.
+- `dexe_get_methods` returns structured per-function metadata (4-byte selectors, mutability, full structured inputs/outputs with `internalType` preserved for tuples).
+- `dexe_proposal_voters` switched to the `pools` subgraph and the proposalInteractions composite ID format (poolAddr + uint32LE(proposalId), no separator).
+- `dexe_decode_proposal` understands every external + internal proposal action shape.
+
+### Fixed
+
+- **Proposal metadata format**: builders now emit `proposalName` / `proposalDescription` (not `name` / `description`), wrap diffs inside `changes: { proposedChanges, currentChanges }`, set `isMeta: false`, and round-trip identical to the frontend reference. 17 builders touched.
+- **Approve target for deposits** is `UserKeeper`, not `GovPool`. Both flow tools (`proposal_create`, `vote_and_execute`) now approve the right address.
+- **Personal voting power** = `tokenBalance.balance − ownedBalance` (deposited only). Without this, `withdraw` on freshly-funded agents reverts `GovUK: can't withdraw this`.
+- **VotePower initData** uses `__LinearPower_init()` selector `0x892aea1f` (not empty `0x`) so newly-deployed DAOs initialize their LINEAR vote-power proxy correctly.
+- **`STATE_NAMES` enum order** corrected (Defeated / Locked positions were swapped).
+- **Custom-proposal IPFS metadata** now includes `category`, `isMeta`, `proposedChanges`, `currentChanges`.
+- **Subgraph migration**: Studio URLs deprecated; switched to The Graph decentralized network with API key. Per-chain endpoints documented.
+- **IPFS gateway path normalization**: dedicated gateways configured with a trailing `/ipfs` (e.g. `https://<sub>.mypinata.cloud/ipfs`) no longer produce `/ipfs/ipfs/<cid>` 404s.
+
+### Changed
+
+- README updated: tool count `83 → 111`, new "Swarm test harness" section.
+- `process.loadEnvFile()` is invoked from `index.ts` so the MCP server loads `.env` itself; users no longer have to plumb env-var changes through their MCP client config (which often doesn't reload).
+- Repo now ships `.claude/skills/swarm-test/SKILL.md` for users running Claude Code; lets them invoke the swarm with `/swarm-test`.
+
+### Notes
+
+- **Validated network**: BSC testnet (chain 97). Two fixture DAOs deployed for the harness — Glacier (50% quorum, no validators) and Sentinel (5% quorum, 2 validators with 1k SVT each).
+- **Mainnet status**: a separate run pass is staged (Stage B per `tests/swarm/README.md`) but blocked on a previously-observed `PoolFactory.deployGovPool` revert. Re-validate when the protocol team confirms a fix.
+- **Off-chain backend tools** require `DEXE_BACKEND_API_URL` and only run on chains where DeXe operates a backend. The corresponding swarm scenarios declare `requiresChain: [56]` so they auto-skip on testnet.
+
+## 0.2.0
+
+The big one — dexe-mcp expands from 15 dev-tooling tools to **83 tools** covering the full DeXe DAO lifecycle. AI agents can now create DAOs, build any of the 33 proposal types the DeXe frontend exposes, upload metadata to IPFS, stake/delegate/vote/execute/claim — all end-to-end.
+
+### Added
+
+**Foundations + reads (13 tools)** — `dexe_dao_info`, `dexe_dao_predict_addresses`, `dexe_dao_registry_lookup`, `dexe_proposal_state`, `dexe_proposal_list`, `dexe_proposal_voters`, `dexe_vote_user_power`, `dexe_vote_get_votes`, `dexe_read_multicall`, `dexe_read_treasury`, `dexe_read_validators`, `dexe_read_settings`, `dexe_read_expert_status`. Backed by an `AddressBook` that resolves contracts via `ContractsRegistry`, a Multicall3 batch helper, a canonical `TxPayload` shape, enum mirrors for `ProposalState` / `VoteType`, and a minimal subgraph GraphQL client.
+
+**IPFS (6 tools)** — `dexe_ipfs_upload_proposal_metadata`, `_upload_dao_metadata`, `_upload_file`, `_fetch`, `_cid_info`, `_cid_for_json`. Backed by a Pinata client and local CID computation via `multiformats`. Public gateways (dweb.link, ipfs.io, cf-ipfs, 4everland) are unreliable and NOT defaulted. Users must set `DEXE_IPFS_GATEWAY` to a dedicated gateway (the one Pinata provides alongside the JWT is recommended). Public gateways are opt-in via `DEXE_IPFS_GATEWAYS_FALLBACK` (comma-separated, tried sequentially — no parallel races).
+
+**Proposals — all 33 types (35 tools)**
+- `dexe_proposal_catalog` — enumerate every proposal type the DeXe UI exposes (24 external, 4 internal, 5 off-chain), with metadata shape, gating, and linked MCP builder.
+- Primitives: `dexe_proposal_build_external` (+ `createProposalAndVote`), `dexe_proposal_build_internal`, `dexe_proposal_build_custom_abi`, `dexe_proposal_build_offchain`.
+- External wrappers (each returns `{ metadata, actions: Action[] }`): `token_transfer`, `token_distribution`, `token_sale`, `token_sale_recover`, `change_voting_settings`, `manage_validators`, `add_expert`, `remove_expert`, `withdraw_treasury`, `delegate_to_expert`, `revoke_from_expert`, `create_staking_tier`, `change_math_model`, `modify_dao_profile`, `blacklist`, `reward_multiplier`, `apply_to_dao`, `new_proposal_type` (also covers *Enable Staking*).
+- Internal validator wrappers (each returns `{ metadata, proposalType, data }`): `change_validator_balances` (type 0), `change_validator_settings` (type 1), `monthly_withdraw` (type 2), `offchain_internal_proposal` (type 3).
+- Off-chain backend proposals: `offchain_single_option`, `offchain_multi_option`, `offchain_for_against`, `offchain_settings`. Plus `dexe_auth_request_nonce` + `dexe_auth_login_request` for the 2-step Bearer flow, and `dexe_offchain_build_vote` / `dexe_offchain_build_cancel_vote`.
+- **Write model is calldata-only.** No signer, no private keys. Every write tool emits a signable payload the agent's wallet submits.
+
+**Vote / stake / execute / claim writes (14 tools)** — `erc20_approve`, `deposit` (payable for native-staking DAOs), `withdraw`, `delegate`, `undelegate`, `vote`, `cancel_vote`, `validator_vote`, `validator_cancel_vote`, `move_to_validators`, `execute`, `claim_rewards`, `claim_micropool_rewards`, plus `multicall` to batch any of the above into one atomic tx. Arg-order gotchas captured in code comments (e.g. `GovPool.vote(pid, isFor, amount, nftIds)` vs `GovValidators.voteInternalProposal(pid, amount, isFor)`).
+
+**DAO deploy (1 tool)** — `dexe_dao_build_deploy` encodes `PoolFactory.deployGovPool(GovPoolDeployParams)` with the full nested struct (settings / validators / userKeeper / token / votePower / verifier / BABT flag / descriptionURL / name). Auto-resolves PoolFactory via `ContractsRegistry` if omitted. When `deployer` + RPC are available, also returns the predicted GovPool address so agents can wire follow-up txs before the DAO exists. Encodes against the compiled `PoolFactory.json` artifact when present (strict parity); falls back to a hand-rolled tuple signature derived from `IPoolFactory.sol` otherwise.
+
+### Changed
+
+- `src/config.ts` adds `DEXE_CHAIN_ID` (default 56), `DEXE_CONTRACTS_REGISTRY` override, `DEXE_PINATA_JWT`, three subgraph URL overrides, `DEXE_BACKEND_API_URL`.
+- `package.json` description rewritten to reflect full DAO-ops scope. New dep: `multiformats` (Protocol Labs, for local CID computation).
+- `README.md` reorganized around the eight tool groups; added the full env-var matrix.
+
+### Notes
+
+- **No breaking changes.** All v0.1.x tools remain. The write contract is new-world: `TxPayload` for single-tx builders, `Action[]` for proposal wrappers — never a singular `action` field.
+- **Deferred to future work** (`FUTURE.md`): Hardhat-fork simulation (`dexe_simulate_vote`), signer-aware send mode, additional IPFS pinning providers (Storacha, Lighthouse), and alternate subgraphs.
+
 ## 0.1.5
 
 ### Fixed

package/FUTURE.md

@@ -1,8 +1,29 @@
 # Future work
 
-Tracking features deliberately deferred out of the Phase A / B roadmap.
+Deliberately deferred out of v0.2.0. Kept here so we don't re-litigate during planning.
 
-## `dexe_get_storage_layout` (dropped from v1)
+## Signer-aware send mode
+
+Every v0.2.0 write tool returns calldata (`TxPayload`). Actually *sending* the tx — reading a `PRIVATE_KEY` or opening a local keystore and submitting via ethers `Wallet.sendTransaction` — is deferred. Reason: scope + security posture. We don't want private keys anywhere near the MCP process by default. If re-opened, expose as an opt-in mode gated on an explicit `DEXE_SIGNING_MODE=enabled` env var with loud warnings in tool output.
+
+## `dexe_simulate_vote` + Hardhat fork management
+
+Spawn a managed `hardhat node --fork $DEXE_RPC_URL` child process owned by the MCP, impersonate a voter, submit the `vote` calldata against the fork, and report success/revert with gas used. Would live in `src/fork.ts`.
+
+## Additional IPFS pinning providers
+
+v0.2.0 ships Pinata only. Reasonable candidates if we need a second:
+- **Lighthouse.storage** — one-time payment, permanent Filecoin storage. Best long-term fit for DAO metadata that must never disappear. User has flagged interest.
+- **Storacha / web3.storage** — UCAN-based, Filecoin-backed, free tier.
+- **Filebase** — S3-compatible, Filecoin-backed.
+
+Design: extend `src/lib/ipfs.ts` with an `IpfsUploader` interface, factor Pinata into an adapter, add new adapters behind `DEXE_IPFS_PROVIDER`.
+
+## Additional subgraphs
+
+We wire `DEXE_SUBGRAPH_INTERACTIONS_URL` (voter lists) and reserved slots for pools/validators subgraphs. Fleshing out list/search tools that use those other subgraphs is deferred — driven by user demand.
+
+## `dexe_get_storage_layout`
 
 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.
 
@@ -25,13 +46,13 @@ solidity: {
 
 Then the tool becomes a short handler reading `output.contracts[file][name].storageLayout` from the matching build-info JSON.
 
-## `dexe_simulate_vote` (Phase B)
+## Fixture tests for write builders
 
-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`.
+Phase 3 and 4 wrappers were verified against the DeXe frontend encodings but don't yet have byte-for-byte golden-file tests. For every `*_build_*` tool, capture the hex calldata from the frontend on identical inputs and snapshot it.
 
 ## 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).
+- **Custom `hardhat-migrate` wrappers** — out of scope per user decision (deployment tooling excluded from the dev-tool surface).
 - **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/README.md

@@ -2,51 +2,26 @@
 
 ![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.
+MCP server that gives AI agents **full DeXe Protocol DAO operations coverage** — deploy DAOs, build any of the 33 proposal types the DeXe UI exposes, upload metadata to IPFS, stake/delegate/vote/execute/claim. Plus dev tooling: build/test/lint, contract introspection, ABI-aware calldata decoding.
 
-## Prerequisites
+**Two write modes, calldata-default.** Every write tool returns a ready-to-sign `TxPayload = { to, data, value, chainId, description }` that the agent's wallet (MetaMask, Safe, hardware, etc.) signs and submits — no key in the MCP. Power users who *want* the server to sign and broadcast can opt in by setting `DEXE_PRIVATE_KEY`; that unlocks `dexe_tx_send`, `dexe_tx_status`, and the auto-broadcast branch of `dexe_proposal_create` / `dexe_proposal_vote_and_execute`. Default stays calldata-only.
 
-- **Node.js >= 20** with a working `npm`. Verify before continuing:
+**111 tools** across 9 groups. Call `dexe_proposal_catalog` at runtime for the full proposal-type map, or browse the [catalog](#tool-catalog) below.
 
-  ```bash
-  node --version    # should print v20.x or higher
-  npm --version     # MUST print a version, not "command not found"
-  ```
+> **End-to-end coverage.** Every proposal-builder tool ships with a swarm-test scenario that exercises it on BSC testnet. Latest pass: **41/41 scenarios green**, ~200 broadcasts validated against two fixture DAOs (Glacier 50%-quorum + Sentinel 5%-quorum-with-validators). See [Swarm test harness](#swarm-test-harness) below.
 
-  If `npm --version` fails, you have a stripped Node install (a bare `node.exe` without the rest of the toolchain — common on Windows when `C:\Program Files\nodejs\node.exe` was placed manually). Install Node from <https://nodejs.org> or via [nvm](https://github.com/nvm-sh/nvm) / [nvm-windows](https://github.com/coreybutler/nvm-windows) and retry. Without npm, `npm install -g dexe-mcp` silently does nothing.
+## Prerequisites
 
-- **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.
+- **Node.js ≥ 20** with a working `npm` (`node --version` and `npm --version` must both succeed).
+- **Git** — only needed the first time a build tool runs, to clone DeXe-Protocol. Skippable if you point `DEXE_PROTOCOL_PATH` at an existing checkout.
 
 ## Install
 
-### 1. Install the package globally
-
 ```bash
 npm install -g dexe-mcp
 ```
 
-Verify the install landed by asking npm where it put it:
-
-```bash
-npm root -g
-# Mac/Linux:  /usr/local/lib/node_modules       (or ~/.nvm/versions/node/vXX.X.X/lib/node_modules)
-# Windows:    C:\Users\<you>\AppData\Roaming\nvm\<version>\node_modules
-#             (or C:\Users\<you>\AppData\Roaming\npm\node_modules for non-nvm)
-```
-
-Note the output — you'll need it for the Windows install step below. The package lives at `<npm-root>/dexe-mcp/dist/index.js`.
-
-### 2. Register the MCP server
-
-#### Mac / Linux
-
-Bare command works because Unix `exec` resolves PATH directly:
-
-```bash
-claude mcp add dexe -- dexe-mcp
-```
-
-Or in JSON (`.mcp.json`, `claude_desktop_config.json`, etc.):
+Register the server with your MCP client (`.mcp.json`, `claude_desktop_config.json`, etc.):
 
 ```json
 {
@@ -58,84 +33,24 @@ Or in JSON (`.mcp.json`, `claude_desktop_config.json`, etc.):
 }
 ```
 
-#### Windows — recommended: absolute path to `node` + `dist/index.js`
-
-On Windows, `dexe-mcp` is installed as a `.cmd` shim that many MCP clients (including Claude Code as of this writing) fail to spawn cleanly over stdio. The **absolute-path** form bypasses shim resolution entirely and is the known-good recipe:
-
-```bash
-claude mcp add dexe -- "C:\Program Files\nodejs\node.exe" "C:\Users\<you>\AppData\Roaming\nvm\<version>\node_modules\dexe-mcp\dist\index.js"
-```
-
-Substitute `<you>` and `<version>` (or use whatever `npm root -g` printed above). In JSON:
+If your client can't spawn the bare `dexe-mcp` command directly (a known issue with some MCP clients on Windows when PATH-shim resolution is involved), point it at the installed script via Node:
 
 ```json
 {
   "mcpServers": {
     "dexe": {
-      "command": "C:/Program Files/nodejs/node.exe",
-      "args": ["C:/Users/<you>/AppData/Roaming/nvm/<version>/node_modules/dexe-mcp/dist/index.js"]
-    }
-  }
-}
-```
-
-This works because:
-- No PATH dependency — every argument is an absolute path
-- No `.cmd` / `.ps1` shim in the chain, so `CreateProcess` semantics don't trip over missing extensions
-- `dexe-mcp` internally invokes `npm`/`hardhat` via `process.execPath`, so it uses whichever Node you pointed at and does not need npm on the spawned process PATH
-
-<details>
-<summary>Alternative: <code>cmd /c dexe-mcp</code> (not recommended — often unreliable with Claude Code)</summary>
-
-```json
-{
-  "mcpServers": {
-    "dexe": {
-      "command": "cmd",
-      "args": ["/c", "dexe-mcp"]
+      "command": "node",
+      "args": ["<output of `npm root -g`>/dexe-mcp/dist/index.js"]
     }
   }
 }
 ```
 
-Use only if the absolute-path form is inconvenient. End-to-end testing showed this can pass a direct stdio check but fail to complete the MCP handshake when spawned by Claude Code.
-</details>
-
-### 3. Verify the install (optional but recommended)
-
-Before wiring the server into your MCP client, confirm the binary can actually speak MCP over stdio. On any OS:
-
-```bash
-# Send a minimal initialize request, expect a capabilities JSON back.
-echo "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"t\",\"version\":\"1\"}}}" | dexe-mcp
-```
-
-On Windows if the above hangs, try instead:
-
-```bash
-echo {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}} | node "C:\Users\<you>\AppData\Roaming\nvm\<version>\node_modules\dexe-mcp\dist\index.js"
-```
-
-A healthy response starts with a single stderr line (`[dexe-mcp] connected on stdio. …`) and a stdout JSON blob containing `"serverInfo":{"name":"dexe-mcp"}`. If you see that, the server is fine and any "failed to connect" from your MCP client is purely a client-side spawn/config problem, not a bug in dexe-mcp.
-
-### 4. Restart your MCP client
-
-On the first build-tool call (e.g. `dexe_compile`), `dexe-mcp` will automatically:
+Run `npm root -g` to resolve the path on your machine. Restart the MCP client and the `dexe_*` tools will appear.
 
-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)
+## Quickstart
 
-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`:
+Minimum config to get **read-only** access to a BSC mainnet DAO:
 
 ```json
 {
@@ -143,122 +58,119 @@ If you already have a DeXe-Protocol clone you want to reuse (and have run `npm i
     "dexe": {
       "command": "dexe-mcp",
       "env": {
-        "DEXE_PROTOCOL_PATH": "/absolute/path/to/your/DeXe-Protocol"
+        "DEXE_RPC_URL": "https://bsc-dataseed.binance.org",
+        "DEXE_CHAIN_ID": "56"
       }
     }
   }
 }
 ```
 
-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.
+Add `DEXE_PINATA_JWT` for IPFS uploads, `DEXE_BACKEND_API_URL` for off-chain proposals, and per-chain subgraph URLs for `dexe_proposal_voters` and the DAO-list reads. Full matrix → [`docs/ENVIRONMENT.md`](./docs/ENVIRONMENT.md).
 
-### Dev mode (working on dexe-mcp itself)
+Three first-call examples (full set in [`docs/USAGE.md`](./docs/USAGE.md)):
 
-Clone this repo, build, and point the MCP command at the local `dist/index.js`:
+```jsonc
+// 1) discover available proposal types
+dexe_proposal_catalog({ category: "all", implementedOnly: true })
 
-```bash
-git clone https://github.com/edward-arinin-web-dev/dexe-mcp.git
-cd dexe-mcp
-npm install
-npm run build
-```
+// 2) read a DAO
+dexe_dao_info({ govPool: "0x..." })
 
-```json
-{
-  "mcpServers": {
-    "dexe": {
-      "command": "node",
-      "args": ["/absolute/path/to/dexe-mcp/dist/index.js"],
-      "env": {
-        "DEXE_PROTOCOL_PATH": "/absolute/path/to/DeXe-Protocol"
-      }
-    }
-  }
-}
+// 3) build a token-transfer proposal (calldata only)
+dexe_proposal_build_token_transfer({
+  govPool: "0x...",
+  token:   "0x...",
+  recipient: "0x...",
+  amount: "1000000000000000000"
+})
 ```
 
 ## 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. On a brand-new install the first `dexe_compile` also triggers the clone + `npm install` steps described above.
-
-## 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 |
+The MCP server starts instantly. On the first build-tool call (`dexe_compile` / `dexe_test` / `dexe_lint`), dexe-mcp will automatically shallow-clone DeXe-Protocol into a platform cache directory and run `npm install` there once. If you prefer to reuse an existing checkout, set `DEXE_PROTOCOL_PATH` in the MCP `env` block and nothing will be cloned.
 
-### 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_methods` | Enumerate read (view/pure) and write (nonpayable/payable) methods with structured inputs/outputs and `internalType` — for generating TypeScript interfaces |
-| `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 |
+Most tools don't need the protocol checkout at all — read/proposal/vote/deploy builders only need an RPC URL. Only the dev-tooling group (`dexe_compile`, `dexe_test`, `dexe_coverage`, `dexe_lint`, and the introspection tools) depends on artifacts.
 
 ## Environment variables
 
-| Variable | Required | Purpose |
-|----------|----------|---------|
-| `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)
-
-Run the direct stdio test from the "Verify the install" section first. If that prints a clean `serverInfo` response, the server is fine and the problem is in how your client is spawning it.
-
-The fix is almost always to switch to the **absolute-path** registration:
+All optional. Tools that need a missing variable fail with a clear message pointing at exactly what to set. Full matrix + per-tool requirements → [`docs/ENVIRONMENT.md`](./docs/ENVIRONMENT.md).
+
+| Variable | Required for | Purpose |
+|----------|--------------|---------|
+| `DEXE_PROTOCOL_PATH` | dev tooling (optional) | Use an existing DeXe-Protocol checkout; disables auto clone/install |
+| `DEXE_RPC_URL` | reads / predict / deploy | JSON-RPC endpoint (BSC or any EVM chain where DeXe is deployed) |
+| `DEXE_CHAIN_ID` | reads | Defaults to `56` (BSC mainnet). Override for other chains |
+| `DEXE_CONTRACTS_REGISTRY` | reads (optional) | Override the ContractsRegistry root; defaults to the known per-chain address |
+| `DEXE_PINATA_JWT` | IPFS uploads | Pinata JWT for pinning proposal/DAO metadata |
+| `DEXE_IPFS_GATEWAY` | IPFS fetch | **Dedicated** gateway URL (Pinata provides one alongside your JWT; Filebase / Quicknode / self-hosted also work). Public gateways are unreliable and NOT defaulted |
+| `DEXE_IPFS_GATEWAYS_FALLBACK` | IPFS fetch (optional) | Comma-separated public gateways tried sequentially after the primary |
+| `DEXE_SUBGRAPH_INTERACTIONS_URL` | `dexe_proposal_voters` | The Graph endpoint for the DeXe interactions subgraph |
+| `DEXE_SUBGRAPH_POOLS_URL`, `DEXE_SUBGRAPH_VALIDATORS_URL` | reserved | Additional subgraph endpoints for future tools |
+| `DEXE_BACKEND_API_URL` | off-chain proposals | DeXe backend (e.g. `https://api.dexe.io`) |
+
+## Documentation
+
+Full docs in [`docs/`](./docs):
+
+- [`docs/TOOLS.md`](./docs/TOOLS.md) — complete catalog of all 111 tools, organized by category, with one-line descriptions and required envs per tool.
+- [`docs/USAGE.md`](./docs/USAGE.md) — 10 worked examples (deploy DAO, create proposals, vote, delegate, validator chamber, decode calldata, off-chain proposals, multicall batching). Copy-pasteable JSON.
+- [`docs/ENVIRONMENT.md`](./docs/ENVIRONMENT.md) — full env-var reference: minimum block to get started, per-category requirements, calldata vs signer mode, chain-specific config, IPFS gateway rationale, subgraph migration, swarm harness envs, common pitfalls.
+
+## Tool surface (high-level)
+
+| Group | Tools | What |
+|-------|-------|------|
+| Dev tooling | 4 | Hardhat wrappers: `dexe_compile`, `_test`, `_coverage`, `_lint` |
+| Contract introspection | 10 | `_list_contracts`, `_get_abi`, `_get_methods`, `_get_selectors`, `_find_selector`, `_get_natspec`, `_get_source`, `_decode_calldata`, `_decode_proposal`, `_list_gov_contract_types` |
+| DAO reads | 25 | `_dao_info`, `_dao_predict_addresses`, `_dao_registry_lookup`, `_proposal_state/_list/_voters`, `_vote_user_power/_get_votes`, `_read_*` family |
+| IPFS | 6 | Pinata uploads, gateway fetch, CID computation |
+| DAO deploy | 1 | `dexe_dao_build_deploy` (encodes `PoolFactory.deployGovPool` with full nested struct + predicted addr wiring) |
+| Proposal catalog + primitives | 5 | `dexe_proposal_catalog` enumerates **all 33** types; primitives: `_build_external`, `_build_internal`, `_build_custom_abi`, `_build_offchain` |
+| External proposal wrappers | 18 | Token transfer / distribution / sale, treasury withdraw, validators, experts, staking tier, math model, blacklist, reward multiplier, apply to DAO, modify profile, change voting settings, new proposal type, etc. |
+| Internal validator wrappers | 4 | `_change_validator_balances`, `_change_validator_settings`, `_monthly_withdraw`, `_offchain_internal_proposal` |
+| Off-chain backend | 8 | `_offchain_single_option/_multi_option/_for_against/_settings`, auth flow (`_auth_request_nonce`, `_auth_login_request`), `_offchain_build_vote/_cancel_vote` |
+| Vote / stake / delegate / execute / claim | 16 | `_vote_build_*` family — every direct EOA write on GovPool / Validators |
+| Composite signing flows | 4 | `_proposal_create`, `_proposal_vote_and_execute`, `_tx_send`, `_tx_status` (all opt-in via `DEXE_PRIVATE_KEY`) |
+| Subgraph reads | 6 | DAO list, members, experts, user activity, delegation map, distribution status (decentralized network endpoints) |
+
+Total: **~111**. Per-tool descriptions, args, return shapes → [`docs/TOOLS.md`](./docs/TOOLS.md).
+
+## Swarm test harness
+
+`tests/swarm/` is a multi-agent DAO testing harness that exercises every dexe-mcp
+tool against real BSC-testnet DAOs. Scenarios are JSON specs; the orchestrator
+loads them, resolves agent wallets, and runs each step through either an inline
+ethers dispatcher or the dexe-mcp stdio bridge.
+
+**41 scenarios shipped** covering:
+
+- Reset + delegation chains (S00, S01, S06, S14)
+- Validator chamber pass / veto / full lifecycle (S02, S03, S07)
+- Read-only snapshots: expert state, participation, validators, cross-DAO,
+  catalog, multi-proposal state, user activity (S04, S05, S09, S10, S11, S13, S15)
+- Cancel-vote, decode-and-introspect (S08, S12)
+- Build-only sanity for every proposal type in `dexe_proposal_catalog`
+  (token transfer, blacklist, withdraw treasury, apply to dao, token
+  distribution, token sale + recover, manage validators, change validator
+  balances/settings, monthly withdraw, add/remove expert (local + global),
+  delegate/revoke from expert, reward multiplier (4 modes), change voting
+  settings, new proposal type, change math model, custom ABI, manual calldata,
+  create staking tier, off-chain validator + for/against + settings) (S16–S40)
 
 ```bash
-claude mcp remove dexe
-claude mcp add dexe -- "C:\Program Files\nodejs\node.exe" "C:\Users\<you>\AppData\Roaming\nvm\<version>\node_modules\dexe-mcp\dist\index.js"
+# 1) generate 9 wallets (8 agents + funder), fund the funder from your wallet
+# 2) deploy fixture DAOs via dexe_dao_build_deploy (one 50% quorum + one with validators)
+# 3) configure SWARM_DAOS_TESTNET / SWARM_TOKENS_TESTNET / SWARM_RPC_URL_TESTNET
+npm run swarm:preflight                # red/green table per wallet
+npm run swarm:fund -- --confirm        # broadcast top-ups from funder
+npm run swarm:run                      # full sweep, all scenarios
+npm run swarm:run -- --scenarios=S00-reset,S01-delegation-chain-3hop --dry-run
 ```
 
-Bare `dexe-mcp` and `cmd /c dexe-mcp` both rely on shim resolution that Claude Code's `CreateProcess`-based spawn does not always handle. The absolute-path form has zero shim resolution.
-
-### `npm install -g dexe-mcp` reported success but `dexe-mcp` is nowhere to be found
-
-You're almost certainly on a stripped Node install whose `npm` silently no-ops. Check with `npm --version` — if it fails, install Node properly (see Prerequisites). If it prints a version, check `npm root -g` and look inside that directory; the package should be at `<npm-root>/dexe-mcp`.
-
-### "Hardhat artifacts not found — run dexe_compile first"
-
-Introspection tools require compiled artifacts. Run `dexe_compile` once after the initial setup to populate them.
-
-### "DEXE_PROTOCOL_PATH=… is missing node_modules"
-
-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"
-
-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.
+Setup runbook: [`tests/swarm/README.md`](tests/swarm/README.md).
+Scenario schema: [`tests/swarm/scenarios/_schema.md`](tests/swarm/scenarios/_schema.md).
+Per-role agent prompts: `tests/swarm/prompts/`.
 
 ## Contributing
 
@@ -271,10 +183,6 @@ 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/config.d.ts

@@ -3,8 +3,20 @@ export interface DexeConfig {
     protocolPath: string;
     /** Optional JSON-RPC endpoint for on-chain gov tools. */
     rpcUrl?: string;
+    /** Chain id the RPC points at. Defaults to 56 (BSC mainnet, DeXe home). */
+    chainId: number;
+    /** Override for `ContractsRegistry` root address. */
+    registryOverride?: string;
+    /** Pinata JWT for IPFS uploads (reads work without it via gateway). */
+    pinataJwt?: string;
+    /** GraphQL endpoint URLs for The Graph subgraphs. */
+    subgraphPoolsUrl?: string;
+    subgraphValidatorsUrl?: string;
+    subgraphInteractionsUrl?: string;
     /** Optional fork block pin (Phase B). */
     forkBlock?: number;
+    /** Private key for tx signing. When set, `dexe_tx_send` can broadcast. */
+    privateKey?: string;
 }
 /**
  * Reads environment and returns a frozen config. **Fast and side-effect-free**

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,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"}
+{"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,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CAgEtD"}

package/dist/config.js

@@ -19,6 +19,28 @@ export async function loadConfig() {
         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 chainId = 56;
+    if (process.env.DEXE_CHAIN_ID) {
+        const n = Number(process.env.DEXE_CHAIN_ID);
+        if (!Number.isFinite(n) || n <= 0) {
+            fatal(`DEXE_CHAIN_ID must be a positive integer, got: ${process.env.DEXE_CHAIN_ID}`);
+        }
+        chainId = n;
+    }
+    const registryOverride = process.env.DEXE_CONTRACTS_REGISTRY?.trim() || undefined;
+    const pinataJwt = process.env.DEXE_PINATA_JWT?.trim() || undefined;
+    const subgraphPoolsUrl = process.env.DEXE_SUBGRAPH_POOLS_URL?.trim() || undefined;
+    const subgraphValidatorsUrl = process.env.DEXE_SUBGRAPH_VALIDATORS_URL?.trim() || undefined;
+    const subgraphInteractionsUrl = process.env.DEXE_SUBGRAPH_INTERACTIONS_URL?.trim() || undefined;
+    const privateKey = process.env.DEXE_PRIVATE_KEY?.trim() || undefined;
+    if (privateKey && !rpcUrl) {
+        fatal("DEXE_PRIVATE_KEY requires DEXE_RPC_URL to be set (signing needs an RPC endpoint).");
+    }
+    if (privateKey) {
+        const { Wallet } = await import("ethers");
+        const addr = new Wallet(privateKey).address;
+        process.stderr.write(`[dexe-mcp] signing enabled for ${addr}\n`);
+    }
     let forkBlock;
     if (process.env.DEXE_FORK_BLOCK) {
         const n = Number(process.env.DEXE_FORK_BLOCK);
@@ -27,7 +49,18 @@ export async function loadConfig() {
         }
         forkBlock = n;
     }
-    return Object.freeze({ protocolPath, rpcUrl, forkBlock });
+    return Object.freeze({
+        protocolPath,
+        rpcUrl,
+        chainId,
+        registryOverride,
+        pinataJwt,
+        subgraphPoolsUrl,
+        subgraphValidatorsUrl,
+        subgraphInteractionsUrl,
+        forkBlock,
+        privateKey,
+    });
 }
 function fatal(msg) {
     // stderr only — stdout is the MCP protocol channel.