@agenttrust-sdk/mcp 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,233 @@
+# `@agenttrust-sdk/mcp`
+
+Model Context Protocol (MCP) server for AgentTrust. Drop the binary
+into Claude Desktop, Cursor, or any MCP client and interact with the
+deployed AgentTrust programs through natural language.
+
+> Reads devnet by default. Mainnet is one env var away once mainnet
+> deployment lands.
+
+## Tool inventory
+
+### Read (no signer required)
+
+| Tool | What it returns |
+|--|--|
+| `agenttrust_get_policy` | Decoded `PolicyAccount` PDA for `(agent_asset, policy_id)` — every spending cap, velocity threshold, counterparty tier requirement, and required capability hash. |
+| `agenttrust_list_policies` | All policies registered for an agent (lightweight summary; use `get_policy` for full decode). |
+| `agenttrust_simulate_payment` | Read-only `gate_payment` simulation. Returns `Allow`, `Deny(reasonCode)`, or `RequireValidation(capabilityHash)`. |
+| `agenttrust_get_killswitch` | `KillSwitchState` + `PolicyAuthority` for an agent. |
+| `agenttrust_get_velocity` | `VelocityLedger` for `(agent, policy_id)` — sliding-window cumulative spend. |
+| `agenttrust_get_feedback_log` | `FeedbackEmissionLog` by `payment_id_hash` (32-byte hex). |
+| `agenttrust_get_quantu_reputation` | Quantu `atom_stats` decoded — tier (0..3), feedback count, risk score, confidence. |
+| `agenttrust_get_validation_attestation` | Every `ValidationAttestation` for `(subject_asset, capability_hash)`. |
+| `agenttrust_list_facilitators` | Active facilitator adapters (Pay.sh / Dexter / atxp / MCPay) + ship status. |
+| `agenttrust_demo_state` | Three pre-warmed devnet counterparties used by `examples/pay-sh-demo`. |
+
+### Write (require `KEYPAIR_B58` env)
+
+| Tool | Effect |
+|--|--|
+| `agenttrust_init_policy` | Create `PolicyAccount` + `VelocityLedger` for the signer's agent. |
+| `agenttrust_set_killswitch` | Pause / unpause the agent's `KillSwitchState` (lead-only multisig in v1). |
+| `agenttrust_request_validation` | Open a `ValidationRequest` PDA. |
+| `agenttrust_respond_to_validation` | Attestor writes a `ValidationAttestation` PDA. |
+| `agenttrust_emit_feedback` | Facilitator-only `emit_feedback` CPI (signer must equal facilitator). |
+
+Every write tool surfaces the resulting `txSignature` + Solana Explorer URL
+in its response.
+
+### Discovery
+
+| Tool | What it does |
+|--|--|
+| `agenttrust_docs` | Full-text search the docs corpus at `docs-site/content/docs/`. Returns ranked hits with excerpts. |
+| `agenttrust_facilitator_walkthrough` | Per-adapter integration walkthrough by name. Falls back to the generic adapters guide for unknown names. |
+| `agenttrust_explain_decision` | Translate a `DenyReason` code (1..15) into the enum name + remediation hint. |
+
+### Resources
+
+| URI | MIME | Content |
+|--|--|--|
+| `agenttrust://devnet/programs` | `application/json` | Deployed program IDs + Explorer URLs for the active cluster. |
+| `agenttrust://docs/<rel-path>` | `text/markdown` | Each MDX page in the docs corpus exposed individually. |
+| `agenttrust://examples/pay-sh-demo/...` | `text/x-typescript` / `text/markdown` | Pay.sh demo source files. |
+| `agenttrust://examples/attestor-demo/...` | `text/x-typescript` / `text/markdown` | Attestor demo source files. |
+
+### Prompts (guided workflows)
+
+| Prompt | What it walks the user through |
+|--|--|
+| `agenttrust_audit_payment` | Simulate a payment, read the policy, read the payee's reputation, surface the decision. |
+| `agenttrust_setup_agent` | Bootstrap an agent's PolicyAuthority → KillSwitch → first PolicyAccount. |
+| `agenttrust_explain_failure` | Given a failed payment's reason code, explain root cause + remediation. |
+
+## Install
+
+### Claude Desktop
+
+Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json`
+on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "node",
+      "args": ["/absolute/path/to/agenttrust/mcp/dist/index.js"],
+      "env": {
+        "RPC_URL": "https://api.devnet.solana.com",
+        "NETWORK": "solana-devnet"
+      }
+    }
+  }
+}
+```
+
+Or run the helper:
+
+```bash
+mcp/scripts/install-claude-desktop.sh
+```
+
+The script edits the Claude Desktop config in place. It backs up the
+prior config to `claude_desktop_config.json.bak.<timestamp>` so you can
+revert if needed.
+
+For write tools, add `KEYPAIR_B58` to the `env` block:
+
+```json
+"env": {
+  "RPC_URL":     "https://api.devnet.solana.com",
+  "NETWORK":     "solana-devnet",
+  "KEYPAIR_B58": "<base58-encoded 64-byte secret key>"
+}
+```
+
+### Cursor
+
+Cursor's MCP config lives at `~/.cursor/mcp.json` (or per-workspace
+`.cursor/mcp.json`). Same shape as Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "agenttrust": {
+      "command": "node",
+      "args": ["/absolute/path/to/agenttrust/mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### Generic stdio MCP client
+
+The package ships a binary entry point. Once built:
+
+```bash
+pnpm --filter ./mcp run build
+node ./mcp/dist/index.js   # stdio transport, default
+```
+
+The server speaks MCP over stdin/stdout; any compliant MCP client
+attaches by spawning this command.
+
+### Hosted HTTP transport
+
+Set `MCP_TRANSPORT=http` and `MCP_HTTP_PORT=8765`:
+
+```bash
+MCP_TRANSPORT=http MCP_HTTP_PORT=8765 node ./mcp/dist/index.js
+```
+
+The server listens on `http://0.0.0.0:8765` using
+`StreamableHTTPServerTransport`. Behind a reverse proxy (Caddy, nginx,
+Vercel) this surfaces as a public hosted endpoint.
+
+> A hosted Vercel deployment URL is **not yet shipped**. The streamable-HTTP
+> transport surface is present and exercised in CI, but a public hosted
+> endpoint requires a Vercel project + DNS. Track this as a follow-up.
+
+## Environment
+
+| Var | Default | Effect |
+|--|--|--|
+| `RPC_URL` | devnet RPC | Solana RPC endpoint. |
+| `NETWORK` | `solana-devnet` | `solana-devnet` or `solana-mainnet`. Drives Quantu program IDs. |
+| `KEYPAIR_B58` | unset | Base58-encoded 64-byte secret key. Required for write tools. |
+| `MCP_TRANSPORT` | `stdio` | `stdio` or `http`. |
+| `MCP_HTTP_PORT` | `8765` | Port for HTTP transport. |
+| `POLICY_VAULT_PROGRAM_ID` | devnet ID | Override the policy_vault program ID. |
+| `TRUSTGATE_PROGRAM_ID` | devnet ID | Override the trustgate program ID. |
+| `VALIDATION_REGISTRY_PROGRAM_ID` | devnet ID | Override the validation_registry program ID. |
+| `MCP_DEFAULT_FACILITATOR` | unset | Default facilitator name surfaced in tool replies. |
+| `MCP_DOCS_DIR` | repo `docs-site/content/docs` | Override the docs corpus root (tests). |
+| `PAY_SH_DEMO_STATE_FILE` | `examples/pay-sh-demo/devnet-counterparties.json` | Override the demo state file. |
+
+## Example natural-language prompts
+
+Once installed, try these in Claude Desktop:
+
+- "Use AgentTrust to look up the three pre-warmed devnet counterparties."
+- "Simulate a 5-USDC payment from the tier-3 demo agent to the tier-0 demo agent against policy 1. What does the gate decide?"
+- "Pull the policy for agent &lt;asset&gt; ID 1 and tell me the spending caps."
+- "Why would a payment with reason code 6 fail, and how do I fix it?"
+- "Search the AgentTrust docs for the validation registry data flow."
+- "Walk me through adding a new x402 facilitator adapter."
+
+## IDL fetch
+
+All three Anchor IDLs are published on devnet. Re-verify any time with:
+
+```bash
+anchor idl fetch 8Y6fGeNEHgmWmbt8JsRcF72jxbeBfJhomMjG6SuoJQTR --provider.cluster devnet  # policy_vault
+anchor idl fetch HF8zHfoyA7b5mhLViopTnRMprc6ZT5KActHTdkFrih2N --provider.cluster devnet  # trustgate
+anchor idl fetch Cx4RFa6ysw3qXYhugPkF8pFSWBkmKq59h2dWgF2tKhtv --provider.cluster devnet  # validation_registry
+```
+
+The MCP server bundles snapshots at `src/idl/*.json` as a defensive
+fallback (saves an RPC round-trip on cold start; keeps the server bootable
+in offline / air-gapped harnesses). The latest evidence snapshot is in
+[`../docs/proofs/idl-on-chain.json`](../docs/proofs/idl-on-chain.json) —
+includes SHA256 hashes + instruction counts for each IDL.
+
+## Build + test
+
+```bash
+pnpm install
+pnpm --filter ./trustgate/sdk run build   # MCP depends on the SDK build output
+pnpm --filter ./mcp run build
+pnpm --filter ./mcp test                  # unit tests (no chain access)
+INTEGRATION=1 pnpm --filter ./mcp test:integration   # devnet round-trip
+```
+
+## Architecture
+
+```
+mcp/src/
+  index.ts        — entry point + transport selector
+  server.ts       — MCP Server with tools/resources/prompts wired up
+  config.ts       — env parsing
+  chain.ts        — thin façade over @agenttrust-sdk/trustgate
+  tools/
+    types.ts            — shared Tool<TInput, TOutput> shape
+    common.ts           — pubkey / hex helpers + Zod schemas
+    index.ts            — aggregates ALL_TOOLS
+    read/               — 10 read tools
+    write/              — 5 write tools
+    discovery/          — 3 discovery tools
+  resources/
+    docs.ts             — MDX corpus indexer + path-traversal-safe demo readers
+    programs.ts         — devnet program manifest as JSON resource
+  prompts/
+    types.ts            — shared Prompt shape
+    audit-payment.ts
+    setup-agent.ts
+    explain-failure.ts
+    index.ts            — aggregates ALL_PROMPTS
+```
+
+Chain logic — PDA derivation, IDL loading, `gate_payment` simulation —
+lives in `@agenttrust-sdk/trustgate`. The MCP server is a façade. If a
+helper is missing in the SDK, add it to the SDK and re-export — never
+fork the chain logic into `mcp/`.

package/dist/chain.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Thin façade over `@agenttrust-sdk/trustgate`. The MCP server's tools
+ * call into this module — never directly into Anchor or @solana/web3.js
+ * primitives — so the SDK stays the single source of truth for PDA
+ * derivation, IDL loading, and gate-payment simulation.
+ *
+ * If a helper is missing here, add it to the SDK and re-export. Don't
+ * fork chain logic.
+ */
+import * as anchor from "@coral-xyz/anchor";
+import { AnchorProvider, BN, Program } from "@coral-xyz/anchor";
+import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+import { GateDecision, ProgramIds, derivePolicyPda, deriveVelocityPda, deriveKillSwitchPda, deriveFeedbackLogPda, deriveTrustGateAuthorityPda, deriveAgentAccountPda, deriveAtomConfigPda, deriveAtomStatsPda, deriveAtomRegistryAuthorityPda, deriveQuantuFeedbackAccounts, simulateGatePayment, fetchValidationAttestation, fetchValidationRequest, fetchAttestorProfile, fetchCapabilityNamespace, computeCapabilityHash, computeNamespaceHash, deriveAttestorProfilePda, deriveCapabilityNamespacePda, deriveValidationAttestationPda, deriveValidationRequestPda, buildRegisterAttestorIx, buildRegisterNamespaceIx, buildRequestValidationIx, buildRespondToValidationIx, buildRevokeValidationIx, QuantuProgramIds } from "@agenttrust-sdk/trustgate";
+import { AgentTrustConfig } from "./config";
+export { derivePolicyPda, deriveVelocityPda, deriveKillSwitchPda, deriveFeedbackLogPda, deriveTrustGateAuthorityPda, deriveAgentAccountPda, deriveAtomConfigPda, deriveAtomStatsPda, deriveAtomRegistryAuthorityPda, deriveQuantuFeedbackAccounts, deriveAttestorProfilePda, deriveCapabilityNamespacePda, deriveValidationAttestationPda, deriveValidationRequestPda, computeCapabilityHash, computeNamespaceHash, fetchValidationAttestation, fetchValidationRequest, fetchAttestorProfile, fetchCapabilityNamespace, buildRegisterAttestorIx, buildRegisterNamespaceIx, buildRequestValidationIx, buildRespondToValidationIx, buildRevokeValidationIx, simulateGatePayment, GateDecision, ProgramIds, QuantuProgramIds, };
+/**
+ * Build an Anchor provider tied to `cfg.rpcUrl`. If a signer is configured
+ * the provider's wallet is the real signer; otherwise a throwaway keypair
+ * is used (sufficient for read-only simulation + RPC reads).
+ */
+export declare function makeProvider(cfg: AgentTrustConfig): AnchorProvider;
+/**
+ * Lazily-instantiated program clients. `loadPolicyVault` etc. each fetch
+ * the IDL on first call; subsequent calls reuse the cached `Program`.
+ */
+export declare class ChainClient {
+    readonly cfg: AgentTrustConfig;
+    readonly provider: AnchorProvider;
+    private _policyVault?;
+    private _trustgate?;
+    private _validationRegistry?;
+    constructor(cfg: AgentTrustConfig);
+    get connection(): Connection;
+    /** Public key of the configured signer, or null if no signer is set. */
+    signerPubkey(): PublicKey | null;
+    requireSigner(): Keypair;
+    policyVault(): Promise<Program>;
+    trustgate(): Promise<Program>;
+    validationRegistry(): Promise<Program>;
+}
+export { AnchorProvider, BN, Program, anchor };

package/dist/chain.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Thin façade over `@agenttrust-sdk/trustgate`. The MCP server's tools
+ * call into this module — never directly into Anchor or @solana/web3.js
+ * primitives — so the SDK stays the single source of truth for PDA
+ * derivation, IDL loading, and gate-payment simulation.
+ *
+ * If a helper is missing here, add it to the SDK and re-export. Don't
+ * fork chain logic.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anchor = exports.Program = exports.BN = exports.AnchorProvider = exports.ChainClient = exports.simulateGatePayment = exports.buildRevokeValidationIx = exports.buildRespondToValidationIx = exports.buildRequestValidationIx = exports.buildRegisterNamespaceIx = exports.buildRegisterAttestorIx = exports.fetchCapabilityNamespace = exports.fetchAttestorProfile = exports.fetchValidationRequest = exports.fetchValidationAttestation = exports.computeNamespaceHash = exports.computeCapabilityHash = exports.deriveValidationRequestPda = exports.deriveValidationAttestationPda = exports.deriveCapabilityNamespacePda = exports.deriveAttestorProfilePda = exports.deriveQuantuFeedbackAccounts = exports.deriveAtomRegistryAuthorityPda = exports.deriveAtomStatsPda = exports.deriveAtomConfigPda = exports.deriveAgentAccountPda = exports.deriveTrustGateAuthorityPda = exports.deriveFeedbackLogPda = exports.deriveKillSwitchPda = exports.deriveVelocityPda = exports.derivePolicyPda = void 0;
+exports.makeProvider = makeProvider;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+exports.anchor = anchor;
+const anchor_1 = require("@coral-xyz/anchor");
+Object.defineProperty(exports, "AnchorProvider", { enumerable: true, get: function () { return anchor_1.AnchorProvider; } });
+Object.defineProperty(exports, "BN", { enumerable: true, get: function () { return anchor_1.BN; } });
+Object.defineProperty(exports, "Program", { enumerable: true, get: function () { return anchor_1.Program; } });
+const web3_js_1 = require("@solana/web3.js");
+const trustgate_1 = require("@agenttrust-sdk/trustgate");
+Object.defineProperty(exports, "derivePolicyPda", { enumerable: true, get: function () { return trustgate_1.derivePolicyPda; } });
+Object.defineProperty(exports, "deriveVelocityPda", { enumerable: true, get: function () { return trustgate_1.deriveVelocityPda; } });
+Object.defineProperty(exports, "deriveKillSwitchPda", { enumerable: true, get: function () { return trustgate_1.deriveKillSwitchPda; } });
+Object.defineProperty(exports, "deriveFeedbackLogPda", { enumerable: true, get: function () { return trustgate_1.deriveFeedbackLogPda; } });
+Object.defineProperty(exports, "deriveTrustGateAuthorityPda", { enumerable: true, get: function () { return trustgate_1.deriveTrustGateAuthorityPda; } });
+Object.defineProperty(exports, "deriveAgentAccountPda", { enumerable: true, get: function () { return trustgate_1.deriveAgentAccountPda; } });
+Object.defineProperty(exports, "deriveAtomConfigPda", { enumerable: true, get: function () { return trustgate_1.deriveAtomConfigPda; } });
+Object.defineProperty(exports, "deriveAtomStatsPda", { enumerable: true, get: function () { return trustgate_1.deriveAtomStatsPda; } });
+Object.defineProperty(exports, "deriveAtomRegistryAuthorityPda", { enumerable: true, get: function () { return trustgate_1.deriveAtomRegistryAuthorityPda; } });
+Object.defineProperty(exports, "deriveQuantuFeedbackAccounts", { enumerable: true, get: function () { return trustgate_1.deriveQuantuFeedbackAccounts; } });
+Object.defineProperty(exports, "simulateGatePayment", { enumerable: true, get: function () { return trustgate_1.simulateGatePayment; } });
+Object.defineProperty(exports, "fetchValidationAttestation", { enumerable: true, get: function () { return trustgate_1.fetchValidationAttestation; } });
+Object.defineProperty(exports, "fetchValidationRequest", { enumerable: true, get: function () { return trustgate_1.fetchValidationRequest; } });
+Object.defineProperty(exports, "fetchAttestorProfile", { enumerable: true, get: function () { return trustgate_1.fetchAttestorProfile; } });
+Object.defineProperty(exports, "fetchCapabilityNamespace", { enumerable: true, get: function () { return trustgate_1.fetchCapabilityNamespace; } });
+Object.defineProperty(exports, "computeCapabilityHash", { enumerable: true, get: function () { return trustgate_1.computeCapabilityHash; } });
+Object.defineProperty(exports, "computeNamespaceHash", { enumerable: true, get: function () { return trustgate_1.computeNamespaceHash; } });
+Object.defineProperty(exports, "deriveAttestorProfilePda", { enumerable: true, get: function () { return trustgate_1.deriveAttestorProfilePda; } });
+Object.defineProperty(exports, "deriveCapabilityNamespacePda", { enumerable: true, get: function () { return trustgate_1.deriveCapabilityNamespacePda; } });
+Object.defineProperty(exports, "deriveValidationAttestationPda", { enumerable: true, get: function () { return trustgate_1.deriveValidationAttestationPda; } });
+Object.defineProperty(exports, "deriveValidationRequestPda", { enumerable: true, get: function () { return trustgate_1.deriveValidationRequestPda; } });
+Object.defineProperty(exports, "buildRegisterAttestorIx", { enumerable: true, get: function () { return trustgate_1.buildRegisterAttestorIx; } });
+Object.defineProperty(exports, "buildRegisterNamespaceIx", { enumerable: true, get: function () { return trustgate_1.buildRegisterNamespaceIx; } });
+Object.defineProperty(exports, "buildRequestValidationIx", { enumerable: true, get: function () { return trustgate_1.buildRequestValidationIx; } });
+Object.defineProperty(exports, "buildRespondToValidationIx", { enumerable: true, get: function () { return trustgate_1.buildRespondToValidationIx; } });
+Object.defineProperty(exports, "buildRevokeValidationIx", { enumerable: true, get: function () { return trustgate_1.buildRevokeValidationIx; } });
+// ---------------------------------------------------------------------------
+// Provider construction
+// ---------------------------------------------------------------------------
+/**
+ * Build an Anchor provider tied to `cfg.rpcUrl`. If a signer is configured
+ * the provider's wallet is the real signer; otherwise a throwaway keypair
+ * is used (sufficient for read-only simulation + RPC reads).
+ */
+function makeProvider(cfg) {
+    const conn = new web3_js_1.Connection(cfg.rpcUrl, "confirmed");
+    const wallet = new anchor_1.Wallet(cfg.signer ?? web3_js_1.Keypair.generate());
+    return new anchor_1.AnchorProvider(conn, wallet, { commitment: "confirmed" });
+}
+/**
+ * Lazily-instantiated program clients. `loadPolicyVault` etc. each fetch
+ * the IDL on first call; subsequent calls reuse the cached `Program`.
+ */
+class ChainClient {
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.provider = makeProvider(cfg);
+    }
+    get connection() {
+        return this.provider.connection;
+    }
+    /** Public key of the configured signer, or null if no signer is set. */
+    signerPubkey() {
+        return this.cfg.signer ? this.cfg.signer.publicKey : null;
+    }
+    requireSigner() {
+        if (!this.cfg.signer) {
+            throw new Error("This tool requires KEYPAIR_B58 in the environment. " +
+                "Set it to a base58-encoded 64-byte secret key, then restart the MCP server.");
+        }
+        return this.cfg.signer;
+    }
+    async policyVault() {
+        if (!this._policyVault) {
+            this._policyVault = await (0, trustgate_1.loadPolicyVault)(this.provider, this.cfg.programs.policyVault, BUNDLED_IDLS.policyVault);
+        }
+        return this._policyVault;
+    }
+    async trustgate() {
+        if (!this._trustgate) {
+            this._trustgate = await (0, trustgate_1.loadTrustGate)(this.provider, this.cfg.programs.trustgate, BUNDLED_IDLS.trustgate);
+        }
+        return this._trustgate;
+    }
+    async validationRegistry() {
+        if (!this._validationRegistry) {
+            this._validationRegistry = await (0, trustgate_1.loadValidationRegistry)(this.provider, this.cfg.validationRegistryId, BUNDLED_IDLS.validationRegistry);
+        }
+        return this._validationRegistry;
+    }
+}
+exports.ChainClient = ChainClient;
+// ---------------------------------------------------------------------------
+// Bundled IDLs — defensive fallback. All three IDLs ARE published on
+// devnet (verified via `anchor idl fetch <programId> --provider.cluster
+// devnet`; see docs/proofs/idl-on-chain.json for the latest evidence
+// snapshot), but bundling them statically:
+//   • saves an RPC round-trip on every cold start
+//   • keeps the MCP server bootable in offline / air-gapped harnesses
+//   • survives the rare window after a fresh redeploy when `anchor idl
+//     upgrade` hasn't yet been run
+// The JSON files are committed under src/idl/ as snapshots of target/idl
+// at the time of the latest deploy. The build step copies them into
+// dist/idl/ so the runtime require() resolves post-install.
+// ---------------------------------------------------------------------------
+// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+const policyVaultIdl = require("./idl/policy_vault.json");
+// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+const trustgateIdl = require("./idl/trustgate.json");
+// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+const validationRegistryIdl = require("./idl/validation_registry.json");
+const BUNDLED_IDLS = {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    policyVault: policyVaultIdl,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    trustgate: trustgateIdl,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    validationRegistry: validationRegistryIdl,
+};
+//# sourceMappingURL=chain.js.map

package/dist/chain.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Env parsing for the AgentTrust MCP server.
+ *
+ * Read tools work without any env. Write tools require `KEYPAIR_B58`.
+ * The HTTP transport requires `MCP_HTTP_PORT` (else stdio is the default).
+ *
+ * Defaults are biased toward the local-developer / Claude Desktop case:
+ * devnet RPC, devnet program IDs, no signer required.
+ */
+import { Keypair, PublicKey } from "@solana/web3.js";
+import { ProgramIds, QuantuProgramIds } from "@agenttrust-sdk/trustgate";
+export type Network = "solana-devnet" | "solana-mainnet";
+export interface AgentTrustConfig {
+    readonly network: Network;
+    readonly rpcUrl: string;
+    readonly explorerCluster: "devnet" | "mainnet";
+    readonly programs: ProgramIds;
+    readonly validationRegistryId: PublicKey;
+    readonly quantu: QuantuProgramIds;
+    /** Optional signer keypair. Loaded from KEYPAIR_B58. Write tools require this. */
+    readonly signer?: Keypair;
+    /** Transport selection. */
+    readonly transport: "stdio" | "http";
+    /** HTTP transport port (only used when transport === "http"). */
+    readonly httpPort: number;
+    /** Optional default facilitator name to surface in tool replies. */
+    readonly defaultFacilitator?: string;
+}
+export declare function loadConfig(): AgentTrustConfig;
+/**
+ * Build a Solana Explorer URL for a tx signature or account, scoped to
+ * the active cluster. Devnet uses `?cluster=devnet`, mainnet has no
+ * suffix.
+ */
+export declare function explorerUrl(cfg: AgentTrustConfig, kind: "tx" | "address", value: string): string;

package/dist/config.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Env parsing for the AgentTrust MCP server.
+ *
+ * Read tools work without any env. Write tools require `KEYPAIR_B58`.
+ * The HTTP transport requires `MCP_HTTP_PORT` (else stdio is the default).
+ *
+ * Defaults are biased toward the local-developer / Claude Desktop case:
+ * devnet RPC, devnet program IDs, no signer required.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.explorerUrl = explorerUrl;
+const web3_js_1 = require("@solana/web3.js");
+const bs58_1 = __importDefault(require("bs58"));
+const trustgate_1 = require("@agenttrust-sdk/trustgate");
+const DEVNET_RPC = "https://api.devnet.solana.com";
+const MAINNET_RPC = "https://api.mainnet-beta.solana.com";
+function readNetwork() {
+    const raw = (process.env.NETWORK ?? "solana-devnet").trim().toLowerCase();
+    if (raw === "solana-mainnet" || raw === "mainnet" || raw === "mainnet-beta") {
+        return "solana-mainnet";
+    }
+    return "solana-devnet";
+}
+function readSigner() {
+    const raw = process.env.KEYPAIR_B58?.trim();
+    if (!raw)
+        return undefined;
+    try {
+        const bytes = bs58_1.default.decode(raw);
+        return web3_js_1.Keypair.fromSecretKey(bytes);
+    }
+    catch (err) {
+        throw new Error(`KEYPAIR_B58 is set but failed to decode: ${err.message}. ` +
+            `Expected base58-encoded 64-byte secret key.`);
+    }
+}
+function readTransport() {
+    const raw = (process.env.MCP_TRANSPORT ?? "stdio").trim().toLowerCase();
+    const port = Number.parseInt(process.env.MCP_HTTP_PORT ?? "8765", 10);
+    if (raw === "http" || raw === "sse")
+        return { transport: "http", httpPort: port };
+    return { transport: "stdio", httpPort: port };
+}
+function loadConfig() {
+    const network = readNetwork();
+    const rpcUrl = (process.env.RPC_URL ?? (network === "solana-mainnet" ? MAINNET_RPC : DEVNET_RPC)).trim();
+    const { transport, httpPort } = readTransport();
+    // Devnet ships fully-deployed AgentTrust + Quantu. Mainnet ships
+    // Quantu only (per CLAUDE.md). When mainnet is selected the AgentTrust
+    // program IDs default to devnet placeholders — overridable via env once
+    // mainnet deployment lands.
+    const programs = {
+        policyVault: parsePubkeyEnv("POLICY_VAULT_PROGRAM_ID", trustgate_1.DEFAULT_DEVNET_PROGRAM_IDS.policyVault),
+        trustgate: parsePubkeyEnv("TRUSTGATE_PROGRAM_ID", trustgate_1.DEFAULT_DEVNET_PROGRAM_IDS.trustgate),
+    };
+    const quantu = network === "solana-mainnet"
+        ? trustgate_1.MAINNET_QUANTU_IDS
+        : trustgate_1.DEFAULT_DEVNET_QUANTU_IDS;
+    const validationRegistryId = parsePubkeyEnv("VALIDATION_REGISTRY_PROGRAM_ID", trustgate_1.VALIDATION_REGISTRY_DEVNET_ID);
+    return {
+        network,
+        rpcUrl,
+        explorerCluster: network === "solana-mainnet" ? "mainnet" : "devnet",
+        programs,
+        validationRegistryId,
+        quantu,
+        signer: readSigner(),
+        transport,
+        httpPort,
+        defaultFacilitator: process.env.MCP_DEFAULT_FACILITATOR?.trim() || undefined,
+    };
+}
+function parsePubkeyEnv(name, fallback) {
+    const raw = process.env[name]?.trim();
+    if (!raw)
+        return fallback;
+    try {
+        return new web3_js_1.PublicKey(raw);
+    }
+    catch (err) {
+        throw new Error(`${name} is not a valid base58 pubkey: ${err.message}`);
+    }
+}
+/**
+ * Build a Solana Explorer URL for a tx signature or account, scoped to
+ * the active cluster. Devnet uses `?cluster=devnet`, mainnet has no
+ * suffix.
+ */
+function explorerUrl(cfg, kind, value) {
+    const path = kind === "tx" ? `tx/${value}` : `address/${value}`;
+    const suffix = cfg.explorerCluster === "devnet" ? "?cluster=devnet" : "";
+    return `https://explorer.solana.com/${path}${suffix}`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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