@agenttrust-sdk/mcp 0.1.0

package/dist/resources/programs.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * `agenttrust://devnet/programs` — JSON resource enumerating every
+ * deployed program ID + the URL clients can use to fetch the IDL.
+ *
+ * Anchor publishes IDLs per-program-per-network; the canonical fetch
+ * is `Program.fetchIdl(programId, provider)`. We surface the program
+ * IDs + a deep-link to Solana Explorer's "Anchor IDL" view as the
+ * easiest external pointer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROGRAMS_RESOURCE_URI = void 0;
+exports.describeProgramsResource = describeProgramsResource;
+exports.readProgramsResource = readProgramsResource;
+const config_1 = require("../config");
+exports.PROGRAMS_RESOURCE_URI = "agenttrust://devnet/programs";
+function describeProgramsResource() {
+    return {
+        uri: exports.PROGRAMS_RESOURCE_URI,
+        name: "Deployed program IDs",
+        description: "JSON manifest of AgentTrust + Quantu program IDs and Explorer URLs for the active cluster.",
+        mimeType: "application/json",
+    };
+}
+function readProgramsResource(cfg) {
+    const payload = {
+        network: cfg.network,
+        rpcUrl: cfg.rpcUrl,
+        explorerCluster: cfg.explorerCluster,
+        programs: {
+            policyVault: {
+                programId: cfg.programs.policyVault.toBase58(),
+                explorerUrl: (0, config_1.explorerUrl)(cfg, "address", cfg.programs.policyVault.toBase58()),
+            },
+            trustgate: {
+                programId: cfg.programs.trustgate.toBase58(),
+                explorerUrl: (0, config_1.explorerUrl)(cfg, "address", cfg.programs.trustgate.toBase58()),
+            },
+            validationRegistry: {
+                programId: cfg.validationRegistryId.toBase58(),
+                explorerUrl: (0, config_1.explorerUrl)(cfg, "address", cfg.validationRegistryId.toBase58()),
+            },
+        },
+        quantu: {
+            agentRegistry: {
+                programId: cfg.quantu.agentRegistry.toBase58(),
+                explorerUrl: (0, config_1.explorerUrl)(cfg, "address", cfg.quantu.agentRegistry.toBase58()),
+            },
+            atomEngine: {
+                programId: cfg.quantu.atomEngine.toBase58(),
+                explorerUrl: (0, config_1.explorerUrl)(cfg, "address", cfg.quantu.atomEngine.toBase58()),
+            },
+        },
+        notes: "All three Anchor IDLs are published on devnet (verify with " +
+            "`anchor idl fetch <programId> --provider.cluster devnet`; latest " +
+            "evidence in docs/proofs/idl-on-chain.json). The MCP server bundles " +
+            "snapshots under mcp/src/idl/ as a defensive fallback (saves an RPC " +
+            "round-trip on cold start; lets the server boot in offline harnesses). " +
+            "SDK consumers can reach the IDLs the same two ways via " +
+            "loadPolicyVault / loadTrustGate / loadValidationRegistry — pass an " +
+            "`idl` arg to use the bundled snapshot, omit it to fetch from chain.",
+    };
+    return {
+        uri: exports.PROGRAMS_RESOURCE_URI,
+        mimeType: "application/json",
+        text: JSON.stringify(payload, null, 2),
+    };
+}
+//# sourceMappingURL=programs.js.map

package/dist/resources/programs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"programs.js","sourceRoot":"","sources":["../../src/resources/programs.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAOH,4DAOC;AAED,oDA4CC;AA1DD,sCAA0D;AAG7C,QAAA,qBAAqB,GAAG,8BAA8B,CAAC;AAEpE,SAAgB,wBAAwB;IACtC,OAAO;QACL,GAAG,EAAU,6BAAqB;QAClC,IAAI,EAAS,sBAAsB;QACnC,WAAW,EAAE,4FAA4F;QACzG,QAAQ,EAAK,kBAAkB;KAChC,CAAC;AACJ,CAAC;AAED,SAAgB,oBAAoB,CAAC,GAAqB;IACxD,MAAM,OAAO,GAAG;QACd,OAAO,EAAiB,GAAG,CAAC,OAAO;QACnC,MAAM,EAAkB,GAAG,CAAC,MAAM;QAClC,eAAe,EAAS,GAAG,CAAC,eAAe;QAC3C,QAAQ,EAAE;YACR,WAAW,EAAE;gBACX,SAAS,EAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE;gBAChD,WAAW,EAAE,IAAA,oBAAW,EAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAC;aAC9E;YACD,SAAS,EAAE;gBACT,SAAS,EAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE;gBAC9C,WAAW,EAAE,IAAA,oBAAW,EAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;aAC5E;YACD,kBAAkB,EAAE;gBAClB,SAAS,EAAI,GAAG,CAAC,oBAAoB,CAAC,QAAQ,EAAE;gBAChD,WAAW,EAAE,IAAA,oBAAW,EAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,oBAAoB,CAAC,QAAQ,EAAE,CAAC;aAC9E;SACF;QACD,MAAM,EAAE;YACN,aAAa,EAAE;gBACb,SAAS,EAAI,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE;gBAChD,WAAW,EAAE,IAAA,oBAAW,EAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC;aAC9E;YACD,UAAU,EAAE;gBACV,SAAS,EAAI,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE;gBAC7C,WAAW,EAAE,IAAA,oBAAW,EAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;aAC3E;SACF;QACD,KAAK,EACH,6DAA6D;YAC7D,mEAAmE;YACnE,qEAAqE;YACrE,qEAAqE;YACrE,wEAAwE;YACxE,yDAAyD;YACzD,qEAAqE;YACrE,qEAAqE;KACxE,CAAC;IACF,OAAO;QACL,GAAG,EAAO,6BAAqB;QAC/B,QAAQ,EAAE,kBAAkB;QAC5B,IAAI,EAAM,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,19 @@
+/**
+ * MCP server registration. Wires every tool / resource / prompt onto a
+ * single `Server` instance and returns it so transports can connect.
+ *
+ * Tool dispatch flow:
+ *   1. tools/list → ALL_TOOLS metadata
+ *   2. tools/call → look up by name, parse input via Zod, run handler,
+ *      wrap output as a single text content block (JSON-encoded).
+ *
+ * Resources are split into two URI schemes:
+ *   - agenttrust://docs/<rel-path>     → MDX content
+ *   - agenttrust://devnet/programs     → JSON program manifest
+ *   - agenttrust://examples/<demo>/... → demo source files
+ *
+ * Prompts surface the three guided workflows from prompts/ALL_PROMPTS.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { AgentTrustConfig } from "./config";
+export declare function createMcpServer(cfg: AgentTrustConfig): Server;

package/dist/server.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * MCP server registration. Wires every tool / resource / prompt onto a
+ * single `Server` instance and returns it so transports can connect.
+ *
+ * Tool dispatch flow:
+ *   1. tools/list → ALL_TOOLS metadata
+ *   2. tools/call → look up by name, parse input via Zod, run handler,
+ *      wrap output as a single text content block (JSON-encoded).
+ *
+ * Resources are split into two URI schemes:
+ *   - agenttrust://docs/<rel-path>     → MDX content
+ *   - agenttrust://devnet/programs     → JSON program manifest
+ *   - agenttrust://examples/<demo>/... → demo source files
+ *
+ * Prompts surface the three guided workflows from prompts/ALL_PROMPTS.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMcpServer = createMcpServer;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const chain_1 = require("./chain");
+const prompts_1 = require("./prompts");
+const programs_1 = require("./resources/programs");
+const docs_1 = require("./resources/docs");
+const tools_1 = require("./tools");
+const SERVER_NAME = "agenttrust";
+const SERVER_VERSION = "0.1.0";
+const SERVER_INSTRUCTIONS = "AgentTrust MCP server. Read tools work without auth (devnet by default). " +
+    "Write tools require KEYPAIR_B58 in env. Resources expose the AgentTrust " +
+    "docs corpus, deployed program manifest, and example demo source. Prompts " +
+    "ship three guided workflows: audit_payment, setup_agent, explain_failure.";
+function createMcpServer(cfg) {
+    const chain = new chain_1.ChainClient(cfg);
+    const server = new index_js_1.Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    // ---- tools/list ---------------------------------------------------------
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools: tools_1.ALL_TOOLS.map((t) => ({
+            name: t.name,
+            description: t.description,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(t.inputSchema, { target: "openApi3" }),
+        })),
+    }));
+    // ---- tools/call ---------------------------------------------------------
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+        const tool = tools_1.ALL_TOOLS.find((t) => t.name === req.params.name);
+        if (!tool) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `unknown tool: ${req.params.name}` }],
+            };
+        }
+        let parsed;
+        try {
+            parsed = tool.inputSchema.parse(req.params.arguments ?? {});
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `input validation failed: ${err.message}` }],
+            };
+        }
+        try {
+            const result = await tool.handler(parsed, { chain });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `tool error: ${err.message}` }],
+            };
+        }
+    });
+    // ---- resources/list ----------------------------------------------------
+    server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => ({
+        resources: [
+            (0, programs_1.describeProgramsResource)(),
+            ...(0, docs_1.listDocsResources)(),
+            ...(0, docs_1.listExampleResources)(),
+        ],
+    }));
+    // ---- resources/read ----------------------------------------------------
+    server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (req) => {
+        const uri = req.params.uri;
+        if (uri === programs_1.PROGRAMS_RESOURCE_URI) {
+            const r = (0, programs_1.readProgramsResource)(cfg);
+            return { contents: [r] };
+        }
+        const docs = (0, docs_1.readDocsResource)(uri);
+        if (docs)
+            return { contents: [docs] };
+        const ex = (0, docs_1.readExampleResource)(uri);
+        if (ex)
+            return { contents: [ex] };
+        throw new Error(`unknown resource URI: ${uri}`);
+    });
+    // ---- prompts/list ------------------------------------------------------
+    server.setRequestHandler(types_js_1.ListPromptsRequestSchema, async () => ({
+        prompts: prompts_1.ALL_PROMPTS.map((p) => ({
+            name: p.name,
+            description: p.description,
+            arguments: p.arguments.map((a) => ({
+                name: a.name,
+                description: a.description,
+                required: a.required,
+            })),
+        })),
+    }));
+    // ---- prompts/get -------------------------------------------------------
+    server.setRequestHandler(types_js_1.GetPromptRequestSchema, async (req) => {
+        const prompt = prompts_1.ALL_PROMPTS.find((p) => p.name === req.params.name);
+        if (!prompt)
+            throw new Error(`unknown prompt: ${req.params.name}`);
+        const argMap = (req.params.arguments ?? {});
+        // Required-arg guard so prompt build() can stay declarative.
+        for (const a of prompt.arguments) {
+            if (a.required && !argMap[a.name]) {
+                throw new Error(`prompt ${prompt.name} missing required argument: ${a.name}`);
+            }
+        }
+        const messages = prompt.build(argMap);
+        return {
+            description: prompt.description,
+            messages,
+        };
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/tools/common.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Cross-tool helpers: pubkey parsing, BN serialization, hex conversion.
+ *
+ * Tools serialise PublicKey → base58 string and BN/bigint → string in
+ * tool replies, since most MCP clients render JSON via `JSON.stringify`
+ * which would crash on a BigInt or yield `[object Object]` on a PublicKey.
+ */
+import { PublicKey } from "@solana/web3.js";
+import { z } from "zod";
+export declare const PubkeySchema: z.ZodEffects<z.ZodString, string, string>;
+export declare function parsePubkey(s: string, field: string): PublicKey;
+export declare function bytesToHex(bytes: Uint8Array | Buffer | number[]): string;
+export declare function hexToBytes(s: string): Uint8Array;
+export declare const HexHashSchema: z.ZodEffects<z.ZodString, string, string>;
+/** Convert any `BN`-like or bigint into a decimal string. */
+export declare function toDecString(v: unknown): string;
+/** Convert a decoded Anchor account's potential `Pubkey` field to base58. */
+export declare function pubkeyOrNull(v: unknown): string | null;

package/dist/tools/common.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Cross-tool helpers: pubkey parsing, BN serialization, hex conversion.
+ *
+ * Tools serialise PublicKey → base58 string and BN/bigint → string in
+ * tool replies, since most MCP clients render JSON via `JSON.stringify`
+ * which would crash on a BigInt or yield `[object Object]` on a PublicKey.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HexHashSchema = exports.PubkeySchema = void 0;
+exports.parsePubkey = parsePubkey;
+exports.bytesToHex = bytesToHex;
+exports.hexToBytes = hexToBytes;
+exports.toDecString = toDecString;
+exports.pubkeyOrNull = pubkeyOrNull;
+const web3_js_1 = require("@solana/web3.js");
+const zod_1 = require("zod");
+exports.PubkeySchema = zod_1.z.string().refine((s) => {
+    try {
+        new web3_js_1.PublicKey(s);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, { message: "must be a base58-encoded Solana public key" });
+function parsePubkey(s, field) {
+    try {
+        return new web3_js_1.PublicKey(s);
+    }
+    catch (err) {
+        throw new Error(`${field}: ${err.message}`);
+    }
+}
+function bytesToHex(bytes) {
+    const b = Buffer.from(bytes);
+    return b.toString("hex");
+}
+function hexToBytes(s) {
+    const clean = s.startsWith("0x") ? s.slice(2) : s;
+    if (!/^[0-9a-fA-F]*$/.test(clean) || clean.length % 2 !== 0) {
+        throw new Error(`invalid hex string: ${s}`);
+    }
+    return new Uint8Array(Buffer.from(clean, "hex"));
+}
+exports.HexHashSchema = zod_1.z.string().refine((s) => {
+    const clean = s.startsWith("0x") ? s.slice(2) : s;
+    return /^[0-9a-fA-F]{64}$/.test(clean);
+}, { message: "must be a 32-byte hex string (64 hex chars, optional 0x prefix)" });
+/** Convert any `BN`-like or bigint into a decimal string. */
+function toDecString(v) {
+    if (v == null)
+        return "0";
+    if (typeof v === "bigint")
+        return v.toString();
+    if (typeof v === "number")
+        return v.toString();
+    if (typeof v === "string")
+        return v;
+    // @coral-xyz/anchor BN
+    if (typeof v.toString === "function") {
+        return v.toString(10);
+    }
+    return String(v);
+}
+/** Convert a decoded Anchor account's potential `Pubkey` field to base58. */
+function pubkeyOrNull(v) {
+    if (!v)
+        return null;
+    if (v instanceof web3_js_1.PublicKey)
+        return v.toBase58();
+    if (typeof v.toBase58 === "function") {
+        return v.toBase58();
+    }
+    return null;
+}
+//# sourceMappingURL=common.js.map

package/dist/tools/common.js.map

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

package/dist/tools/discovery/docs.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `agenttrust_docs` — naïve full-text search over the MDX corpus at
+ * `docs-site/content/docs/`. Returns the top 5 ranked snippets.
+ *
+ * Indexer: walks the docs corpus once on first call, caches the
+ * resulting `DocPage[]`. Each page is parsed for title/description
+ * frontmatter + raw body. Ranking: term-frequency over the body, with
+ * a 5x bonus for matches in title or description.
+ *
+ * The MCP server runs in-process so the cache survives across tool
+ * calls. A `MCP_DOCS_DIR` env override exists for tests.
+ */
+import { z } from "zod";
+import type { Tool } from "../types";
+interface DocPage {
+    uri: string;
+    filePath: string;
+    title: string;
+    description: string;
+    body: string;
+    bodyLower: string;
+}
+declare const InputSchema: z.ZodObject<{
+    query: z.ZodString;
+    max_results: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    max_results: number;
+}, {
+    query: string;
+    max_results?: number | undefined;
+}>;
+type Input = z.infer<typeof InputSchema>;
+interface Hit {
+    uri: string;
+    title: string;
+    description: string;
+    score: number;
+    excerpt: string;
+}
+interface Output {
+    query: string;
+    hits: Hit[];
+}
+export declare function findDocsRoot(): string | null;
+export declare function loadDocsCorpus(force?: boolean): DocPage[];
+export declare const docsTool: Tool<Input, Output>;
+export {};

package/dist/tools/discovery/docs.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * `agenttrust_docs` — naïve full-text search over the MDX corpus at
+ * `docs-site/content/docs/`. Returns the top 5 ranked snippets.
+ *
+ * Indexer: walks the docs corpus once on first call, caches the
+ * resulting `DocPage[]`. Each page is parsed for title/description
+ * frontmatter + raw body. Ranking: term-frequency over the body, with
+ * a 5x bonus for matches in title or description.
+ *
+ * The MCP server runs in-process so the cache survives across tool
+ * calls. A `MCP_DOCS_DIR` env override exists for tests.
+ */
+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.docsTool = void 0;
+exports.findDocsRoot = findDocsRoot;
+exports.loadDocsCorpus = loadDocsCorpus;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const zod_1 = require("zod");
+const InputSchema = zod_1.z.object({
+    query: zod_1.z.string().min(2).describe("Free-text query (case-insensitive)"),
+    max_results: zod_1.z.number().int().min(1).max(20).default(5),
+});
+let cache = null;
+function findDocsRoot() {
+    const candidates = [
+        process.env.MCP_DOCS_DIR ?? "",
+        path.resolve(__dirname, "../../../../docs-site/content/docs"),
+        path.resolve(process.cwd(), "docs-site/content/docs"),
+    ].filter(Boolean);
+    for (const c of candidates) {
+        try {
+            if (c && fs.statSync(c).isDirectory())
+                return c;
+        }
+        catch { /* ignore */ }
+    }
+    return null;
+}
+function loadDocsCorpus(force = false) {
+    if (cache && !force)
+        return cache;
+    const root = findDocsRoot();
+    if (!root) {
+        cache = [];
+        return cache;
+    }
+    const pages = [];
+    walk(root, "", pages, root);
+    cache = pages;
+    return pages;
+}
+function walk(dir, rel, pages, root) {
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+        const abs = path.join(dir, ent.name);
+        const cur = rel ? path.join(rel, ent.name) : ent.name;
+        if (ent.isDirectory()) {
+            walk(abs, cur, pages, root);
+        }
+        else if (ent.isFile() && ent.name.endsWith(".mdx")) {
+            const raw = fs.readFileSync(abs, "utf-8");
+            const meta = parseFrontmatter(raw);
+            const body = stripFrontmatter(raw);
+            const uri = "agenttrust://docs/" + cur.replace(/\.mdx$/, "").replace(/\\/g, "/");
+            pages.push({
+                uri,
+                filePath: abs,
+                title: meta.title ?? cur,
+                description: meta.description ?? "",
+                body,
+                bodyLower: body.toLowerCase(),
+            });
+        }
+    }
+}
+function parseFrontmatter(raw) {
+    if (!raw.startsWith("---\n"))
+        return {};
+    const end = raw.indexOf("\n---\n", 4);
+    if (end < 0)
+        return {};
+    const block = raw.slice(4, end);
+    const out = {};
+    for (const line of block.split("\n")) {
+        const m = /^([A-Za-z_]+):\s*(.+?)\s*$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1].toLowerCase();
+        let val = m[2];
+        if ((val.startsWith("\"") && val.endsWith("\"")) || (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+        }
+        if (key === "title")
+            out.title = val;
+        if (key === "description")
+            out.description = val;
+    }
+    return out;
+}
+function stripFrontmatter(raw) {
+    if (!raw.startsWith("---\n"))
+        return raw;
+    const end = raw.indexOf("\n---\n", 4);
+    if (end < 0)
+        return raw;
+    return raw.slice(end + 5);
+}
+function score(query, page) {
+    const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0)
+        return { score: 0, excerpt: "" };
+    let s = 0;
+    let firstHitIdx = -1;
+    for (const t of terms) {
+        const titleHit = page.title.toLowerCase().includes(t) ? 5 : 0;
+        const descHit = page.description.toLowerCase().includes(t) ? 5 : 0;
+        let bodyHits = 0;
+        let from = 0;
+        while (true) {
+            const idx = page.bodyLower.indexOf(t, from);
+            if (idx < 0)
+                break;
+            bodyHits++;
+            if (firstHitIdx < 0)
+                firstHitIdx = idx;
+            from = idx + t.length;
+        }
+        s += titleHit + descHit + bodyHits;
+    }
+    const excerptStart = Math.max(0, firstHitIdx - 80);
+    const excerptEnd = Math.min(page.body.length, (firstHitIdx < 0 ? 0 : firstHitIdx) + 240);
+    const excerpt = firstHitIdx >= 0
+        ? page.body.slice(excerptStart, excerptEnd).replace(/\n+/g, " ").trim()
+        : (page.description || page.body.slice(0, 240).replace(/\n+/g, " ").trim());
+    return { score: s, excerpt };
+}
+exports.docsTool = {
+    name: "agenttrust_docs",
+    description: "Full-text search the AgentTrust docs corpus (docs-site/content/docs). " +
+        "Returns up to N ranked hits with title, agenttrust:// URI, score, and " +
+        "an excerpt around the first match. Use the URI in resources/read for " +
+        "the full doc.",
+    inputSchema: InputSchema,
+    async handler(input) {
+        const corpus = loadDocsCorpus();
+        if (corpus.length === 0) {
+            return { query: input.query, hits: [] };
+        }
+        const ranked = [];
+        for (const page of corpus) {
+            const r = score(input.query, page);
+            if (r.score > 0) {
+                ranked.push({
+                    uri: page.uri,
+                    title: page.title,
+                    description: page.description,
+                    score: r.score,
+                    excerpt: r.excerpt,
+                });
+            }
+        }
+        ranked.sort((a, b) => b.score - a.score);
+        return { query: input.query, hits: ranked.slice(0, input.max_results) };
+    },
+};
+//# sourceMappingURL=docs.js.map

package/dist/tools/discovery/docs.js.map

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

package/dist/tools/discovery/explain-decision.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `agenttrust_explain_decision` — translate a numeric reason code into
+ * its enum name plus a one-paragraph remediation hint.
+ *
+ * Authoritative mapping comes from the SDK's `denyReasonName` (which
+ * mirrors `programs/policy-vault/src/state/decision.rs`). The hints
+ * here are MCP-specific guidance text — they describe what a developer
+ * or operator should do next when they see the code.
+ */
+import { z } from "zod";
+import type { Tool } from "../types";
+declare const InputSchema: z.ZodObject<{
+    reason_code: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    reason_code: number;
+}, {
+    reason_code: number;
+}>;
+type Input = z.infer<typeof InputSchema>;
+interface Output {
+    reasonCode: number;
+    reasonName: string;
+    category: "killswitch" | "spending" | "velocity" | "counterparty" | "atom" | "validation";
+    oneLiner: string;
+    remediation: string;
+}
+export declare const explainDecisionTool: Tool<Input, Output>;
+export {};