@muxoai/sdk 1.2.3 → 1.3.0

package/dist/mcp.js

@@ -0,0 +1,914 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { ROOT_DIR } from "./config.js";
+/**
+ * Concise server instructions (<512 chars) per OpenAI Plugin MCP Server specification:
+ * https://developers.openai.com/plugins/build/mcp-server
+ */
+export const MUXO_MCP_SERVER_INSTRUCTIONS = "Muxo governs SaaS actions (Composio app.*), Instant tools (instant.*), Cloud Infrastructure (Stripe Projects resource.*), Supermemory v5 recall, and Microsoft Agent Governance Ed25519 receipts. Workflow: 1) search_tools & inspect_tool. 2) plan_action to get a plan_*. 3) If authHandoff.required is true, show redirectUrl and call wait_for_connection. 4) Execute via the matching risk tool (execute_read/write/admin/financial/provisioning/destructive). 5) Verify via get_receipt.";
+export const MUXO_MCP_TOOLS = [
+    {
+        name: "get_profile",
+        title: "Get Authenticated Profile",
+        description: "Get the authenticated actor profile, user ID, email, workspace ID, and subscription tier.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Unique user identifier" },
+                name: { type: "string", description: "Display name" },
+                email: { type: "string", description: "Email address" },
+                workspaceId: { type: "string", description: "Active workspace ID" },
+                workspaceName: { type: "string", description: "Active workspace name" },
+                tier: { type: "string", description: "Workspace subscription tier" },
+            },
+            required: ["id"],
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+        _meta: {
+            "openai/profile": true,
+        },
+    },
+    {
+        name: "get_organization",
+        title: "Get Organization & Billing Summary",
+        description: "Get workspace governance policy, monthly action usage, credit balance, Merchant-of-Record supplier settlement summary, and active connection/resource counts.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "search_tools",
+        title: "Search Unified Tool Catalog",
+        description: "Search the unified Muxo catalog across Connected Apps (Composio SDK: app.*), Instant Tools (Composio Instant: instant.*), and Cloud Infrastructure (Stripe Projects: resource.*).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search keywords (e.g. 'postgres', 'github issue', 'web search', 'seo audit', 'redis')",
+                },
+                lane: {
+                    type: "string",
+                    enum: ["all", "composio_sdk", "composio_instant", "stripe_projects"],
+                    default: "all",
+                },
+                risk_level: {
+                    type: "string",
+                    enum: [
+                        "read",
+                        "write",
+                        "admin",
+                        "financial",
+                        "provisioning",
+                        "destructive",
+                    ],
+                },
+                limit: { type: "number", default: 20 },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "inspect_tool",
+        title: "Inspect Tool Schema & Risk",
+        description: "Inspect a tool's full input JSON schema, risk classification, provider lane, LLM context URL, and credit cost before planning.",
+        inputSchema: {
+            type: "object",
+            required: ["tool_slug"],
+            properties: {
+                tool_slug: {
+                    type: "string",
+                    description: "Canonical Muxo tool slug (e.g. 'instant.seo.audit', 'app.gmail.send_email', or 'resource.turso.database')",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "connection_status",
+        title: "Check Connection Status",
+        description: "Check connection status across Composio OAuth apps, Instant wallet, and linked Stripe Projects cloud providers.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                provider: {
+                    type: "string",
+                    description: "Optional provider filter (e.g. 'github', 'gmail', 'slack', 'neon', 'turso')",
+                },
+                sync_live: {
+                    type: "boolean",
+                    default: true,
+                    description: "Whether to sync live status from upstream Composio and Stripe Projects",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "start_connection",
+        title: "Start OAuth Connection Handoff",
+        description: "Initiate a managed OAuth connection handoff for a Connected App (Composio) or link a cloud provider (Stripe Projects).",
+        inputSchema: {
+            type: "object",
+            required: ["provider"],
+            properties: {
+                provider: {
+                    type: "string",
+                    description: "Provider or toolkit slug (e.g. 'github', 'gmail', 'slack', 'neon')",
+                },
+                lane: {
+                    type: "string",
+                    enum: ["composio_sdk", "stripe_projects"],
+                    description: "Provider lane (defaults to composio_sdk unless prefixed with resource.)",
+                },
+                callback_url: {
+                    type: "string",
+                    description: "Optional OAuth callback URL",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "wait_for_connection",
+        title: "Wait for OAuth Connection Handoff",
+        description: "Poll and wait for an external user's pending OAuth connection handoff to become active before resuming a planned operation.",
+        inputSchema: {
+            type: "object",
+            required: ["provider"],
+            properties: {
+                provider: {
+                    type: "string",
+                    description: "Provider or toolkit slug (e.g. 'github', 'gmail', 'slack', 'notion', 'linear')",
+                },
+                timeout_seconds: {
+                    type: "number",
+                    default: 15,
+                    description: "Maximum seconds to poll for OAuth completion (0-120, default 15)",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "plan_action",
+        title: "Create Governed Action Plan",
+        description: "Create a governed execution plan (plan_*) for any tool, billing operation, or infrastructure provisioning operation. Accepts either an exact tool_slug (e.g. 'instant.seo.audit', 'billing.credits.topup', 'resource.turso.database') or a natural-language instruction (e.g. 'audit seo for https://muxo.ai'). Evaluates workspace policy, risk level, Supermemory v5 recall, Ed25519 signature, BYOK vs Muxo-funded mode, and credit balance.",
+        inputSchema: {
+            type: "object",
+            required: ["tool_slug"],
+            properties: {
+                tool_slug: {
+                    type: "string",
+                    description: "Muxo tool slug (e.g. 'instant.seo.audit', 'billing.credits.topup') or natural-language request",
+                },
+                input: {
+                    type: "object",
+                    description: "Arguments matching the tool's inputSchema (auto-extracted when tool_slug is natural language)",
+                },
+                reason: {
+                    type: "string",
+                    description: "Audit reason explaining why this action is being planned",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "get_plan",
+        title: "Get Action Plan",
+        description: "Inspect the status, risk level, governance decision record, and approval state of a planned action.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "get_run_context",
+        title: "Get Workspace Context & Memory",
+        description: "Get the workspace runtime context, Supermemory v5 contextual brain (static/dynamic profile + hybrid search recall), Microsoft Agent Governance status, active provisioned Stripe Projects resources, and redacted environment variable keys.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Optional semantic search query to recall relevant workspace memories from Supermemory v5",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "execute_read",
+        title: "Execute Read Plan",
+        description: "Execute an approved plan with riskLevel = 'read'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_write",
+        title: "Execute Write Plan",
+        description: "Execute an approved plan with riskLevel = 'write'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_admin",
+        title: "Execute Admin Plan",
+        description: "Execute an approved plan with riskLevel = 'admin'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_financial",
+        title: "Execute Financial Plan",
+        description: "Execute an approved plan with riskLevel = 'financial'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_provisioning",
+        title: "Execute Infrastructure Provisioning Plan",
+        description: "Execute an approved infrastructure provisioning plan with riskLevel = 'provisioning' via Stripe Projects.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "execute_destructive",
+        title: "Execute Destructive Plan",
+        description: "Execute an approved plan with riskLevel = 'destructive'.",
+        inputSchema: {
+            type: "object",
+            required: ["plan_id"],
+            properties: {
+                plan_id: { type: "string", description: "Plan ID (plan_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: true,
+        },
+    },
+    {
+        name: "get_run",
+        title: "Get Execution Run",
+        description: "Get the execution status, output, duration, and metered cost of a run (run_*).",
+        inputSchema: {
+            type: "object",
+            required: ["run_id"],
+            properties: {
+                run_id: { type: "string", description: "Run ID (run_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "cancel_run",
+        title: "Cancel Execution Run",
+        description: "Cancel an in-progress run and issue a cancellation receipt.",
+        inputSchema: {
+            type: "object",
+            required: ["run_id"],
+            properties: {
+                run_id: { type: "string", description: "Run ID (run_*)" },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "get_receipt",
+        title: "Verify Execution Receipt",
+        description: "Fetch and cryptographically verify the HMAC-SHA256 + Ed25519 chained execution receipt (rcpt_*) for a run.",
+        inputSchema: {
+            type: "object",
+            required: ["receipt_id"],
+            properties: {
+                receipt_id: {
+                    type: "string",
+                    description: "Receipt ID (rcpt_*) or Run ID (run_*)",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+];
+/**
+ * OpenAI Company Knowledge standard `search` and `fetch` tool definitions
+ * per https://developers.openai.com/plugins/build/mcp-server#company-knowledge-compatibility
+ */
+export const OPENAI_COMPANY_KNOWLEDGE_TOOLS = [
+    {
+        name: "search",
+        title: "Search Muxo Tools & Workspace Memory",
+        description: "Search across Muxo tools, provisioned cloud resources, and Supermemory v5 workspace knowledge.",
+        inputSchema: {
+            type: "object",
+            required: ["query"],
+            properties: {
+                query: { type: "string", description: "Search query string." },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+    {
+        name: "fetch",
+        title: "Fetch Muxo Tool or Memory Record",
+        description: "Retrieve complete details for a Muxo tool, resource, or workspace memory record by ID.",
+        inputSchema: {
+            type: "object",
+            required: ["id"],
+            properties: {
+                id: {
+                    type: "string",
+                    description: "Identifier returned by search (e.g. 'tool:instant.seo.audit' or 'memory:mem_123').",
+                },
+            },
+            additionalProperties: false,
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: false,
+        },
+    },
+];
+function sha256Digest(content) {
+    const hash = crypto
+        .createHash("sha256")
+        .update(Buffer.from(content, "utf8"))
+        .digest("hex");
+    return `sha256:${hash}`;
+}
+function parseFrontmatter(markdown) {
+    const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const result = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const idx = line.indexOf(":");
+        if (idx > 0) {
+            const k = line.slice(0, idx).trim();
+            const v = line.slice(idx + 1).trim();
+            if (k && v)
+                result[k] = v;
+        }
+    }
+    return result;
+}
+function readSkillFileOrDefault(relPath, fallback) {
+    try {
+        const absPath = path.join(ROOT_DIR, "plugins", "muxo", "skills", relPath);
+        if (fs.existsSync(absPath)) {
+            return fs.readFileSync(absPath, "utf8");
+        }
+    }
+    catch {
+        // Fallback to embedded markdown
+    }
+    return fallback;
+}
+export function getMuxoMcpSkills() {
+    const muxoSkillMd = readSkillFileOrDefault("muxo/SKILL.md", `---
+name: muxo
+description: Route governed Muxo work between the hosted MCP-backed app and the local Muxo CLI across Connected Apps (Composio), Instant Tools, Cloud Infrastructure (Stripe Projects), Supermemory v5, and Microsoft Agent Governance.
+---
+
+# Muxo
+
+Use \`search_tools\`, \`inspect_tool\`, \`plan_action\`, \`wait_for_connection\`, and \`execute_<risk>\` to run governed actions across Connected Apps (\`app.*\`), Instant Tools (\`instant.*\`), and Cloud Infrastructure (\`resource.*\`).
+`);
+    const muxoCliMd = readSkillFileOrDefault("muxo/references/cli.md", `# Local Muxo CLI\n\nRun \`muxo login --signup\`, \`muxo search\`, \`muxo link <provider> --wait\`, \`muxo exec\`, and \`muxo env pull\`.`);
+    const muxoMcpMd = readSkillFileOrDefault("muxo/references/mcp.md", `# Hosted Muxo MCP App\n\nFollow \`search_tools\` -> \`inspect_tool\` -> \`plan_action\` -> \`wait_for_connection\` -> \`execute_<risk>\` -> \`get_receipt\`.`);
+    const setupSkillMd = readSkillFileOrDefault("setup/SKILL.md", `---
+name: setup
+description: Guided onboarding skill for setting up the Muxo plugin in OpenAI ChatGPT and Codex. Helps users verify workspace authorization, connect external SaaS apps via OAuth handoff, provision cloud infrastructure, or install the local Muxo CLI.
+---
+
+# Muxo Onboarding & Setup
+
+Call \`get_profile\` and \`get_organization\` to verify your workspace connection, or run \`npx -y @muxoai/cli@latest login --signup\` in a terminal.
+`);
+    const muxoFm = parseFrontmatter(muxoSkillMd);
+    const setupFm = parseFrontmatter(setupSkillMd);
+    const muxoFiles = [
+        {
+            path: "SKILL.md",
+            uri: "skill://muxo/muxo/SKILL.md",
+            size: Buffer.byteLength(muxoSkillMd, "utf8"),
+            digest: sha256Digest(muxoSkillMd),
+            mimeType: "text/markdown",
+            content: muxoSkillMd,
+        },
+        {
+            path: "references/cli.md",
+            uri: "skill://muxo/muxo/references/cli.md",
+            size: Buffer.byteLength(muxoCliMd, "utf8"),
+            digest: sha256Digest(muxoCliMd),
+            mimeType: "text/markdown",
+            content: muxoCliMd,
+        },
+        {
+            path: "references/mcp.md",
+            uri: "skill://muxo/muxo/references/mcp.md",
+            size: Buffer.byteLength(muxoMcpMd, "utf8"),
+            digest: sha256Digest(muxoMcpMd),
+            mimeType: "text/markdown",
+            content: muxoMcpMd,
+        },
+    ];
+    const setupFiles = [
+        {
+            path: "SKILL.md",
+            uri: "skill://muxo/setup/SKILL.md",
+            size: Buffer.byteLength(setupSkillMd, "utf8"),
+            digest: sha256Digest(setupSkillMd),
+            mimeType: "text/markdown",
+            content: setupSkillMd,
+        },
+    ];
+    const muxoName = muxoFm.name || "muxo";
+    const muxoDesc = muxoFm.description ||
+        "Route governed Muxo work between the hosted MCP-backed app and the local Muxo CLI.";
+    const setupName = setupFm.name || "setup";
+    const setupDesc = setupFm.description ||
+        "Guided onboarding skill for setting up the Muxo plugin in OpenAI ChatGPT and Codex.";
+    return [
+        {
+            name: muxoName,
+            description: muxoDesc,
+            uri: "skill://muxo/muxo/SKILL.md",
+            version: muxoFiles[0].digest,
+            frontmatter: {
+                name: muxoName,
+                description: muxoDesc,
+            },
+            files: muxoFiles,
+        },
+        {
+            name: setupName,
+            description: setupDesc,
+            uri: "skill://muxo/setup/SKILL.md",
+            version: setupFiles[0].digest,
+            frontmatter: {
+                name: setupName,
+                description: setupDesc,
+            },
+            files: setupFiles,
+        },
+    ];
+}
+export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
+    switch (toolName) {
+        case "get_profile":
+            return engine.getProfile(ctx);
+        case "get_organization":
+            return engine.getOrganization(ctx);
+        case "search_tools":
+            return engine.searchTools({
+                query: args.query ? String(args.query) : undefined,
+                lane: args.lane || "all",
+                riskLevel: args.risk_level,
+                limit: args.limit ? Number(args.limit) : 20,
+            });
+        case "inspect_tool":
+            return engine.inspectTool(String(args.tool_slug || args.slug || ""));
+        case "connection_status":
+            return engine.connectionStatus(ctx, {
+                provider: args.provider ? String(args.provider) : undefined,
+                syncLive: args.sync_live !== false,
+            });
+        case "start_connection":
+            return engine.startConnection(ctx, {
+                provider: String(args.provider || ""),
+                lane: args.lane,
+                callbackUrl: args.callback_url ? String(args.callback_url) : undefined,
+            });
+        case "wait_for_connection":
+            return engine.waitForConnection(ctx, {
+                provider: String(args.provider || ""),
+                timeoutSeconds: args.timeout_seconds !== undefined
+                    ? Number(args.timeout_seconds)
+                    : 15,
+            });
+        case "plan_action":
+            return engine.planAction(ctx, {
+                toolSlug: String(args.tool_slug ||
+                    args.slug ||
+                    args.tool_id ||
+                    args.prompt ||
+                    args.instruction ||
+                    ""),
+                input: (args.input || args.arguments) || {},
+                reason: args.reason ? String(args.reason) : undefined,
+            });
+        case "get_plan":
+            return engine.getPlan(ctx, String(args.plan_id || ""));
+        case "get_run_context":
+            return engine.getRunContext(ctx, args.query ? String(args.query) : undefined);
+        case "execute_read":
+            return engine.executePlanForRisk(ctx, String(args.plan_id || ""), "read");
+        case "execute_write":
+            return engine.executePlanForRisk(ctx, String(args.plan_id || ""), "write");
+        case "execute_admin":
+            return engine.executePlanForRisk(ctx, String(args.plan_id || ""), "admin");
+        case "execute_financial":
+            return engine.executePlanForRisk(ctx, String(args.plan_id || ""), "financial");
+        case "execute_provisioning":
+            return engine.executePlanForRisk(ctx, String(args.plan_id || ""), "provisioning");
+        case "execute_destructive":
+            return engine.executePlanForRisk(ctx, String(args.plan_id || ""), "destructive");
+        case "get_run":
+            return engine.getRun(ctx, String(args.run_id || ""));
+        case "cancel_run":
+            return engine.cancelRun(ctx, String(args.run_id || ""));
+        case "get_receipt":
+            return engine.getReceipt(ctx, String(args.receipt_id || args.run_id || ""));
+        // OpenAI Company Knowledge standard `search` and `fetch` tool support
+        case "search": {
+            const q = String(args.query || "").trim();
+            const [toolsRes, memRes] = await Promise.all([
+                engine.searchTools({ query: q, limit: 10 }),
+                engine.getMemoryOverview(ctx, q),
+            ]);
+            const toolHits = toolsRes.tools.map((t) => ({
+                id: `tool:${t.slug}`,
+                title: `${t.name} (${t.slug})`,
+                url: t.providerUrl || `https://docs.muxo.ai/tools/${encodeURIComponent(t.slug)}`,
+                snippet: `${t.description} [lane=${t.lane}, risk=${t.riskLevel}, cost=${t.creditCost}cr]`,
+            }));
+            const memHits = (memRes.memories || []).slice(0, 5).map((m) => ({
+                id: `memory:${m.id}`,
+                title: m.title,
+                url: `https://app.muxo.ai/?memory=${encodeURIComponent(m.id)}`,
+                snippet: m.content.slice(0, 240),
+            }));
+            return {
+                results: [...toolHits, ...memHits],
+            };
+        }
+        case "fetch": {
+            const rawId = String(args.id || "").trim();
+            const slug = rawId.startsWith("tool:") ? rawId.slice(5) : rawId;
+            if (rawId.startsWith("memory:")) {
+                const memId = rawId.slice(7);
+                const memRes = await engine.getMemoryOverview(ctx);
+                const found = (memRes.memories || []).find((m) => m.id === memId);
+                if (!found)
+                    throw new Error(`Memory record not found: ${rawId}`);
+                return {
+                    id: rawId,
+                    title: found.title,
+                    text: found.content,
+                    url: `https://app.muxo.ai/?memory=${encodeURIComponent(found.id)}`,
+                    metadata: {
+                        namespace: found.namespace,
+                        kind: found.kind,
+                        createdAt: found.createdAt,
+                    },
+                };
+            }
+            const tool = await engine.inspectTool(slug);
+            return {
+                id: `tool:${tool.slug}`,
+                title: tool.name,
+                text: JSON.stringify(tool, null, 2),
+                url: tool.providerUrl ||
+                    `https://docs.muxo.ai/tools/${encodeURIComponent(tool.slug)}`,
+                metadata: {
+                    slug: tool.slug,
+                    lane: tool.lane,
+                    riskLevel: tool.riskLevel,
+                    creditCost: String(tool.creditCost),
+                },
+            };
+        }
+        default:
+            throw new Error(`Unknown MCP tool: ${toolName}`);
+    }
+}
+export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
+    const id = rpc.id ?? null;
+    const method = String(rpc.method || "");
+    const params = (rpc.params || {});
+    if (method === "notifications/initialized" ||
+        method.startsWith("notifications/")) {
+        return null;
+    }
+    try {
+        if (method === "initialize") {
+            const requestedProtocol = typeof params.protocolVersion === "string" &&
+                params.protocolVersion.trim()
+                ? params.protocolVersion.trim()
+                : "2025-06-18";
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    protocolVersion: requestedProtocol,
+                    instructions: MUXO_MCP_SERVER_INSTRUCTIONS,
+                    serverInfo: {
+                        name: "muxo-mcp-server",
+                        version: "1.3.0",
+                    },
+                    capabilities: {
+                        tools: { listChanged: false },
+                        resources: { listChanged: false },
+                        extensions: {
+                            "io.modelcontextprotocol/skills": {},
+                        },
+                    },
+                },
+            };
+        }
+        if (method === "ping") {
+            return { jsonrpc: "2.0", id, result: {} };
+        }
+        if (method === "tools/list") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    tools: MUXO_MCP_TOOLS,
+                },
+            };
+        }
+        if (method === "tools/call") {
+            const toolName = String(params.name || "");
+            const toolArgs = (params.arguments || {});
+            const output = await dispatchMcpToolCall(engine, ctx, toolName, toolArgs);
+            const structuredContent = output && typeof output === "object" && !Array.isArray(output)
+                ? output
+                : { data: output };
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    structuredContent,
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(output, null, 2),
+                        },
+                    ],
+                    isError: false,
+                },
+            };
+        }
+        // SEP-2640 Skills Import Extension (`io.modelcontextprotocol/skills`)
+        if (method === "skills/list") {
+            const skills = getMuxoMcpSkills().map((s) => ({
+                name: s.name,
+                description: s.description,
+                uri: s.uri,
+                version: s.version,
+                digest: s.files[0]?.digest || "",
+                files: s.files.length,
+            }));
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: { skills },
+            };
+        }
+        if (method === "skills/get") {
+            const requestedName = String(params.name || "muxo").trim();
+            const skill = getMuxoMcpSkills().find((s) => s.name === requestedName);
+            if (!skill) {
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    error: {
+                        code: -32602,
+                        message: `Skill not found: ${requestedName}`,
+                    },
+                };
+            }
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    skill: {
+                        name: skill.name,
+                        description: skill.description,
+                        uri: skill.uri,
+                        version: skill.version,
+                        digest: skill.files[0]?.digest || "",
+                    },
+                    frontmatter: skill.frontmatter,
+                    files: skill.files.map((f) => ({
+                        path: f.path,
+                        uri: f.uri,
+                        size: f.size,
+                        digest: f.digest,
+                        mimeType: f.mimeType,
+                    })),
+                },
+            };
+        }
+        if (method === "resources/list") {
+            const resources = getMuxoMcpSkills().flatMap((s) => s.files.map((f) => ({
+                uri: f.uri,
+                name: `${s.name}/${f.path}`,
+                description: s.description,
+                mimeType: f.mimeType,
+            })));
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: { resources },
+            };
+        }
+        if (method === "resources/read") {
+            const uri = String(params.uri || "").trim();
+            const allFiles = getMuxoMcpSkills().flatMap((s) => s.files);
+            const found = allFiles.find((f) => f.uri === uri);
+            if (!found) {
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    error: {
+                        code: -32602,
+                        message: `Resource not found: ${uri}`,
+                    },
+                };
+            }
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    contents: [
+                        {
+                            uri: found.uri,
+                            mimeType: found.mimeType,
+                            text: found.content,
+                        },
+                    ],
+                },
+            };
+        }
+        return {
+            jsonrpc: "2.0",
+            id,
+            error: {
+                code: -32601,
+                message: `Method not found: ${method}`,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            jsonrpc: "2.0",
+            id,
+            result: {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            error: String(err?.message || err || "MCP tool execution failed"),
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            },
+        };
+    }
+}