dexe-mcp 0.1.5 → 0.2.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,38 @@
 # Changelog
 
+## 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,24 @@
 
 ![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
-
-- **Node.js >= 20** with a working `npm`. Verify before continuing:
+**Writes return calldata.** No signer ever lives in the MCP — every write tool emits a ready-to-sign `{ to, data, value, chainId, description }` payload that the agent's wallet (MetaMask, Safe, hardware, etc.) signs and submits. No `PRIVATE_KEY` env var, ever.
 
-  ```bash
-  node --version    # should print v20.x or higher
-  npm --version     # MUST print a version, not "command not found"
-  ```
+**83 tools** across 8 groups. Call `dexe_proposal_catalog` at runtime for the full proposal-type map, or browse the [catalog](#tool-catalog) 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,207 +31,123 @@ 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:
-
-```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"]
-    }
-  }
-}
-```
-
-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:
-
-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`:
+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": "dexe-mcp",
-      "env": {
-        "DEXE_PROTOCOL_PATH": "/absolute/path/to/your/DeXe-Protocol"
-      }
+      "command": "node",
+      "args": ["<output of `npm root -g`>/dexe-mcp/dist/index.js"]
     }
   }
 }
 ```
 
-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.
+Run `npm root -g` to resolve the path on your machine. Restart the MCP client and the `dexe_*` tools will appear.
 
-### Dev mode (working on dexe-mcp itself)
+## First run
 
-Clone this repo, build, and point the MCP command at the local `dist/index.js`:
+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.
 
-```bash
-git clone https://github.com/edward-arinin-web-dev/dexe-mcp.git
-cd dexe-mcp
-npm install
-npm run build
-```
+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.
 
-```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
+## Environment variables
 
-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.
+All optional. Tools that need a missing variable fail with a clear message pointing at exactly what to set.
+
+| 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`) |
 
 ## Tool catalog
 
-### Build / test
+### Dev tooling (compile / test / introspect / decode)
 
 | 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 |
+| `dexe_compile`, `dexe_test`, `dexe_coverage`, `dexe_lint` | Hardhat wrappers |
+| `dexe_list_contracts`, `dexe_get_abi`, `dexe_get_methods`, `dexe_get_selectors`, `dexe_find_selector`, `dexe_get_natspec`, `dexe_get_source` | Contract introspection from compiled artifacts |
+| `dexe_decode_calldata`, `dexe_decode_proposal`, `dexe_list_gov_contract_types` | ABI-aware calldata / proposal decoding |
 
-### Contract introspection
+### DAO reads (on-chain state via multicall + subgraph)
 
 | 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 |
+| `dexe_dao_info` | DAO overview — helpers, NFT contracts, validator count |
+| `dexe_dao_predict_addresses` | Predict CREATE2 addresses for a future DAO |
+| `dexe_dao_registry_lookup` | Is this address a registered GovPool? |
+| `dexe_proposal_state`, `dexe_proposal_list`, `dexe_proposal_voters` | Proposal reads (voters via subgraph) |
+| `dexe_vote_user_power`, `dexe_vote_get_votes` | User staking + per-proposal vote info |
+| `dexe_read_multicall` | Generic Multicall3 batched `eth_call` |
+| `dexe_read_treasury`, `dexe_read_validators`, `dexe_read_settings`, `dexe_read_expert_status` | Canned live reads |
+| `dexe_read_gov_state` | Aggregate gov-pool state (legacy helper) |
 
-### Governance domain
+### IPFS
 
 | 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 | 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"
+| `dexe_ipfs_upload_proposal_metadata`, `dexe_ipfs_upload_dao_metadata`, `dexe_ipfs_upload_file` | Pinata uploads (requires `DEXE_PINATA_JWT`) |
+| `dexe_ipfs_fetch` | Fetch by CID via configured dedicated gateway |
+| `dexe_ipfs_cid_info` | Parse CID + v0↔v1 conversion + gateway URLs |
+| `dexe_ipfs_cid_for_json` | Compute CIDv1 locally (no network) for dry-run flows |
 
-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.
+### DAO deploy
 
-### "`npm install` failed inside DeXe-Protocol"
+| Tool | Description |
+|------|-------------|
+| `dexe_dao_build_deploy` | Encode `PoolFactory.deployGovPool(GovPoolDeployParams)` with full nested-struct input (settings / validators / userKeeper / token / votePower / verifier / BABT flag / descriptionURL / name). Auto-resolves PoolFactory via registry; optionally returns the predicted GovPool address |
 
-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.
+### Proposals — primitives + catalog
 
-### "Failed to connect" in Claude Code (Windows)
+| Tool | Description |
+|------|-------------|
+| `dexe_proposal_catalog` | Enumerate **all 33** proposal types with schemas, gating, metadata shape, and the MCP tool that handles each |
+| `dexe_proposal_build_external` | Raw `GovPool.createProposal(url, actionsFor, actionsAgainst)` (+ `createProposalAndVote` variant) |
+| `dexe_proposal_build_internal` | Raw `GovValidators.createInternalProposal(type, url, data)` |
+| `dexe_proposal_build_custom_abi` | Encode any ABI call → one `ProposalAction` |
+| `dexe_proposal_build_offchain` | Generic DeXe backend HTTP request builder |
 
-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.
+### Proposal wrappers — external (on-chain)
 
-The fix is almost always to switch to the **absolute-path** registration:
+Each returns `{ metadata, actions[] }` — upload the metadata via `dexe_ipfs_upload_proposal_metadata`, then feed actions into `dexe_proposal_build_external`:
 
-```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"
-```
+`dexe_proposal_build_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*).
 
-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.
+### Proposal wrappers — internal validator
 
-### `npm install -g dexe-mcp` reported success but `dexe-mcp` is nowhere to be found
+Return `{ metadata, proposalType, data }` — compose with `dexe_proposal_build_internal`:
 
-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`.
+`dexe_proposal_build_change_validator_balances` (type 0), `_change_validator_settings` (type 1), `_monthly_withdraw` (type 2), `_offchain_internal_proposal` (type 3).
 
-### "Hardhat artifacts not found — run dexe_compile first"
+### Proposal wrappers — off-chain (DeXe backend)
 
-Introspection tools require compiled artifacts. Run `dexe_compile` once after the initial setup to populate them.
+`dexe_proposal_build_offchain_single_option`, `_offchain_multi_option`, `_offchain_for_against`, `_offchain_settings`.
 
-### "DEXE_PROTOCOL_PATH=… is missing node_modules"
+Plus auth + vote helpers: `dexe_auth_request_nonce`, `dexe_auth_login_request`, `dexe_offchain_build_vote`, `dexe_offchain_build_cancel_vote`.
 
-You pointed `DEXE_PROTOCOL_PATH` at a checkout that hasn't been installed yet. `cd` into it and run `npm install` once, then retry.
+### Vote / stake / execute / claim (direct EOA writes)
 
-### "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.
+| Tool | Description |
+|------|-------------|
+| `dexe_vote_build_erc20_approve` | ERC20 approve — prepend before `deposit` for ERC20-staking DAOs |
+| `dexe_vote_build_deposit` | `GovPool.deposit(amount, nftIds)` — payable for native-coin DAOs |
+| `dexe_vote_build_withdraw` | `GovPool.withdraw(receiver, amount, nftIds)` |
+| `dexe_vote_build_delegate`, `_undelegate` | User-level delegation on `GovPool` |
+| `dexe_vote_build_vote`, `_cancel_vote` | `GovPool.vote(pid, isFor, amount, nftIds)` / `cancelVote` |
+| `dexe_vote_build_validator_vote`, `_validator_cancel_vote` | Validator voting (internal/external scope) |
+| `dexe_vote_build_move_to_validators`, `_execute` | Proposal lifecycle |
+| `dexe_vote_build_claim_rewards`, `_claim_micropool_rewards` | Reward claiming |
+| `dexe_vote_build_multicall` | Atomic `GovPool.multicall(bytes[])` — batch any of the above into one tx |
 
 ## Contributing
 
@@ -271,10 +160,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,6 +3,16 @@ 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;
 }

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;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC,CAqDtD"}

package/dist/config.js

@@ -19,6 +19,19 @@ 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;
     let forkBlock;
     if (process.env.DEXE_FORK_BLOCK) {
         const n = Number(process.env.DEXE_FORK_BLOCK);
@@ -27,7 +40,17 @@ export async function loadConfig() {
         }
         forkBlock = n;
     }
-    return Object.freeze({ protocolPath, rpcUrl, forkBlock });
+    return Object.freeze({
+        protocolPath,
+        rpcUrl,
+        chainId,
+        registryOverride,
+        pinataJwt,
+        subgraphPoolsUrl,
+        subgraphValidatorsUrl,
+        subgraphInteractionsUrl,
+        forkBlock,
+    });
 }
 function fatal(msg) {
     // stderr only — stdout is the MCP protocol channel.

package/dist/config.js.map

@@ -1 +1 @@
-{"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"}
+{"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;AAqBnE;;;;;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,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,KAAK,CAAC,kDAAkD,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,OAAO,GAAG,CAAC,CAAC;IACd,CAAC;IAED,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAClF,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACnE,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAClF,MAAM,qBAAqB,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAC5F,MAAM,uBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC,8BAA8B,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAEhG,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;QACnB,YAAY;QACZ,MAAM;QACN,OAAO;QACP,gBAAgB;QAChB,SAAS;QACT,gBAAgB;QAChB,qBAAqB;QACrB,uBAAuB;QACvB,SAAS;KACV,CAAC,CAAC;AACL,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/lib/addresses.d.ts

@@ -0,0 +1,57 @@
+import { JsonRpcProvider } from "ethers";
+/**
+ * Per-chain `ContractsRegistry` root addresses. Every other DeXe protocol
+ * contract is resolved through `ContractsRegistry.getContract(name)` at
+ * runtime, so we only need to know the root per chain. Users can override with
+ * `DEXE_CONTRACTS_REGISTRY`.
+ *
+ * NOTE: the BSC mainnet address below matches the value shipped in the DeXe
+ * frontend env. Add more chains as they come online.
+ */
+export declare const CONTRACTS_REGISTRY_BY_CHAIN: Record<number, string>;
+/**
+ * Canonical contract names used as keys inside `ContractsRegistry`. Mirrors
+ * constants in `contracts/core/ContractsRegistry.sol` and
+ * `contracts/factory/PoolRegistry.sol` (DeXe-Protocol).
+ */
+export declare const CONTRACT_NAMES: {
+    readonly POOL_FACTORY: "POOL_FACTORY";
+    readonly POOL_REGISTRY: "POOL_REGISTRY";
+    readonly USER_REGISTRY: "USER_REGISTRY";
+    readonly CORE_PROPERTIES: "CORE_PROPERTIES";
+    readonly NETWORK_PROPERTIES: "NETWORK_PROPERTIES";
+    readonly PRICE_FEED: "PRICE_FEED";
+    readonly TREASURY: "TREASURY";
+    readonly DEXE: "DEXE";
+    readonly WETH: "WETH";
+    readonly USD: "USD";
+    readonly BABT: "BABT";
+    readonly DEXE_EXPERT_NFT: "DEXE_EXPERT_NFT";
+    readonly TOKEN_ALLOCATOR: "TOKEN_ALLOCATOR";
+};
+export type ContractName = (typeof CONTRACT_NAMES)[keyof typeof CONTRACT_NAMES];
+export interface AddressBookConfig {
+    readonly provider: JsonRpcProvider;
+    readonly chainId: number;
+    /** Optional override for the `ContractsRegistry` root. */
+    readonly registryOverride?: string;
+}
+/**
+ * Lazy, cached resolver for DeXe core contract addresses on a given chain.
+ * First call for each name hits RPC; subsequent calls return from the in-memory
+ * cache.
+ */
+export declare class AddressBook {
+    private readonly cfg;
+    private readonly cache;
+    private readonly registry;
+    readonly registryAddress: string;
+    readonly provider: JsonRpcProvider;
+    readonly chainId: number;
+    constructor(cfg: AddressBookConfig);
+    /** Resolve a canonical contract name to its deployed address on this chain. */
+    resolve(name: string): Promise<string>;
+    /** Resolve many at once (sequential — registry getContract is cheap). */
+    resolveMany(names: string[]): Promise<Record<string, string>>;
+}
+//# sourceMappingURL=addresses.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"addresses.d.ts","sourceRoot":"","sources":["../../src/lib/addresses.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,eAAe,EAAe,MAAM,QAAQ,CAAC;AAEhE;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAE9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;CAcjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAOhF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;GAIG;AACH,qBAAa,WAAW;IAOV,OAAO,CAAC,QAAQ,CAAC,GAAG;IANhC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEI,GAAG,EAAE,iBAAiB;IAgBnD,+EAA+E;IACzE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAc5C,yEAAyE;IACnE,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAKpE"}