@opvs-ai/mcp 0.7.4 → 2.6.1

package/dist/index.js

@@ -1,97 +1,930 @@
 #!/usr/bin/env node
 /**
- * @opvs-ai/mcp — MCP Server for AgentBoard + AgentDocs
+ * @opvs-ai/mcp — MCP server for the OPVS on-demand model
  *
- * Gives Claude Code, Cursor, and Claude Desktop native tool access
- * to OPVS AgentBoard task management and AgentDocs documentation.
+ * Exposes 11 tools — the 8 that mirror the gateway's `skills-meta` plugin (so
+ * external MCP hosts like Claude Desktop, Cursor, Antigravity and Windsurf get
+ * the same surface OPVS-hosted agents see), plus `board_as_markdown` (Topic 1 /
+ * S1.4 — a whole AgentBoard as a Markdown plan in one call; it has no
+ * `tool_call` route because the agentboard skill ships no schema.yaml), plus
+ * `tool_read` (DLRT 3.2 — read any published skill's actual SKILL.md + its
+ * `references/` layers on-demand from the catalog bundle, with nothing
+ * installed), plus `sandbox_chat` (vendor test mode — drive your marketplace
+ * sandbox test agent through the real gateway, per Vendor-Upstream-and-Testing
+ * decision 4: a MODE of this package, not a new one). Every other capability is
+ * reached through `tool_call` indirection so the package fits under the
+ * ~100-tool cap that all current MCP clients enforce.
  *
- * Transport: stdio (JSON-RPC over stdin/stdout)
- * Auth: reads token from ~/.opvs/config.json (shared with @opvs-ai/cli)
+ * Tool names match OpenAI's `^[a-zA-Z0-9_-]+$` (see
+ * `feedback-openai-tool-name-regex` memory). Dots, `@`, and `/` are rejected.
  *
- * Multi-workspace: every tool accepts an optional `workspace` parameter.
- * If omitted, uses OPVS_WORKSPACE env var or the current workspace from config.
+ * Transport: stdio (JSON-RPC). Never write to stdout outside the SDK.
+ * Debug logs go to stderr via console.error().
  *
- * IMPORTANT: Never use console.log() — it corrupts the stdio transport.
- * Use console.error() for debug logging.
+ * Auth: PAT from `~/.opvs/config.json` (shared with `@opvs-ai/cli`). Brand is
+ * pinned server-side from the PAT — never trust LLM-supplied brand_id.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { createClient, buildUrl, getResponseText } from "@opvs-ai/core";
-// ── Handler modules ─────────────────────────────────────────────
-import { TOOLS as BOARD_TOOLS, handleTool as handleBoard } from "./handlers/board.js";
-import { TOOLS as AGENT_TOOLS, handleTool as handleAgent } from "./handlers/agent.js";
-import { TOOLS as DOCS_TOOLS, handleTool as handleDocs } from "./handlers/docs.js";
-import { TOOLS as VIEWS_TOOLS, handleTool as handleViews } from "./handlers/views.js";
-import { TOOLS as STAGES_TOOLS, handleTool as handleStages } from "./handlers/stages.js";
-import { TOOLS as AUTH_TOOLS, handleTool as handleAuth } from "./handlers/auth.js";
-import { TOOLS as PROTOCOL_TOOLS, handleTool as handleProtocol } from "./handlers/protocol.js";
-import { GENERATED_TOOLS, handleGeneratedTool } from "./generated-tools.js";
-import { err } from "./handlers/types.js";
-// ── API client ──────────────────────────────────────────────────
-async function callApi(method, path, wsSlug, body, headers) {
-    const client = createClient(wsSlug);
-    let res;
-    switch (method) {
-        case "GET":
-            res = await client.get(path, headers);
-            break;
-        case "POST":
-            res = await client.post(path, body, headers);
-            break;
-        case "PATCH":
-            res = await client.patch(path, body, headers);
-            break;
-        case "PUT":
-            res = await client.put(path, body, headers);
-            break;
-        case "DELETE":
-            res = await client.delete(path, headers);
-            break;
+import { createClient, getEffectiveConfig, getResponseText } from "@opvs-ai/core";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// Read the version from package.json at runtime so the MCP `initialize`
+// handshake never drifts from the published version (AgentCLI LEARNINGS #13).
+// dist/index.js sits next to package.json at the installed package root.
+const PKG_VERSION = (() => {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+function ok(body) {
+    const text = typeof body === "string" ? body : JSON.stringify(body);
+    return { content: [{ type: "text", text }] };
+}
+/** Standard error envelope: flat-sibling `_guidance` (W1.A discipline,
+ *  confirmed with SpiderIQ 2026-05-15 PM). Never wrap. */
+function err(message, guidance) {
+    const body = { error: message };
+    if (guidance)
+        body._guidance = guidance;
+    return { content: [{ type: "text", text: JSON.stringify(body) }] };
+}
+// ── Skill-ref helpers ─────────────────────────────────────────────────
+function normalizeSkillRef(ref) {
+    // Accept "@vendor/name", "vendor/name", or bare "name".
+    const cleaned = ref.replace(/^@/, "");
+    if (cleaned.includes("/")) {
+        const [vendor, ...rest] = cleaned.split("/");
+        return { full: `${vendor}/${rest.join("/")}`, vendor, name: rest.join("/") };
+    }
+    return { full: cleaned, vendor: "", name: cleaned };
+}
+// ── API client ────────────────────────────────────────────────────────
+function client() {
+    return createClient();
+}
+async function getJson(path) {
+    const res = await client().get(path);
+    const text = await getResponseText(res);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function postJson(path, body) {
+    const res = await client().post(path, body);
+    const text = await getResponseText(res);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
     }
+}
+/** GET a path and return the raw response body as text (no JSON parse). Used
+ *  for endpoints that emit Markdown / plain text such as the board export. */
+async function getText(path) {
+    const res = await client().get(path);
     return getResponseText(res);
 }
-function ok(text) {
-    return { content: [{ type: "text", text }] };
+async function del204(path) {
+    // The OPVS DELETE endpoints we hit return 204 No Content; createClient
+    // throws on non-2xx, so reaching here = success.
+    await client().delete(path);
+}
+/** Fetch the package descriptor from the registry and return the canonical
+ *  `manifest.skills[].id` array. Mirrors `SkillsMetaClient.fetchManifestSkillIds`
+ *  in the gateway plugin (W2.0.A). */
+async function fetchManifestSkillIds(vendor, packageName) {
+    const cleanedVendor = vendor.replace(/^@+/, "");
+    const canonicalVendor = `@${cleanedVendor}`;
+    const path = `/api/v1/registry/packages/${encodeURIComponent(canonicalVendor)}/${encodeURIComponent(packageName)}`;
+    try {
+        const data = await getJson(path);
+        if (typeof data !== "object" || data === null) {
+            return { ok: false, status: 502, detail: String(data).slice(0, 200) };
+        }
+        const manifest = data.manifest ??
+            {};
+        const rawSkills = Array.isArray(manifest.skills) ? manifest.skills : [];
+        const ids = rawSkills
+            .map((s) => (s && typeof s === "object" ? s.id : null))
+            .filter((id) => typeof id === "string" && id.length > 0);
+        return { ok: true, ids };
+    }
+    catch (e) {
+        const error = e;
+        return {
+            ok: false,
+            status: error.status ?? 502,
+            detail: (error.detail ?? "registry fetch failed").slice(0, 200),
+        };
+    }
 }
-// ── Tool registry ───────────────────────────────────────────────
+/** Resolve a skill name → active install_id for the brand pinned to the PAT. */
+async function resolveInstallId(skillRef) {
+    try {
+        const data = await getJson("/api/v1/marketplace/installed");
+        const items = data.items ?? [];
+        const wanted = normalizeSkillRef(skillRef);
+        for (const row of items) {
+            if (row.state !== "active")
+                continue;
+            const vendor = String(row.vendor ?? "");
+            const name = String(row.name ?? "");
+            const full = vendor ? `${vendor}/${name}` : name;
+            if (full === wanted.full ||
+                name === wanted.name ||
+                full === skillRef ||
+                name === skillRef) {
+                return { install_id: String(row.id), vendor, name };
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Tool definitions ──────────────────────────────────────────────────
+/**
+ * Appended to the discovery tool descriptions so an agent can self-recover from
+ * the ONE failure we can't fix server-side: an IDE (e.g. Antigravity, 2026-07)
+ * that discovers OPVS tools but blocks their execution ("not enabled" / "unknown
+ * tool"). A tool's DESCRIPTION is in the prompt even when the tool can't be
+ * called — so this hint is reachable when nothing else is.
+ */
+const IDE_TOOL_HINT = " IDE note: if your IDE reports this tool as 'not enabled' or 'unknown tool' at call time, " +
+    "enable the OPVS server's tools in your IDE's MCP settings — or fall back to the CLI: " +
+    "`opvs-skills install <@vendor/name> --runtime <claude-code|antigravity|cursor|windsurf> --dest .`.";
 const TOOLS = [
-    ...BOARD_TOOLS,
-    ...AGENT_TOOLS,
-    ...DOCS_TOOLS,
-    ...VIEWS_TOOLS,
-    ...STAGES_TOOLS,
-    ...AUTH_TOOLS,
-    ...PROTOCOL_TOOLS,
+    {
+        name: "tool_search",
+        description: "Semantic search across the OPVS marketplace registry for skills matching your intent. " +
+            "Returns ranked packages with vendor/name/description plus a `telemetry_signal` " +
+            "(absent|cold|warm|hot) reflecting 30-day usage on this brand. Call this BEFORE " +
+            "tool_call when you don't yet know which skill handles a job. Pair with tool_help " +
+            "for deep parameter docs. Response carries a sibling `_guidance` string. " +
+            "For board / DAG / factory work (task pipelines, claim loops, run-a-board), the " +
+            "`agentboard` skill is the one — then call tool_help(@opvs-ai/agentboard) for its " +
+            "operating model." +
+            IDE_TOOL_HINT,
+        inputSchema: {
+            type: "object",
+            properties: {
+                intent: {
+                    type: "string",
+                    description: "Free-text intent — what the agent is trying to do (e.g. 'find restaurant " +
+                        "leads in Aarhus', 'send a Telegram message').",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max results (1–25). Default 5.",
+                },
+                additional_filters: {
+                    type: "object",
+                    description: "Optional structured filter map. Reserved keys: `package` (vendor/name string), " +
+                        "`vendor`, `category`. Other keys are forwarded as-is to future filter slots.",
+                    additionalProperties: true,
+                },
+                include_schemas: {
+                    type: "boolean",
+                    description: "If true, the registry response shape includes method schemas (heavier payload, " +
+                        "useful for one-shot describe + call without a follow-up tool_help round-trip).",
+                },
+            },
+            required: ["intent"],
+        },
+    },
+    {
+        name: "tool_help",
+        description: "Fetch the marketplace package descriptor for a skill: description, methods, " +
+            "manifest, examples. Use BEFORE tool_call to understand parameter shapes. " +
+            "`section` narrows the payload (description | methods | manifest | all). Default: all. " +
+            "The `methods` section returns the rich `methods_index` (full param shapes incl. nested " +
+            "object `properties`) when the package has one, else the compact `manifest.methods` list. " +
+            "The `description` section is the skill's SKILL.md — for a board/factory skill it carries " +
+            "the operating model + a references index (the run-a-factory-board recipe). When the " +
+            "descriptor is a board/factory skill, tool_help attaches a `_guidance` sibling routing you " +
+            "to those facts so you don't drive a factory board blind.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Skill reference: '@vendor/name', 'vendor/name', or bare 'name' " +
+                        "(resolves to the @opvs-ai vendor when bare).",
+                },
+                section: {
+                    type: "string",
+                    enum: ["description", "methods", "manifest", "all"],
+                    description: "Slice of the descriptor to return. Default: all.",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "tool_read",
+        description: "Read any PUBLISHED skill's actual SKILL.md guidance on-demand — with nothing " +
+            "installed. Unlike tool_help (which returns the registry manifest's `description` " +
+            "field), tool_read extracts the real on-disk SKILL.md body from the signed CATALOG " +
+            "bundle PLUS its shippable `references/` layer files, so you get the full operating " +
+            "model an agent sees after install. Catalog-global + inert (no auth trust boundary — " +
+            "same as download/changelog): works for UNINSTALLED skills. Default returns " +
+            "`{vendor, name, version, skill_md, layers[]}`; `layers` lists deeper files you can " +
+            "pull one at a time by re-calling with `path` (e.g. path='references/run-a-factory-board.md'). " +
+            "Use this to LEARN a skill's guidance before deciding whether to tool_install it." +
+            IDE_TOOL_HINT,
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Skill reference: '@vendor/name', 'vendor/name', or bare 'name' " +
+                        "(resolves to the @opvs-ai vendor when bare).",
+                },
+                path: {
+                    type: "string",
+                    description: "Optional layer file to read instead of the SKILL.md body — one of the entries " +
+                        "from a prior tool_read's `layers[]` (e.g. 'references/foo.md'). Returns that " +
+                        "file's raw markdown. Restricted to the skill's shippable layer subdirs; an " +
+                        "unknown path or a traversal attempt yields 404.",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "tool_call",
+        description: "Universal proxy to any installed skill on this brand. Routes through the " +
+            "marketplace runtime forwarder (W1.9). The `skill` segment is resolved server-side " +
+            "from `manifest.skills[].id` (W2.0.A) — pass either '@vendor/name' or a bare " +
+            "skill id. Response carries a sibling `_guidance` string with #audit/#next/#dont " +
+            "tags — parse `_guidance` before acting on the data.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                skill: {
+                    type: "string",
+                    description: "Skill reference. Either '@vendor/name', 'vendor/name', or a bare " +
+                        "manifest.skills[].id. Resolved against this brand's active installs.",
+                },
+                method: {
+                    type: "string",
+                    description: "Method to invoke (defined in the skill's `methods:` block). Example: " +
+                        "'list_tasks', 'send_email'. Use tool_help first if unsure.",
+                },
+                params: {
+                    type: "object",
+                    description: "Method parameters. The runtime forwarder splits these into path/query/body " +
+                        "based on the skill's schema. Never set `brand_id` here — it's pinned server-side.",
+                    additionalProperties: true,
+                },
+            },
+            required: ["skill", "method"],
+        },
+    },
+    {
+        name: "tool_pin",
+        description: "Pin or unpin a skill in an OPVS agent's `## Pinned Skills` section (TOOLS.md). " +
+            "Pinned skills surface as native typed tools the next time that agent boots a session. " +
+            "Idempotent. NOTE: in MCP this is a stub today — TOOLS.md persistence requires " +
+            "Management API access not exposed to the PAT auth surface. Until W2.MCP.PIN ships the " +
+            "PAT-gated passthrough, use the OPVS dashboard's agent profile editor to manage pins.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Skill reference (e.g. '@opvs-ai/agentboard').",
+                },
+                agent_id: {
+                    type: "string",
+                    description: "Target OPVS agent id whose TOOLS.md to edit.",
+                },
+                action: {
+                    type: "string",
+                    enum: ["pin", "unpin"],
+                    description: "'pin' (default) or 'unpin'.",
+                },
+            },
+            required: ["name", "agent_id"],
+        },
+    },
+    {
+        name: "tool_list_installed",
+        description: "List every marketplace package installed on this brand: vendor, name, version, " +
+            "state, install_id. Use to confirm what's already available before tool_install. " +
+            "Brand is read server-side from the PAT.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "tool_install",
+        description: "Install a marketplace package onto this brand. Requires the registry `package_id` " +
+            "(UUID, get it from tool_search). Grants the entitlements you pass; missing required " +
+            "entitlements yield a structured 422 with the gap list in `_guidance`. Credentials " +
+            "must already exist on the brand or the install enters `pending` state.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                package_id: {
+                    type: "string",
+                    description: "Registry package UUID (from tool_search result `id` field).",
+                },
+                granted_entitlements: {
+                    type: "array",
+                    description: "Entitlement strings the brand is consenting to. Must cover the manifest's " +
+                        "required set. Omit to install with no grants (skill will refuse to run).",
+                    items: { type: "string" },
+                },
+                credential_bindings: {
+                    type: "object",
+                    description: "Optional credential resolutions. Keyed by credential name from the manifest. " +
+                        "Each value is the `api_integration_id` to bind, or an object with provider/id.",
+                    additionalProperties: true,
+                },
+            },
+            required: ["package_id"],
+        },
+    },
+    {
+        name: "tool_uninstall",
+        description: "Uninstall a marketplace package from this brand. Flips `installed_packages.state` " +
+            "to 'uninstalled' and revokes all granted entitlements. Gateway picks up the flip " +
+            "within 60s. Use tool_list_installed to find the install_id.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                install_id: {
+                    type: "string",
+                    description: "The install row UUID (from tool_list_installed).",
+                },
+            },
+            required: ["install_id"],
+        },
+    },
+    {
+        name: "whoami",
+        description: "Probe the current PAT context: workspace slug, brand_id, agent role (if any), " +
+            "API base URL. Use this BEFORE sensitive operations to confirm which brand the " +
+            "PAT is pinned to. Pure session probe — emits one upstream GET against /auth/me.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "board_as_markdown",
+        description: "Read a WHOLE AgentBoard (or a chosen subset of its columns) as a single " +
+            "Markdown plan/PRD document — one call instead of N task fetches. Cheaper on " +
+            "tokens and gives narrative context, not raw rows. Returns the rendered " +
+            "Markdown string verbatim (read-only, deterministic — same board state → same " +
+            "bytes, each task row carries an HTML comment with its UUID for diffing). " +
+            "Brand is pinned server-side from the PAT — never pass a brand_id. Pick `detail`: " +
+            "`summary` = compact one-row-per-task table (token-cheapest); `standard` " +
+            "(default) = the nested plan format with task bodies, subtasks and stages; " +
+            "`full` = the exhaustive dump including comments.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                board_id: {
+                    type: "string",
+                    description: "The board UUID to render.",
+                },
+                detail: {
+                    type: "string",
+                    enum: ["summary", "standard", "full"],
+                    description: "Render depth. Default `standard` (the nested plan/PRD shape). " +
+                        "`summary` is the compact table; `full` adds comments.",
+                },
+                columns: {
+                    type: "string",
+                    description: "Optional comma-separated column filter — names OR ids, mixed. Each token " +
+                        "is resolved name-first-then-id; an unknown token fails loud (400). Omit to " +
+                        "render every column.",
+                },
+            },
+            required: ["board_id"],
+        },
+    },
+    {
+        name: "sandbox_chat",
+        description: "VENDOR TEST MODE — live-chat your marketplace sandbox test agent through the " +
+            "REAL OPVS gateway. The agent is `skills:[]`, so the MODEL reads your published " +
+            "SKILL.md guidance and decides whether/how to call a method — this is the only " +
+            "level that validates 'does my guidance make an agent pick the right tool?'. " +
+            "Returns the agent's reply PLUS `tools_fired` — the tool calls captured from the " +
+            "agent's own session transcript (the load-bearing proof a skill fired; a reply " +
+            "alone can be produced with no call). Auth is your sandbox-scoped PAT from " +
+            "`~/.opvs/config.json`; the sandbox brand is pinned SERVER-SIDE from it — never " +
+            "pass a brand_id. Provision the sandbox + install your package first (dashboard " +
+            "or `opvs-skills`).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                vendor: {
+                    type: "string",
+                    description: "Your vendor id (the sandbox owner). Example: the UUID or slug from your " +
+                        "vendor onboarding.",
+                },
+                message: {
+                    type: "string",
+                    description: "The message to send to the sandbox agent this turn.",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Per-turn timeout in seconds (1–300, default 120).",
+                },
+            },
+            required: ["vendor", "message"],
+        },
+    },
 ];
-// ── Handler router ──────────────────────────────────────────────
-const handlers = [handleBoard, handleAgent, handleDocs, handleViews, handleStages, handleProtocol];
+// ── Tool execution ────────────────────────────────────────────────────
+/** Build the exact `@vendor/name` from a search-result row (defensive on field names). */
+function resultPackageName(item) {
+    if (typeof item.name === "string" && item.name.startsWith("@"))
+        return item.name;
+    const vendorRaw = typeof item.vendor === "string"
+        ? item.vendor
+        : typeof item.vendor_name === "string"
+            ? item.vendor_name
+            : null;
+    const name = typeof item.name === "string" ? item.name : null;
+    if (vendorRaw && name) {
+        const v = vendorRaw.startsWith("@") ? vendorRaw : `@${vendorRaw}`;
+        return `${v}/${name}`;
+    }
+    return null;
+}
+/**
+ * Make tool_search results copy-paste-proof: attach the exact `install` command
+ * + `tool_read` call to every row, plus a `_guidance` line telling the agent to
+ * pass the name VERBATIM — a model "helpfully" singularizing/pluralizing a
+ * package name is the #1 cause of a marketplace 404.
+ */
+function enrichSearchResults(data) {
+    if (!data || typeof data !== "object")
+        return data;
+    const d = data;
+    const rows = (Array.isArray(d.results) && d.results) ||
+        (Array.isArray(d.packages) && d.packages) ||
+        (Array.isArray(d.items) && d.items) ||
+        null;
+    if (rows) {
+        for (const item of rows) {
+            if (!item || typeof item !== "object")
+                continue;
+            const pkg = resultPackageName(item);
+            if (!pkg)
+                continue;
+            item.install = `opvs-skills install ${pkg} --runtime <claude-code|antigravity|cursor|windsurf> --dest .`;
+            item.read = `tool_read("${pkg}")`;
+        }
+    }
+    const prior = typeof d._guidance === "string" ? d._guidance + " " : "";
+    d._guidance =
+        prior +
+            "#names:pass a result's `.name` (or the ready `.install`/`.read`) VERBATIM to " +
+            "tool_read/tool_install/CLI — never singularize, pluralize, or paraphrase it " +
+            "(the #1 cause of a marketplace 404).";
+    return d;
+}
+async function handleToolSearch(args) {
+    if (!args.intent || typeof args.intent !== "string") {
+        return err("intent is required", "#audit.error:input=missing — tool_search needs a free-text intent string.");
+    }
+    const q = new URLSearchParams({
+        intent: args.intent,
+        limit: String(args.limit ?? 5),
+    });
+    if (args.additional_filters && typeof args.additional_filters === "object") {
+        // Forward filters individually so future server-side handling can pick them
+        // up by name. The locked contract reserves `package` (vendor/name string).
+        // Other keys pass through untouched.
+        for (const [k, v] of Object.entries(args.additional_filters)) {
+            if (v == null)
+                continue;
+            q.set(`filter_${k}`, typeof v === "string" ? v : JSON.stringify(v));
+        }
+    }
+    if (args.include_schemas)
+        q.set("include_schemas", "true");
+    try {
+        const data = await getJson(`/api/v1/registry/search?${q.toString()}`);
+        return ok(enrichSearchResults(data));
+    }
+    catch (e) {
+        const error = e;
+        return err(`tool_search failed: ${error.status ?? "?"} ${error.detail ?? "unknown"}`, "#audit.error:registry-search " +
+            "#next:fall back to tool_list_installed for a flat catalog of what this brand has.");
+    }
+}
+/** Is this descriptor a board / DAG / factory skill? Keyed on the registry
+ *  category first (stable), falling back to the skill name. Drives the
+ *  factory-operating-model `_guidance` nudge below. */
+function isBoardFactorySkill(refName, data) {
+    const category = String(data.category ?? "").toLowerCase();
+    if (category === "board")
+        return true;
+    return /agentboard|\bboard\b/.test(refName.toLowerCase());
+}
+/** Routing nudge for board/factory skills (GS.2). A POINTER to the canonical
+ *  sources (the SKILL.md `description` section + its references index + the live
+ *  claimTask/getRunnable `_guidance` envelopes), carrying the few platform
+ *  invariants an MCP agent needs at decision time so it can't drive a factory
+ *  board blind. Deliberately terse — the full recipe is run-a-factory-board.md,
+ *  surfaced via section='description'; this never restates it. */
+const FACTORY_HELP_GUIDANCE = "#use:board/DAG/factory task pipelines. " +
+    "#read:section='description' for the operating model + references index (the " +
+    "run-a-factory-board recipe). " +
+    "#factory:new cards land in Backlog (staging, NOT claimable) → move to Ready " +
+    "(claimable by role 'builder') → a worker claims and it auto-moves to Executing. " +
+    "A factory board runs NOTHING until an opvs-sidecar worker is pointed at its " +
+    "board_id; set a `mode:` label (auto|assisted|manual) per card for build autonomy. " +
+    "#next:the live claimTask + getRunnable responses carry their own `_guidance` " +
+    "envelope (e.g. a claim that returns task_id:null+reason is a worker misconfig, " +
+    "not no-work) — read it.";
+/** Inject the factory `_guidance` sibling into a tool_help payload when the
+ *  descriptor is a board/factory skill. Object bodies only; never wraps. */
+function okWithFactoryGuidance(body, refName, data) {
+    if (isBoardFactorySkill(refName, data)) {
+        body._guidance = FACTORY_HELP_GUIDANCE;
+    }
+    return ok(body);
+}
+async function handleToolHelp(args) {
+    if (!args.name) {
+        return err("name is required", "#audit.error:input=missing — pass a skill reference like '@opvs-ai/agentboard'.");
+    }
+    const ref = normalizeSkillRef(args.name);
+    const vendor = ref.vendor || "opvs-ai";
+    const canonicalVendor = `@${vendor}`;
+    const path = `/api/v1/registry/packages/${encodeURIComponent(canonicalVendor)}/${encodeURIComponent(ref.name)}`;
+    try {
+        const data = await getJson(path);
+        const section = (args.section || "all").toLowerCase();
+        if (section === "all")
+            return okWithFactoryGuidance(data, ref.name, data);
+        // The registry's package_to_summary_dict emits `vendor_name`, not
+        // `vendor`. Expose both keys so callers don't have to know which
+        // surface they're talking to.
+        const subset = {
+            vendor: data.vendor_name ?? data.vendor,
+            vendor_name: data.vendor_name ?? data.vendor,
+            name: data.name,
+            version: data.version,
+        };
+        if (section === "description") {
+            subset.description = data.description;
+            subset.category = data.category;
+        }
+        else if (section === "methods") {
+            // Prefer the rich `methods_index` embedded at publish (skill-object-schema
+            // slice 1.2): {skill_id: {method: {description, http, params}}} where
+            // `params` carries the full nested object `properties` verbatim. Mirrors the
+            // gateway `skill_describe(section=methods)` logic (skills-meta/index.ts) so
+            // MCP hosts get the same nested-param detail. Falls back to the compact
+            // `manifest.methods` (name/http/description, no params) for legacy packages
+            // whose registry row has no fetchable bundle yet.
+            const methodsIndex = data.methods_index;
+            const hasIndex = methodsIndex != null &&
+                typeof methodsIndex === "object" &&
+                Object.values(methodsIndex).some((m) => m != null &&
+                    typeof m === "object" &&
+                    Object.keys(m).length > 0);
+            if (hasIndex) {
+                subset.methods_index = methodsIndex;
+            }
+            else {
+                subset.methods =
+                    data.manifest?.methods ?? null;
+            }
+        }
+        else if (section === "manifest") {
+            subset.manifest = data.manifest ?? null;
+        }
+        else {
+            return okWithFactoryGuidance(data, ref.name, data);
+        }
+        return okWithFactoryGuidance(subset, ref.name, data);
+    }
+    catch (e) {
+        const error = e;
+        if (error.status === 404) {
+            return err(`package '${canonicalVendor}/${ref.name}' not found in registry`, "#audit.error:package=missing #next:try tool_search for similar skills.");
+        }
+        return err(`tool_help failed: ${error.status ?? "?"} ${error.detail ?? ""}`);
+    }
+}
+async function handleToolRead(args) {
+    if (!args.name) {
+        return err("name is required", "#audit.error:input=missing — pass a skill reference like '@opvs-ai/agentboard'.");
+    }
+    const ref = normalizeSkillRef(args.name);
+    const vendor = ref.vendor || "opvs-ai";
+    const canonicalVendor = `@${vendor}`;
+    const base = `/api/v1/registry/packages/${encodeURIComponent(canonicalVendor)}/${encodeURIComponent(ref.name)}/skill-guide`;
+    // Specific layer-file read → the 3.1 endpoint emits raw text/markdown (not
+    // JSON), so read it as text and return the body verbatim.
+    if (args.path) {
+        const q = new URLSearchParams({ path: args.path });
+        try {
+            const body = await getText(`${base}?${q.toString()}`);
+            return ok(body);
+        }
+        catch (e) {
+            const error = e;
+            if (error.status === 404) {
+                return err(`layer file '${args.path}' not found in ${canonicalVendor}/${ref.name}`, "#audit.error:layer=missing #next:call tool_read without `path` to see the " +
+                    "valid `layers[]` list for this skill.");
+            }
+            return err(`tool_read failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:upstream");
+        }
+    }
+    // Default → the JSON payload with the SKILL.md body + discoverable layers[].
+    try {
+        const data = await getJson(base);
+        if (typeof data === "object" && data !== null) {
+            const layers = Array.isArray(data.layers)
+                ? data.layers
+                : [];
+            data._guidance =
+                layers.length > 0
+                    ? `#audit.ok:skill_md read + ${layers.length} layer file(s) available. ` +
+                        "#next:re-call tool_read with `path` set to one of `layers[]` to read a " +
+                        "reference file. #dont:tool_install isn't required to READ guidance — only to " +
+                        "CALL the skill's methods."
+                    : "#audit.ok:skill_md read (no extra layer files). " +
+                        "#next:tool_help for the method schemas; tool_install to enable calling them.";
+        }
+        return ok(data);
+    }
+    catch (e) {
+        const error = e;
+        if (error.status === 404) {
+            return err(`no published guidance for '${canonicalVendor}/${ref.name}' ` +
+                "(package/version/SKILL.md missing)", "#audit.error:guide=missing #next:tool_search to find published skills; " +
+                "tool_help to confirm the package exists in the registry.");
+        }
+        return err(`tool_read failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:upstream #next:tool_help to verify the package is reachable.");
+    }
+}
+async function handleToolCall(args) {
+    if (!args.skill || !args.method) {
+        return err("skill and method are required", "#audit.error:input=missing — tool_call needs both a skill reference and a method name.");
+    }
+    const resolved = await resolveInstallId(args.skill);
+    if (!resolved) {
+        return err(`skill '${args.skill}' not installed on this brand`, "#audit.error:skill=not-installed " +
+            "#next:try tool_search to discover candidates → tool_install to add one.");
+    }
+    // W2.0.A — resolve the URL skill segment from `manifest.skills[].id`, not the
+    // package name. Three branches when input is @vendor/name. Bare-name inputs
+    // pass through as-is (existing behaviour where sub-skill id == package name).
+    const inputRef = normalizeSkillRef(args.skill);
+    let routeSkillId = resolved.name;
+    if (inputRef.vendor !== "") {
+        const lookup = await fetchManifestSkillIds(resolved.vendor || inputRef.vendor, resolved.name);
+        if (!lookup.ok) {
+            return err(`tool_call route resolution failed: registry returned ${lookup.status} for ${resolved.vendor || `@${inputRef.vendor}`}/${resolved.name}`, "#audit.error:manifest-fetch " +
+                "#next:tool_help to verify the package is reachable.");
+        }
+        if (lookup.ids.length === 0) {
+            return err(`package ${resolved.vendor || `@${inputRef.vendor}`}/${resolved.name} declares no sub-skills (likely a meta-package — install a leaf package)`, "#audit.error:no-sub-skills " +
+                "#next:tool_list_installed to find the leaf packages it pulled in.");
+        }
+        if (lookup.ids.length === 1) {
+            routeSkillId = lookup.ids[0];
+        }
+        else {
+            return err(`package ${resolved.vendor || `@${inputRef.vendor}`}/${resolved.name} has ${lookup.ids.length} sub-skills, specify one of: ${lookup.ids.join(", ")}`, "#audit.error:ambiguous-sub-skill " +
+                "#next:re-call tool_call with `skill` set to one of the sub-skill ids above (these come from manifest.skills[].id).");
+        }
+    }
+    const path = `/api/v1/marketplace/runtime/${resolved.install_id}/${encodeURIComponent(routeSkillId)}/${encodeURIComponent(args.method)}`;
+    try {
+        const data = await postJson(path, args.params ?? {});
+        return ok(data);
+    }
+    catch (e) {
+        const error = e;
+        return err(`tool_call failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:upstream " +
+            "#next:tool_help for the method's parameters; tool_list_installed to verify entitlements.");
+    }
+}
+async function handleToolPin(args) {
+    // W2.1 TOOLS.md persistence is live in the gateway's skills-meta plugin, but
+    // the underlying Management API endpoint is admin-key gated and not yet
+    // reachable from a PAT-authenticated MCP client. Returning an explicit
+    // not-yet-supported envelope (vs silent success) keeps the agent honest.
+    if (!args.name || !args.agent_id) {
+        return err("name and agent_id are required", "#audit.error:input=missing");
+    }
+    const ref = normalizeSkillRef(args.name);
+    const fullRef = ref.vendor ? `@${ref.vendor}/${ref.name}` : ref.name;
+    return ok({
+        action: args.action || "pin",
+        skill: fullRef,
+        agent_id: args.agent_id,
+        changed: false,
+        _guidance: "#audit.warn:not-supported-via-mcp — tool_pin's Management API surface " +
+            "isn't PAT-gated yet. Use the OPVS dashboard agent profile editor at " +
+            "/admin/agents/personas to pin/unpin skills, or run skill_pin via the " +
+            "gateway plugin if you have an OpenClaw agent session. The MCP shim " +
+            "will start writing through once W2.MCP.PIN ships the PAT passthrough.",
+    });
+}
+async function handleToolListInstalled() {
+    try {
+        const data = await getJson("/api/v1/marketplace/installed");
+        const items = data.items ?? [];
+        const active = items.filter((i) => i.state === "active").length;
+        return ok({
+            ...data,
+            _guidance: `#audit.ok:installs=${items.length} active=${active}. ` +
+                "#next:tool_help on any of these to see methods, or tool_call to invoke.",
+        });
+    }
+    catch (e) {
+        const error = e;
+        return err(`tool_list_installed failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:upstream");
+    }
+}
+async function handleToolInstall(args) {
+    if (!args.package_id) {
+        return err("package_id is required", "#audit.error:input=missing — call tool_search first to get a package_id (the `id` field).");
+    }
+    const body = {};
+    if (args.granted_entitlements)
+        body.granted_entitlements = args.granted_entitlements;
+    if (args.credential_bindings)
+        body.credential_bindings = args.credential_bindings;
+    try {
+        const data = await postJson(`/api/v1/marketplace/packages/${encodeURIComponent(args.package_id)}/install`, body);
+        return ok(data);
+    }
+    catch (e) {
+        const error = e;
+        return err(`tool_install failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:install " +
+            "#next:if 422, inspect `detail` for the missing entitlements/credentials list.");
+    }
+}
+async function handleToolUninstall(args) {
+    if (!args.install_id) {
+        return err("install_id is required", "#audit.error:input=missing — call tool_list_installed to find the install_id.");
+    }
+    try {
+        await del204(`/api/v1/marketplace/installed/${encodeURIComponent(args.install_id)}`);
+        return ok({
+            install_id: args.install_id,
+            state: "uninstalled",
+            _guidance: "#audit.ok:uninstalled — entitlement grants revoked; gateway picks up the flip within 60s.",
+        });
+    }
+    catch (e) {
+        const error = e;
+        return err(`tool_uninstall failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:uninstall");
+    }
+}
+async function handleWhoami() {
+    try {
+        const cfg = getEffectiveConfig();
+        const me = await getJson("/api/v1/auth/me");
+        return ok({
+            api_url: cfg.api_url,
+            workspace: cfg.workspace_slug ?? null,
+            brand_id: cfg.brand_id ?? null,
+            identity: me,
+            _guidance: cfg.brand_id != null
+                ? `#audit.ok:brand_id=${cfg.brand_id} workspace=${cfg.workspace_slug ?? "?"}`
+                : "#audit.warn:brand=missing — this PAT isn't brand-scoped; brand-pinned " +
+                    "tools (tool_call, tool_list_installed) will refuse. Run `opvs auth request` " +
+                    "with a brand-scoped workspace.",
+        });
+    }
+    catch (e) {
+        const error = e;
+        return err(`whoami failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:auth — PAT may be missing or expired. Run `opvs auth request`.");
+    }
+}
+async function handleBoardAsMarkdown(args) {
+    if (!args.board_id || typeof args.board_id !== "string") {
+        return err("board_id is required", "#audit.error:input=missing — board_as_markdown needs the board UUID. " +
+            "Use tool_call(@opvs-ai/agentboard, list_boards) to find one.");
+    }
+    if (args.detail != null &&
+        !["summary", "standard", "full"].includes(args.detail)) {
+        return err(`invalid detail '${args.detail}'`, "#audit.error:input=bad-detail — detail must be summary | standard | full. " +
+            "#next:omit it for the default (standard).");
+    }
+    // Mirror the export contract: format=md is fixed; detail/columns are forwarded
+    // only when the caller set them (don't synthesize defaults — let the backend
+    // own them; LEARNINGS #38, the silent-drop tax cuts both ways).
+    const q = new URLSearchParams({ format: "md" });
+    if (args.detail)
+        q.set("detail", args.detail);
+    if (args.columns)
+        q.set("columns", args.columns);
+    const path = `/api/v1/board/boards/${encodeURIComponent(args.board_id)}/export?${q.toString()}`;
+    try {
+        const md = await getText(path);
+        return ok(md);
+    }
+    catch (e) {
+        const error = e;
+        if (error.status === 400) {
+            return err(`board_as_markdown: ${error.detail ?? "bad request"}`, "#audit.error:bad-columns — an unknown column name/id was passed. " +
+                "#next:tool_call(@opvs-ai/agentboard, list_columns) to see valid columns, or omit `columns`.");
+        }
+        if (error.status === 404) {
+            return err(`board '${args.board_id}' not found (or not visible to this brand)`, "#audit.error:board=missing #next:whoami to confirm the PAT's brand; " +
+                "tool_call(@opvs-ai/agentboard, list_boards) to list boards.");
+        }
+        return err(`board_as_markdown failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:upstream #next:whoami to verify auth/brand; check the board_id.");
+    }
+}
+async function handleSandboxChat(args) {
+    if (!args.vendor || !args.message) {
+        return err("vendor and message are required", "#audit.error:input=missing — sandbox_chat needs your vendor id and a message. " +
+            "The sandbox brand is pinned server-side from your PAT.");
+    }
+    const body = { message: args.message };
+    if (args.timeout != null)
+        body.timeout = args.timeout;
+    const path = `/api/v1/marketplace/vendors/${encodeURIComponent(args.vendor)}/sandbox/chat`;
+    try {
+        const data = await postJson(path, body);
+        const fired = Array.isArray(data.tools_fired) ? data.tools_fired : [];
+        // Attach the tool-fire verdict as a sibling `_guidance` string (W1.A) so the
+        // driving agent parses the EVIDENCE, not just the reply text.
+        data._guidance =
+            fired.length > 0
+                ? `#audit.ok:tools_fired=${fired.join(",")} — verified from the sandbox agent's ` +
+                    "session transcript (authoritative). #next:inspect tool_calls for ids/timestamps."
+                : "#audit.warn:no-tool-fired — the model answered from guidance alone this turn. " +
+                    "If you expected a skill call, sharpen the SKILL.md decision rules or the " +
+                    "method `guidance.use`, then retry.";
+        return ok(data);
+    }
+    catch (e) {
+        const error = e;
+        if (error.status === 403) {
+            return err(`sandbox_chat forbidden: ${error.detail ?? "PAT is not sandbox-scoped"}`, "#audit.error:auth — this tool needs a SANDBOX-scoped PAT (from sandbox " +
+                "provision) or a platform admin key. A real-brand PAT is refused.");
+        }
+        if (error.status === 404) {
+            return err(`sandbox_chat: no sandbox for vendor '${args.vendor}'`, "#audit.error:no-sandbox #next:provision the sandbox + install your package first.");
+        }
+        return err(`sandbox_chat failed: ${error.status ?? "?"} ${error.detail ?? ""}`, "#audit.error:upstream #next:confirm the gateway is up and the sandbox agent exists.");
+    }
+}
 async function handleTool(name, args) {
-    // Try each domain handler
-    for (const handler of handlers) {
-        const result = await handler(name, args, callApi, buildUrl);
-        if (result !== null)
-            return result;
-    }
-    // Auth handler has a different signature (no buildUrl)
-    const authResult = await handleAuth(name, args, callApi);
-    if (authResult !== null)
-        return authResult;
-    return err(`Unknown tool: ${name}`);
-}
-// ── Server setup ────────────────────────────────────────────────
-const server = new Server({ name: "opvs", version: "0.7.4" }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: [...TOOLS, ...GENERATED_TOOLS],
-}));
+    switch (name) {
+        case "tool_search":
+            return handleToolSearch(args);
+        case "tool_help":
+            return handleToolHelp(args);
+        case "tool_read":
+            return handleToolRead(args);
+        case "tool_call":
+            return handleToolCall(args);
+        case "tool_pin":
+            return handleToolPin(args);
+        case "tool_list_installed":
+            return handleToolListInstalled();
+        case "tool_install":
+            return handleToolInstall(args);
+        case "tool_uninstall":
+            return handleToolUninstall(args);
+        case "whoami":
+            return handleWhoami();
+        case "board_as_markdown":
+            return handleBoardAsMarkdown(args);
+        case "sandbox_chat":
+            return handleSandboxChat(args);
+        default:
+            return err(`unknown tool: ${name}`);
+    }
+}
+// ── Server setup ──────────────────────────────────────────────────────
+const server = new Server({ name: "opvs", version: PKG_VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-        // Try generated tools first (opvsHUB skills)
-        const generatedResult = await handleGeneratedTool(name, (args ?? {}), callApi, buildUrl, ok);
-        if (generatedResult !== null)
-            return generatedResult;
-        // Fall back to hand-written tools
         return await handleTool(name, (args ?? {}));
     }
     catch (e) {