dexe-mcp 0.21.0 → 0.22.0

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -60,19 +60,46 @@ if (subcommand === "skills") {
     await mod.run(process.argv.slice(3));
     process.exit(0);
 }
+/** Real package version — the MCP handshake previously hardcoded "0.1.5". */
+function packageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(__dirname, "..", "package.json"), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 async function main() {
     const config = await loadConfig();
-    const server = new McpServer({ name: "dexe-mcp", version: "0.1.5" }, {
+    const server = new McpServer({ name: "dexe-mcp", version: packageVersion() }, {
         instructions: "Tools for DeXe Protocol governance DAOs (plus a generic dexe_gov_* surface for external OpenZeppelin/Compound Governor DAOs). " +
             "Call dexe_context first WHEN you need orientation (signer, active chain, env readiness, DAOs/proposals from prior sessions) — skip it when the user already gave you the target DAO and chain. " +
-            "Prefer the composite flow tools over hand-sequencing calldata: dexe_dao_create (deploy a DAO), dexe_proposal_create (any proposal — pass proposalType + params), dexe_proposal_vote_and_execute. " +
+            "Prefer the composite flow tools over hand-sequencing calldata: dexe_dao_create (deploy a DAO), dexe_proposal_create (ANY of the 33 catalog proposal types — pass proposalType + params), dexe_proposal_vote_and_execute (auto-deposits when power is short). " +
+            "Amounts accept raw wei (digits-only) or human units with a decimal point ('12.5'); durations are seconds. " +
             "For images (DAO avatars): pass a LOCAL FILE PATH (avatarPath / newAvatarPath / filePath) and the server reads, validates, and pins it — never read image files or pass base64 through the conversation. " +
-            "They handle the approve→deposit→create sequence, correct IPFS metadata, and the known deploy/proposal reverts. When depositing, ERC20.approve the UserKeeper, never GovPool. Validate DAO deploys on BSC testnet (chain 97). " +
-            "Before any dexe_get_* / dexe_list_contracts / dexe_find_selector, run dexe_compile once per session. dexe_decode_proposal and dexe_read_gov_state need an RPC. " +
-            "The tool surface is gated by DEXE_TOOLSETS (default 'core,proposals'). Set DEXE_TOOLSETS=full for every tool, or add sets: read, vote, governor, dev. " +
+            "The composites handle approve→deposit→create sequencing, correct IPFS metadata, and the known deploy/proposal reverts; on partial failure they return the landed-steps ledger — fix the cause and re-run the same call (completed steps are skipped). " +
+            "When depositing, ERC20.approve the UserKeeper, never GovPool. Validate DAO deploys on BSC testnet (chain 97). " +
+            "Before any dexe_get_* / dexe_list_contracts / dexe_find_selector, run dexe_compile once per session. " +
+            "The tool surface is gated by DEXE_TOOLSETS (default 'core,proposals'); dexe_context reports which sets are off and what they unlock. " +
+            "Full intent→call recipes + error→remedy table: docs/PLAYBOOK.md (shipped in the package). " +
             "Recipe skills ship with the package (dexe-create-dao, dexe-create-proposal, dexe-vote-execute, dexe-otc). Installed automatically with the Claude Code plugin (`/plugin install dexe@dexe-mcp`), or copy them standalone with `npx dexe-mcp skills`.",
     });
     registerAll(server, config);
+    // The AI-efficiency guide, on demand (docs/PLAYBOOK.md ships in the package).
+    // Kept out of `instructions` so it doesn't cost tokens every session.
+    const playbookPath = resolve(__dirname, "..", "docs", "PLAYBOOK.md");
+    if (existsSync(playbookPath)) {
+        server.resource("playbook", "dexe://playbook", async () => ({
+            contents: [
+                {
+                    uri: "dexe://playbook",
+                    mimeType: "text/markdown",
+                    text: readFileSync(playbookPath, "utf8"),
+                },
+            ],
+        }));
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Log-only, not protocol. stdout is the MCP channel.

package/dist/index.js.map

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

package/dist/lib/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Actionable-error layer (v0.22). Every catch-all in the composite flows routes
+ * through `toActionableError` so the model/user gets "what happened + what to do
+ * next" instead of a raw ethers dump. The remedy table is exported so
+ * `npm run gen:playbook` can render it into docs/PLAYBOOK.md — one source.
+ */
+export interface KnownFailure {
+    /** Matched against the raw error message (case-insensitive). */
+    match: RegExp;
+    /** Stable slug used in PLAYBOOK's error→remedy table. */
+    slug: string;
+    /** One-sentence statement of what went wrong, in user terms. */
+    what: string;
+    /** Concrete next step ("do X"), tool names included. */
+    remedy: string;
+}
+/**
+ * Known failure signatures across the DeXe flows. Order matters — first match
+ * wins. Keep `what`/`remedy` self-contained: they are shown without the
+ * surrounding code context.
+ */
+export declare const KNOWN_FAILURES: readonly KnownFailure[];
+/** Result of classifying an unknown error against the KNOWN_FAILURES table. */
+export interface ActionableError {
+    message: string;
+    slug?: string;
+}
+/**
+ * Wrap a caught error with step context and, when the signature is recognized,
+ * a concrete remedy. Falls back to the redacted raw message so nothing is lost.
+ */
+export declare function toActionableError(err: unknown, step?: string): ActionableError;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EA+CxC,CAAC;AAEX,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CAS9E"}

package/dist/lib/errors.js

@@ -0,0 +1,65 @@
+import { safeErrorMessage } from "./redact.js";
+/**
+ * Known failure signatures across the DeXe flows. Order matters — first match
+ * wins. Keep `what`/`remedy` self-contained: they are shown without the
+ * surrounding code context.
+ */
+export const KNOWN_FAILURES = [
+    {
+        match: /insufficient funds for (gas|intrinsic)/i,
+        slug: "no-gas",
+        what: "The signer wallet has no BNB to pay gas.",
+        remedy: "Fund the signer address with BNB on the target chain (testnet 97: use a faucet, e.g. https://www.bnbchain.org/en/testnet-faucet), then re-run.",
+    },
+    {
+        match: /nonce (too low|has already been used)|already known|replacement transaction underpriced/i,
+        slug: "nonce-conflict",
+        what: "A transaction with this nonce is already pending or mined.",
+        remedy: "A previous broadcast is still settling. Wait ~15s, check it with dexe_tx_status, then re-run — the flow re-checks completed steps and skips them.",
+    },
+    {
+        match: /user rejected|user denied|rejected by user/i,
+        slug: "wallet-rejected",
+        what: "The transaction was rejected in the wallet.",
+        remedy: "Re-run the call and approve the request on the phone/wallet when it appears.",
+    },
+    {
+        match: /DEXE_PINATA_JWT/i,
+        slug: "pinata-missing",
+        what: "IPFS uploads need a Pinata JWT and none is configured.",
+        remedy: "1) Create a free API key at https://app.pinata.cloud/developers/api-keys with pinJSONToIPFS + pinFileToIPFS permissions. " +
+            "2) Add DEXE_PINATA_JWT=<jwt> to the .env at the dexe-mcp root (never .claude.json). " +
+            "3) Restart Claude Code (the .env is read once at startup). Or run /dexe-setup for a guided walkthrough.",
+    },
+    {
+        match: /rate.?limit|\b429\b|SERVER_ERROR|could not detect network|failed to fetch|fetch failed|ETIMEDOUT|ECONNRESET/i,
+        slug: "rpc-flaky",
+        what: "The RPC endpoint failed or rate-limited mid-call (retries were already attempted).",
+        remedy: "Re-run the call — completed steps are skipped. For reliability set a private endpoint in .env " +
+            "(DEXE_RPC_URL_MAINNET / DEXE_RPC_URL_TESTNET, e.g. Alchemy/QuickNode/Ankr) and restart.",
+    },
+    {
+        match: /execution reverted|CALL_EXCEPTION|transaction failed|status.*0\b/i,
+        slug: "onchain-revert",
+        what: "The transaction reverted on-chain (state was NOT changed by this step).",
+        remedy: "Read the revert reason above if present. Common causes: proposal not in the required state " +
+            "(check dexe_proposal_state), tokens locked in an active proposal (withdraw between proposals), " +
+            "or a blacklisted recipient. Fix the cause and re-run — earlier landed steps are skipped.",
+    },
+];
+/**
+ * Wrap a caught error with step context and, when the signature is recognized,
+ * a concrete remedy. Falls back to the redacted raw message so nothing is lost.
+ */
+export function toActionableError(err, step) {
+    const raw = safeErrorMessage(err);
+    const hit = KNOWN_FAILURES.find((k) => k.match.test(raw));
+    const prefix = step ? `${step} failed: ` : "";
+    if (!hit)
+        return { message: `${prefix}${raw}` };
+    return {
+        slug: hit.slug,
+        message: `${prefix}${raw}\n\n${hit.what}\nNext step: ${hit.remedy}`,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAoB/C;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAA4B;IACrD;QACE,KAAK,EAAE,yCAAyC;QAChD,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,0CAA0C;QAChD,MAAM,EACJ,gJAAgJ;KACnJ;IACD;QACE,KAAK,EAAE,0FAA0F;QACjG,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,4DAA4D;QAClE,MAAM,EACJ,mJAAmJ;KACtJ;IACD;QACE,KAAK,EAAE,6CAA6C;QACpD,IAAI,EAAE,iBAAiB;QACvB,IAAI,EAAE,6CAA6C;QACnD,MAAM,EAAE,8EAA8E;KACvF;IACD;QACE,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,wDAAwD;QAC9D,MAAM,EACJ,2HAA2H;YAC3H,sFAAsF;YACtF,yGAAyG;KAC5G;IACD;QACE,KAAK,EAAE,8GAA8G;QACrH,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,oFAAoF;QAC1F,MAAM,EACJ,gGAAgG;YAChG,yFAAyF;KAC5F;IACD;QACE,KAAK,EAAE,mEAAmE;QAC1E,IAAI,EAAE,gBAAgB;QACtB,IAAI,EAAE,yEAAyE;QAC/E,MAAM,EACJ,6FAA6F;YAC7F,iGAAiG;YACjG,0FAA0F;KAC7F;CACO,CAAC;AAQX;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,IAAa;IAC3D,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,GAAG,GAAG,EAAE,EAAE,CAAC;IAChD,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,OAAO,EAAE,GAAG,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,IAAI,gBAAgB,GAAG,CAAC,MAAM,EAAE;KACpE,CAAC;AACJ,CAAC"}

package/dist/lib/params.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+/**
+ * Shared `chainId` input param for every read tool. Optional — when omitted the
+ * MCP's default chain is used, so adding this to a tool is non-breaking.
+ * Write tools already carry their own copy with broadcast-specific wording.
+ */
+export declare const chainIdParam: z.ZodOptional<z.ZodNumber>;
+//# sourceMappingURL=params.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../../src/lib/params.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,YAAY,4BAQtB,CAAC"}

package/dist/lib/params.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+/**
+ * Shared `chainId` input param for every read tool. Optional — when omitted the
+ * MCP's default chain is used, so adding this to a tool is non-breaking.
+ * Write tools already carry their own copy with broadcast-specific wording.
+ */
+export const chainIdParam = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Chain id to read from (56 = BSC mainnet, 97 = BSC testnet). Defaults to the MCP's default chain. " +
+    "Rejects if no RPC is configured for the requested chain.");
+//# sourceMappingURL=params.js.map

package/dist/lib/params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.js","sourceRoot":"","sources":["../../src/lib/params.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC;KAC1B,MAAM,EAAE;KACR,GAAG,EAAE;KACL,QAAQ,EAAE;KACV,QAAQ,EAAE;KACV,QAAQ,CACP,mGAAmG;IACjG,0DAA0D,CAC7D,CAAC"}

package/dist/lib/proposalBuilders.d.ts

@@ -42,9 +42,37 @@ export interface CatalogBuilder {
 }
 /**
  * Registry keyed by the short `proposalType` accepted by `dexe_proposal_create`.
- * Extend this to wire another catalog type into the composite.
+ * Extend this to wire another catalog type into the composite. Aliases point at
+ * the same builder object (validators_allocation ≡ manage_validators;
+ * enable_staking ≡ new_proposal_type with StakingProposal among executors —
+ * matching the frontend, which reuses useGovPoolCreateProposalType).
  */
 export declare const PROPOSAL_BUILDERS: Record<string, CatalogBuilder>;
+export interface BuiltInternalProposal {
+    /** GovValidators internal type: 0 ChangeBalances, 1 ChangeSettings, 2 MonthlyWithdraw, 3 OffchainProposal. */
+    internalType: 0 | 1 | 2 | 3;
+    /** Selector + abi-encoded args for the internal executor method ("0x" for type 3). */
+    data: string;
+    category: string;
+    metadataExtra: Record<string, unknown>;
+    summary: string;
+}
+export interface InternalCatalogBuilder {
+    schema: z.ZodTypeAny;
+    build: (params: unknown) => BuiltInternalProposal;
+}
+/**
+ * Internal proposals do NOT go through GovPool.createProposalAndVote — they are
+ * created on GovValidators (validators-only voting, no deposit). The flow layer
+ * routes these to a single createInternalProposal payload.
+ */
+export declare const INTERNAL_PROPOSAL_BUILDERS: Record<string, InternalCatalogBuilder>;
+/**
+ * Off-chain proposal types live on the DeXe backend (api.dexe.io), not on any
+ * contract — `dexe_proposal_create` rejects them with the exact alternative
+ * flow instead of a dead-end.
+ */
+export declare const OFFCHAIN_FLOW_TYPES: readonly ["offchain_single_option", "offchain_multi_option", "offchain_for_against"];
 /** proposalType values `dexe_proposal_create` accepts directly. */
-export declare const FLOW_PROPOSAL_TYPES: readonly ["modify_dao_profile", "custom", ...string[]];
+export declare const FLOW_PROPOSAL_TYPES: readonly ["modify_dao_profile", "custom", ...string[], "offchain_single_option", "offchain_multi_option", "offchain_for_against"];
 //# sourceMappingURL=proposalBuilders.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"proposalBuilders.d.ts","sourceRoot":"","sources":["../../src/lib/proposalBuilders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAmCvD,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,YAAY,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnE,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,WAAW,CAAC;IACjB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;IACrB,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC9E;AAoPD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAS5D,CAAC;AAEF,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,wDAItB,CAAC"}
+{"version":3,"file":"proposalBuilders.d.ts","sourceRoot":"","sources":["../../src/lib/proposalBuilders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAiFvD,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,YAAY,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnE,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,WAAW,CAAC;IACjB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;IACrB,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC9E;AA0oBD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CA8B5D,CAAC;AAIF,MAAM,WAAW,qBAAqB;IACpC,8GAA8G;IAC9G,YAAY,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC;IACrB,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,qBAAqB,CAAC;CACnD;AAID;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAgF7E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,sFAItB,CAAC;AAEX,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,mIAMtB,CAAC"}