@muxoai/sdk 1.3.0 → 1.4.2

package/dist/mcp.js

@@ -2,474 +2,9 @@ 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,
-        },
-    },
-];
+import { APPROVED_PLAN_STATUSES, DEFAULT_LEGACY_MCP_PROTOCOL_VERSION, DEFAULT_TOOL_SECURITY_SCHEMES, LATEST_MCP_PROTOCOL_VERSION, MCP_ERR_HEADER_MISMATCH, MCP_ERR_MISSING_REQUIRED_CLIENT_CAPABILITY, MCP_ERR_UNSUPPORTED_PROTOCOL_VERSION, MUXO_MCP_RESOURCE_TEMPLATES, MUXO_MCP_SERVER_INSTRUCTIONS, MUXO_MCP_TOOLS, MUXO_UI_MCP_APP_URI, MUXO_UI_RESOURCES, MUXO_UI_WIDGET_URI, OPENAI_COMPANY_KNOWLEDGE_TOOLS, PUBLIC_MCP_TOOL_NAMES, PUBLIC_TOOL_SECURITY_SCHEMES, SUPPORTED_MCP_PROTOCOL_VERSIONS, UI_RENDERED_MCP_TOOL_NAMES, attachMcpHarnessGuidance, MuxoToolError, buildApprovalUrl, buildMcpDiscoverResult, buildMcpErrorResultMeta, buildMcpToolDescriptor, buildMcpToolResultMeta, buildOnboardTeamGuide, clampWaitSeconds, completeMcpArgument, decodeMcpHeaderValue, errorPayloadFrom, extractOpenAiClientMeta, findMcpSkill, isSupportedMcpProtocolVersion, renderMuxoUiWidgetHtml, securitySchemesForTool, validateMcpHttpHeadersAndMeta, } from "./mcp-schema.js";
+import { MUXO_VERSION } from "./version.js";
+export { DEFAULT_LEGACY_MCP_PROTOCOL_VERSION, DEFAULT_TOOL_SECURITY_SCHEMES, LATEST_MCP_PROTOCOL_VERSION, MCP_ERR_HEADER_MISMATCH, MCP_ERR_MISSING_REQUIRED_CLIENT_CAPABILITY, MCP_ERR_UNSUPPORTED_PROTOCOL_VERSION, MUXO_MCP_RESOURCE_TEMPLATES, MUXO_MCP_SERVER_INSTRUCTIONS, MUXO_MCP_TOOLS, MUXO_UI_MCP_APP_URI, MUXO_UI_RESOURCES, MUXO_UI_WIDGET_URI, OPENAI_COMPANY_KNOWLEDGE_TOOLS, PUBLIC_MCP_TOOL_NAMES, PUBLIC_TOOL_SECURITY_SCHEMES, SUPPORTED_MCP_PROTOCOL_VERSIONS, UI_RENDERED_MCP_TOOL_NAMES, attachMcpHarnessGuidance, buildMcpDiscoverResult, buildMcpErrorResultMeta, buildMcpToolDescriptor, buildMcpToolResultMeta, completeMcpArgument, decodeMcpHeaderValue, extractOpenAiClientMeta, isSupportedMcpProtocolVersion, renderMuxoUiWidgetHtml, securitySchemesForTool, validateMcpHttpHeadersAndMeta, };
 function sha256Digest(content) {
     const hash = crypto
         .createHash("sha256")
@@ -508,7 +43,7 @@ function readSkillFileOrDefault(relPath, 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.
+description: Route governed Muxo work between the hosted MCP-backed app and the local Muxo CLI across Muxo Connected Apps, Instant Tools, Cloud Infrastructure (Stripe Projects), Supermemory v5, and Microsoft Agent Governance.
 ---
 
 # Muxo
@@ -526,6 +61,8 @@ description: Guided onboarding skill for setting up the Muxo plugin in OpenAI Ch
 
 Call \`get_profile\` and \`get_organization\` to verify your workspace connection, or run \`npx -y @muxoai/cli@latest login --signup\` in a terminal.
 `);
+    const muxoOpenaiYaml = readSkillFileOrDefault("muxo/agents/openai.yaml", `interface:\n  display_name: "Muxo"\n  short_description: "Governed SaaS, Instant Web/SEO tools, Cloud Infrastructure, and Workspace Memory"\n  default_prompt: "Audit https://muxo.ai for technical SEO and crawl its top pages."\n\ndependencies:\n  tools:\n    - type: "mcp"\n      value: "muxo"\n      description: "Muxo Governed Execution, Instant Web/SEO Tools, Connected Apps, and Cloud Infrastructure MCP Server"\n      transport: "streamable_http"\n      url: "https://api.muxo.ai/mcp"\n`);
+    const setupOpenaiYaml = readSkillFileOrDefault("setup/agents/openai.yaml", `interface:\n  display_name: "Muxo Setup"\n  short_description: "Guided onboarding and connection verification for Muxo in ChatGPT and Codex"\n  default_prompt: "Check my Muxo profile and organization status."\n\ndependencies:\n  tools:\n    - type: "mcp"\n      value: "muxo"\n      description: "Muxo Governed Execution, Instant Web/SEO Tools, Connected Apps, and Cloud Infrastructure MCP Server"\n      transport: "streamable_http"\n      url: "https://api.muxo.ai/mcp"\n`);
     const muxoFm = parseFrontmatter(muxoSkillMd);
     const setupFm = parseFrontmatter(setupSkillMd);
     const muxoFiles = [
@@ -537,6 +74,14 @@ Call \`get_profile\` and \`get_organization\` to verify your workspace connectio
             mimeType: "text/markdown",
             content: muxoSkillMd,
         },
+        {
+            path: "agents/openai.yaml",
+            uri: "skill://muxo/muxo/agents/openai.yaml",
+            size: Buffer.byteLength(muxoOpenaiYaml, "utf8"),
+            digest: sha256Digest(muxoOpenaiYaml),
+            mimeType: "application/yaml",
+            content: muxoOpenaiYaml,
+        },
         {
             path: "references/cli.md",
             uri: "skill://muxo/muxo/references/cli.md",
@@ -563,6 +108,14 @@ Call \`get_profile\` and \`get_organization\` to verify your workspace connectio
             mimeType: "text/markdown",
             content: setupSkillMd,
         },
+        {
+            path: "agents/openai.yaml",
+            uri: "skill://muxo/setup/agents/openai.yaml",
+            size: Buffer.byteLength(setupOpenaiYaml, "utf8"),
+            digest: sha256Digest(setupOpenaiYaml),
+            mimeType: "application/yaml",
+            content: setupOpenaiYaml,
+        },
     ];
     const muxoName = muxoFm.name || "muxo";
     const muxoDesc = muxoFm.description ||
@@ -615,18 +168,22 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
                 provider: args.provider ? String(args.provider) : undefined,
                 syncLive: args.sync_live !== false,
             });
-        case "start_connection":
-            return engine.startConnection(ctx, {
+        case "start_connection": {
+            const conn = await engine.startConnection(ctx, {
                 provider: String(args.provider || ""),
                 lane: args.lane,
                 callbackUrl: args.callback_url ? String(args.callback_url) : undefined,
             });
+            return {
+                ok: true,
+                ...conn,
+                connection: conn,
+            };
+        }
         case "wait_for_connection":
             return engine.waitForConnection(ctx, {
                 provider: String(args.provider || ""),
-                timeoutSeconds: args.timeout_seconds !== undefined
-                    ? Number(args.timeout_seconds)
-                    : 15,
+                timeoutSeconds: clampWaitSeconds(args.timeout_seconds),
             });
         case "plan_action":
             return engine.planAction(ctx, {
@@ -640,9 +197,157 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
                 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);
+            if (args.wait_for_approval === true || args.wait === true) {
+                return engine.waitForPlanApproval(ctx, {
+                    planId: String(args.plan_id || ""),
+                    timeoutSeconds: clampWaitSeconds(args.timeout_seconds, 15, 60),
+                });
+            }
+            {
+                const plan = engine.getPlan(ctx, String(args.plan_id || ""));
+                return {
+                    ok: true,
+                    approved: APPROVED_PLAN_STATUSES.has(plan.approvalStatus),
+                    timedOut: false,
+                    plan,
+                    approvalStatus: plan.approvalStatus,
+                    approvalUrl: buildApprovalUrl(engine.config.baseUrl, plan.id),
+                };
+            }
+        case "get_run_context": {
+            const action = String(args.action || "").trim().toLowerCase();
+            const prompt = String(args.prompt || "").trim();
+            const query = args.query ? String(args.query) : undefined;
+            const rawParamRules = Array.isArray(args.parameter_rules)
+                ? args.parameter_rules
+                : Array.isArray(args.parameterRules)
+                    ? args.parameterRules
+                    : undefined;
+            if (action === "memory_graph") {
+                return engine.getMemoryGraph(ctx, query);
+            }
+            if (action === "governance_status") {
+                return engine.getGovernanceOverview(ctx);
+            }
+            if (action === "list_workspaces") {
+                const workspaces = engine.store.listUserWorkspaces(ctx.user.id, ctx.workspace.id);
+                return {
+                    ok: true,
+                    action,
+                    currentWorkspaceId: ctx.workspace.id,
+                    activeWorkspace: workspaces.find((w) => w.id === ctx.workspace.id) || {
+                        id: ctx.workspace.id,
+                        name: ctx.workspace.name,
+                        slug: ctx.workspace.slug,
+                        tier: ctx.workspace.tier,
+                    },
+                    workspaces,
+                };
+            }
+            if (action === "switch_workspace") {
+                const targetWsId = String(args.workspace_id || query || prompt || "").trim();
+                if (!targetWsId) {
+                    throw new Error("workspace_id is required when action='switch_workspace'");
+                }
+                const switched = engine.store.switchUserWorkspace(ctx.user.id, targetWsId);
+                if (!switched) {
+                    throw new Error(`Workspace ${targetWsId} not found or not linked to your account. Call get_run_context with action='list_workspaces' to see accessible workspaces.`);
+                }
+                return {
+                    ok: true,
+                    action,
+                    switched: true,
+                    workspaceId: switched.workspace.id,
+                    workspace: switched.workspace,
+                    workspaces: engine.store.listUserWorkspaces(ctx.user.id, switched.workspace.id),
+                    message: `Active workspace for your session is now ${switched.workspace.name} (${switched.workspace.id}). API keys stay bound to their own workspace; use a key minted for ${switched.workspace.id} to target it over MCP.`,
+                };
+            }
+            if (action === "onboard_team") {
+                return buildOnboardTeamGuide({
+                    baseUrl: engine.config.baseUrl,
+                    workspaceId: ctx.workspace.id,
+                    workspaceName: ctx.workspace.name,
+                    teamName: String(args.team_name || args.teamName || query || prompt || "").trim(),
+                    workspaces: engine.store.listUserWorkspaces(ctx.user.id, ctx.workspace.id),
+                });
+            }
+            if (action === "set_guardrail" &&
+                (prompt || (rawParamRules && rawParamRules.length > 0))) {
+                return engine.applyNaturalLanguageGuardrail(ctx, prompt, {
+                    parameterRules: rawParamRules,
+                    source: rawParamRules ? "mcp_harness" : "deterministic",
+                });
+            }
+            if (action === "reset_guardrails") {
+                return engine.resetWorkspaceGuardrails(ctx);
+            }
+            if (action === "check_policy" || action === "simulate_policy") {
+                const toolSlug = String(args.tool_slug || args.slug || args.tool_id || query || prompt || "instant.web.search").trim();
+                const input = (args.input || args.arguments) || {};
+                return engine.checkToolPolicy(ctx, { toolSlug, input });
+            }
+            if (action === "kill_switch") {
+                const enabled = typeof args.enabled === "boolean"
+                    ? args.enabled
+                    : typeof args.active === "boolean"
+                        ? args.active
+                        : !/\b(resume|unpause|disable|off|false)\b/i.test(prompt || query || "");
+                const reason = prompt ||
+                    query ||
+                    (enabled ? "Paused via MCP get_run_context" : undefined);
+                const updated = engine.setKillSwitch(ctx, enabled, reason);
+                const govOverview = engine.getGovernanceOverview(ctx);
+                return {
+                    ok: true,
+                    action: "kill_switch",
+                    killSwitchActive: Boolean(updated.policy.killSwitchActive),
+                    killSwitchReason: updated.policy.killSwitchReason || null,
+                    policy: updated.policy,
+                    llmPolicyBrief: govOverview.llmPolicyBrief,
+                    explanation: govOverview.explanation,
+                };
+            }
+            if (action === "scan_context") {
+                const textToScan = String(args.content || prompt || query || "");
+                return engine.scanForContextPoisoning(ctx.workspace.id, textToScan);
+            }
+            if (action === "forget") {
+                if (!(query || prompt)) {
+                    throw new Error("query is required when action='forget'");
+                }
+                return engine.forgetWorkspaceMemoryMatching(ctx, query || prompt);
+            }
+            if (action === "recall") {
+                return engine.getMemoryOverview(ctx, query);
+            }
+            if (action === "remember") {
+                if (prompt && !args.content) {
+                    return engine.doNaturalLanguage(ctx, { prompt });
+                }
+                const record = await engine.addWorkspaceMemory(ctx, {
+                    title: String(args.title || prompt.slice(0, 60) || "Workspace Fact"),
+                    content: String(args.content || prompt || query || ""),
+                    kind: "fact",
+                });
+                const overview = await engine.getMemoryOverview(ctx);
+                return {
+                    ok: true,
+                    memory: record,
+                    activeDefaults: overview.activeDefaults,
+                    explanation: overview.explanation,
+                };
+            }
+            if (prompt && !action) {
+                return engine.doNaturalLanguage(ctx, { prompt });
+            }
+            const runCtx = await engine.getRunContext(ctx, query);
+            if (args.include_graph === true) {
+                const memoryGraph = await engine.getMemoryGraph(ctx, query);
+                return { ...runCtx, memoryGraph };
+            }
+            return runCtx;
+        }
         case "execute_read":
             return engine.executePlanForRisk(ctx, String(args.plan_id || ""), "read");
         case "execute_write":
@@ -658,9 +363,125 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
         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 || ""));
+            return engine.cancelRun(ctx, String(args.run_id || ""), args.reason ? String(args.reason) : undefined);
+        case "get_receipt": {
+            const targetId = String(args.receipt_id || args.run_id || "latest").trim();
+            if (targetId === "chain") {
+                return engine.verifyReceiptChain(ctx);
+            }
+            const verified = engine.getReceipt(ctx, targetId);
+            if (args.verify_chain === true) {
+                const receiptChain = engine.verifyReceiptChain(ctx);
+                return { ...verified, receiptChain };
+            }
+            return verified;
+        }
+        // Supermemory MCP & Governance direct tool aliases for agent harness interoperability
+        case "who_am_i":
+            return engine.getProfile(ctx);
+        case "list_spaces": {
+            const overview = await engine.getMemoryOverview(ctx);
+            return {
+                activeSpace: overview.namespace,
+                spaces: [
+                    {
+                        id: overview.namespace,
+                        containerTag: overview.namespace,
+                        workspaceId: ctx.workspace.id,
+                        workspaceName: ctx.workspace.name,
+                        active: true,
+                    },
+                ],
+            };
+        }
+        case "search_memory":
+        case "list_memories":
+            return engine.getMemoryOverview(ctx, args.query ? String(args.query) : undefined);
+        case "add_memory":
+        case "remember": {
+            const prompt = String(args.prompt || "").trim();
+            if (prompt && !args.content) {
+                return engine.doNaturalLanguage(ctx, { prompt });
+            }
+            const content = String(args.content || args.memory || prompt || "");
+            const title = String(args.title || content.slice(0, 60) || "Workspace Memory");
+            const record = await engine.addWorkspaceMemory(ctx, {
+                title,
+                content,
+                kind: args.kind || "fact",
+            });
+            const overview = await engine.getMemoryOverview(ctx);
+            return {
+                ok: true,
+                memory: record,
+                activeDefaults: overview.activeDefaults,
+                explanation: overview.explanation,
+            };
+        }
+        case "forget_memory": {
+            const query = String(args.query || args.id || args.memory || "").trim();
+            if (!query)
+                throw new Error("query is required to forget a memory");
+            return engine.forgetWorkspaceMemoryMatching(ctx, query);
+        }
+        case "memory_graph":
+            return engine.getMemoryGraph(ctx, args.query ? String(args.query) : undefined);
+        case "set_guardrail":
+        case "configure_guardrails": {
+            const rawParamRules = Array.isArray(args.parameter_rules)
+                ? args.parameter_rules
+                : Array.isArray(args.parameterRules)
+                    ? args.parameterRules
+                    : undefined;
+            return engine.applyNaturalLanguageGuardrail(ctx, String(args.prompt || args.rule || args.instruction || ""), {
+                parameterRules: rawParamRules,
+                source: rawParamRules ? "mcp_harness" : "deterministic",
+            });
+        }
+        case "reset_guardrails":
+            return engine.resetWorkspaceGuardrails(ctx);
+        case "check_policy":
+        case "simulate_policy":
+            return engine.checkToolPolicy(ctx, {
+                toolSlug: String(args.tool_slug || args.slug || args.tool_id || args.query || "instant.web.search"),
+                input: (args.input || args.arguments) || {},
+            });
+        case "kill_switch": {
+            const enabled = typeof args.enabled === "boolean"
+                ? args.enabled
+                : typeof args.active === "boolean"
+                    ? args.active
+                    : true;
+            const reason = args.reason
+                ? String(args.reason)
+                : args.prompt
+                    ? String(args.prompt)
+                    : undefined;
+            const updated = engine.setKillSwitch(ctx, enabled, reason);
+            const govOverview = engine.getGovernanceOverview(ctx);
+            return {
+                ok: true,
+                action: "kill_switch",
+                killSwitchActive: Boolean(updated.policy.killSwitchActive),
+                killSwitchReason: updated.policy.killSwitchReason || null,
+                policy: updated.policy,
+                llmPolicyBrief: govOverview.llmPolicyBrief,
+                explanation: govOverview.explanation,
+            };
+        }
+        case "scan_context":
+            return engine.scanForContextPoisoning(ctx.workspace.id, String(args.content || args.prompt || args.query || ""));
+        case "governance_status":
+            return engine.getGovernanceOverview(ctx);
+        case "verify_receipt_chain":
+            return engine.verifyReceiptChain(ctx, args.limit ? Number(args.limit) : 100);
+        case "do":
+            return engine.doNaturalLanguage(ctx, {
+                prompt: String(args.prompt || args.instruction || args.query || ""),
+                input: args.input || undefined,
+                dryRun: Boolean(args.dry_run || args.dryRun),
+                autoApprove: args.auto_approve !== false && args.autoApprove !== false,
+            });
         // OpenAI Company Knowledge standard `search` and `fetch` tool support
         case "search": {
             const q = String(args.query || "").trim();
@@ -671,7 +492,7 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
             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)}`,
+                url: t.providerUrl || `https://docs.muxo.ai/catalogue#${encodeURIComponent(t.providerSlug || t.slug)}`,
                 snippet: `${t.description} [lane=${t.lane}, risk=${t.riskLevel}, cost=${t.creditCost}cr]`,
             }));
             const memHits = (memRes.memories || []).slice(0, 5).map((m) => ({
@@ -711,7 +532,7 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
                 title: tool.name,
                 text: JSON.stringify(tool, null, 2),
                 url: tool.providerUrl ||
-                    `https://docs.muxo.ai/tools/${encodeURIComponent(tool.slug)}`,
+                    `https://docs.muxo.ai/catalogue#${encodeURIComponent(tool.providerSlug || tool.slug)}`,
                 metadata: {
                     slug: tool.slug,
                     lane: tool.lane,
@@ -721,7 +542,7 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
             };
         }
         default:
-            throw new Error(`Unknown MCP tool: ${toolName}`);
+            throw new MuxoToolError(`Unknown MCP tool: '${toolName}'. Call tools/list for the canonical Muxo MCP tools.`, { code: "unknown_mcp_tool", statusCode: 404, payload: { toolName } });
     }
 }
 export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
@@ -732,55 +553,270 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
         method.startsWith("notifications/")) {
         return null;
     }
+    const headerAndMetaCheck = validateMcpHttpHeadersAndMeta({}, rpc);
+    if (!headerAndMetaCheck.ok) {
+        return {
+            jsonrpc: "2.0",
+            id,
+            error: headerAndMetaCheck.error,
+        };
+    }
     try {
+        if (method === "server/discover") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: buildMcpDiscoverResult(MUXO_VERSION),
+            };
+        }
         if (method === "initialize") {
-            const requestedProtocol = typeof params.protocolVersion === "string" &&
-                params.protocolVersion.trim()
-                ? params.protocolVersion.trim()
-                : "2025-06-18";
+            const requestedProtocol = headerAndMetaCheck.protocolVersion;
+            const serverInfo = {
+                name: "muxo-mcp-server",
+                title: "Muxo Unified Agent Runtime & Governance MCP Server",
+                version: MUXO_VERSION,
+            };
             return {
                 jsonrpc: "2.0",
                 id,
                 result: {
+                    resultType: "complete",
                     protocolVersion: requestedProtocol,
+                    supportedVersions: [...SUPPORTED_MCP_PROTOCOL_VERSIONS],
                     instructions: MUXO_MCP_SERVER_INSTRUCTIONS,
-                    serverInfo: {
-                        name: "muxo-mcp-server",
-                        version: "1.3.0",
-                    },
+                    serverInfo,
                     capabilities: {
                         tools: { listChanged: false },
-                        resources: { listChanged: false },
+                        resources: { listChanged: false, subscribe: false },
+                        prompts: { listChanged: false },
+                        completions: {},
                         extensions: {
                             "io.modelcontextprotocol/skills": {},
+                            "io.modelcontextprotocol/apps": {},
                         },
                     },
+                    _meta: {
+                        "io.modelcontextprotocol/serverInfo": serverInfo,
+                        "io.modelcontextprotocol/instructions": MUXO_MCP_SERVER_INSTRUCTIONS,
+                    },
                 },
             };
         }
         if (method === "ping") {
-            return { jsonrpc: "2.0", id, result: {} };
+            return { jsonrpc: "2.0", id, result: { resultType: "complete" } };
+        }
+        if (method === "completion/complete") {
+            const catalogTools = await engine.searchTools({ lane: "all", limit: 100 });
+            const completion = completeMcpArgument(params, catalogTools.tools.map((t) => t.slug));
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    resultType: "complete",
+                    completion,
+                },
+            };
+        }
+        if (method === "subscriptions/listen") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    resultType: "complete",
+                    events: [],
+                    ttlMs: 30_000,
+                    cacheScope: "private",
+                },
+            };
+        }
+        if (method === "prompts/list") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    resultType: "complete",
+                    ttlMs: 300_000,
+                    cacheScope: "public",
+                    prompts: [
+                        {
+                            name: "context",
+                            title: "Workspace Memory & Governance Context",
+                            description: "Ready-to-attach workspace context (Supermemory v5 profile, bi-temporal facts, learned parameter defaults, and active Microsoft Governance guardrails).",
+                            arguments: [
+                                {
+                                    name: "query",
+                                    description: "Optional topic or task query to focus memory recall",
+                                    required: false,
+                                },
+                            ],
+                        },
+                        {
+                            name: "governed_execution",
+                            title: "Governed Tool Execution Workflow",
+                            description: "Step-by-step assistant prompt for discovering, planning, approving, executing, and verifying a governed Muxo action.",
+                            arguments: [
+                                {
+                                    name: "task",
+                                    description: "Natural-language task to plan and execute",
+                                    required: false,
+                                },
+                            ],
+                        },
+                        {
+                            name: "security_audit",
+                            title: "Workspace Governance, Memory Graph & Receipt Chain Audit",
+                            description: "Inspect the workspace's 9-module Microsoft Agent Governance posture, Bi-Temporal Knowledge Graph, and Ed25519 AgenticReceipt hash chain.",
+                            arguments: [],
+                        },
+                        {
+                            name: "policy_guardrails",
+                            title: "Workspace Policy, Parameter Guardrails & Risk Matrix",
+                            description: "Load the structured LLM Policy & Governance Brief (riskLaneMatrix, conditional parameterRules with compliance guidance, budget caps, kill switch status, and control-plane commands).",
+                            arguments: [],
+                        },
+                    ],
+                },
+            };
+        }
+        if (method === "prompts/get") {
+            const promptName = String(params.name || "context").trim();
+            const promptArgs = (params.arguments || {});
+            if (promptName === "context") {
+                const query = promptArgs.query ? String(promptArgs.query) : undefined;
+                const runCtx = await engine.getRunContext(ctx, query);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        description: "Ready-to-attach Muxo workspace memory, active defaults, and safety guardrails.",
+                        messages: [
+                            {
+                                role: "user",
+                                content: {
+                                    type: "text",
+                                    text: String(runCtx.llmSystemPrompt || runCtx.explanation.preferred),
+                                },
+                            },
+                        ],
+                    },
+                };
+            }
+            if (promptName === "policy_guardrails") {
+                const gov = engine.getGovernanceOverview(ctx);
+                const sections = [
+                    gov.llmPolicyBrief.llmSystemDirective,
+                    `### Structured LLM Policy Brief (JSON)\n\`\`\`json\n${JSON.stringify(gov.llmPolicyBrief, null, 2)}\n\`\`\``,
+                ];
+                if (promptArgs.tool_slug) {
+                    const sim = await engine.checkToolPolicy(ctx, {
+                        toolSlug: String(promptArgs.tool_slug),
+                    });
+                    sections.push(`### Dry-Run Policy Check for \`${sim.toolSlug}\`\n\`\`\`json\n${JSON.stringify(sim, null, 2)}\n\`\`\``);
+                }
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        description: "Workspace policy, conditional parameter guardrails, and risk-lane matrix for AI agents",
+                        messages: [
+                            {
+                                role: "user",
+                                content: {
+                                    type: "text",
+                                    text: sections.join("\n\n"),
+                                },
+                            },
+                        ],
+                    },
+                };
+            }
+            if (promptName === "governed_execution") {
+                const task = String(promptArgs.task || "the user's requested operation");
+                const runCtx = await engine.getRunContext(ctx);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        description: "Governed Muxo execution workflow prompt",
+                        messages: [
+                            {
+                                role: "user",
+                                content: {
+                                    type: "text",
+                                    text: `${runCtx.llmSystemPrompt}\n\n## Task\nExecute "${task}" safely using Muxo:\n1. Call \`search_tools\` and \`inspect_tool\` (or pass a natural-language request to \`plan_action\`).\n2. Call \`plan_action\` and inspect \`plan.approvalStatus\`, \`authHandoff\`, and \`llmGuidance.nextToolCalls\`.\n3. If \`authHandoff.required\` is true, present \`humanHandoff.markdownForUser\` and call \`wait_for_connection\`.\n4. If \`approvalStatus === "pending_approval"\`, present \`humanHandoff.markdownForUser\` and call \`get_plan\` with \`wait_for_approval: true\`.\n5. Execute with \`execute_<riskLevel>\` and verify the cryptographic receipt with \`get_receipt\`.`,
+                                },
+                            },
+                        ],
+                    },
+                };
+            }
+            if (promptName === "security_audit") {
+                const [gov, graph, chain] = await Promise.all([
+                    Promise.resolve(engine.getGovernanceOverview(ctx)),
+                    engine.getMemoryGraph(ctx),
+                    Promise.resolve(engine.verifyReceiptChain(ctx)),
+                ]);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        description: "Workspace governance, bi-temporal graph, and receipt chain audit",
+                        messages: [
+                            {
+                                role: "user",
+                                content: {
+                                    type: "text",
+                                    text: [
+                                        `# Muxo Security, Memory & Cryptographic Audit`,
+                                        `## 1. Microsoft Agent Governance (9 Modules)\n${gov.explanation.preferred}`,
+                                        `## 2. Bi-Temporal Knowledge Graph\n${graph.explanation.preferred}\n\`\`\`mermaid\n${graph.mermaid}\n\`\`\``,
+                                        `## 3. Portable Ed25519 AgenticReceipt Chain\n${chain.explanation.preferred}`,
+                                    ].join("\n\n"),
+                                },
+                            },
+                        ],
+                    },
+                };
+            }
+            return {
+                jsonrpc: "2.0",
+                id,
+                error: {
+                    code: -32602,
+                    message: `Prompt not found: ${promptName}`,
+                },
+            };
         }
         if (method === "tools/list") {
             return {
                 jsonrpc: "2.0",
                 id,
                 result: {
-                    tools: MUXO_MCP_TOOLS,
+                    resultType: "complete",
+                    ttlMs: 300_000,
+                    cacheScope: "public",
+                    tools: MUXO_MCP_TOOLS.map((t) => buildMcpToolDescriptor(t)),
                 },
             };
         }
         if (method === "tools/call") {
             const toolName = String(params.name || "");
             const toolArgs = (params.arguments || {});
-            const output = await dispatchMcpToolCall(engine, ctx, toolName, toolArgs);
+            const rawOutput = await dispatchMcpToolCall(engine, ctx, toolName, toolArgs);
+            const output = attachMcpHarnessGuidance(toolName, toolArgs, rawOutput);
             const structuredContent = output && typeof output === "object" && !Array.isArray(output)
                 ? output
                 : { data: output };
+            const resultMeta = buildMcpToolResultMeta(toolName, params);
             return {
                 jsonrpc: "2.0",
                 id,
                 result: {
+                    resultType: "complete",
                     structuredContent,
                     content: [
                         {
@@ -788,6 +824,7 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
                             text: JSON.stringify(output, null, 2),
                         },
                     ],
+                    ...(resultMeta ? { _meta: resultMeta } : {}),
                     isError: false,
                 },
             };
@@ -795,9 +832,14 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
         // SEP-2640 Skills Import Extension (`io.modelcontextprotocol/skills`)
         if (method === "skills/list") {
             const skills = getMuxoMcpSkills().map((s) => ({
+                uri: s.uri,
+                frontmatter: s.frontmatter,
+                resources: s.files.map((f) => ({
+                    uri: f.uri,
+                    digest: f.digest,
+                })),
                 name: s.name,
                 description: s.description,
-                uri: s.uri,
                 version: s.version,
                 digest: s.files[0]?.digest || "",
                 files: s.files.length,
@@ -805,34 +847,49 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
             return {
                 jsonrpc: "2.0",
                 id,
-                result: { skills },
+                result: {
+                    resultType: "complete",
+                    ttlMs: 300_000,
+                    cacheScope: "public",
+                    skills,
+                },
             };
         }
         if (method === "skills/get") {
-            const requestedName = String(params.name || "muxo").trim();
-            const skill = getMuxoMcpSkills().find((s) => s.name === requestedName);
+            const { skill, requested } = findMcpSkill(getMuxoMcpSkills(), params);
             if (!skill) {
                 return {
                     jsonrpc: "2.0",
                     id,
                     error: {
                         code: -32602,
-                        message: `Skill not found: ${requestedName}`,
+                        message: `Skill not found: ${requested}`,
                     },
                 };
             }
+            const resources = skill.files.map((f) => ({
+                uri: f.uri,
+                digest: f.digest,
+            }));
             return {
                 jsonrpc: "2.0",
                 id,
                 result: {
+                    resultType: "complete",
+                    ttlMs: 300_000,
+                    cacheScope: "public",
                     skill: {
+                        uri: skill.uri,
+                        frontmatter: skill.frontmatter,
+                        resources,
                         name: skill.name,
                         description: skill.description,
-                        uri: skill.uri,
                         version: skill.version,
                         digest: skill.files[0]?.digest || "",
                     },
+                    uri: skill.uri,
                     frontmatter: skill.frontmatter,
+                    resources,
                     files: skill.files.map((f) => ({
                         path: f.path,
                         uri: f.uri,
@@ -843,21 +900,401 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
                 },
             };
         }
+        if (method === "resources/templates/list") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    resultType: "complete",
+                    ttlMs: 300_000,
+                    cacheScope: "public",
+                    resourceTemplates: MUXO_MCP_RESOURCE_TEMPLATES,
+                },
+            };
+        }
         if (method === "resources/list") {
-            const resources = getMuxoMcpSkills().flatMap((s) => s.files.map((f) => ({
+            const skillResources = getMuxoMcpSkills().flatMap((s) => s.files.map((f) => ({
                 uri: f.uri,
                 name: `${s.name}/${f.path}`,
                 description: s.description,
                 mimeType: f.mimeType,
             })));
+            const dynamicResources = [
+                {
+                    uri: "muxo://profile",
+                    name: "Workspace Profile & Active Memory Defaults",
+                    description: "Stable and recent Supermemory v5 profile context, active auto-fill defaults, and Ed25519 Agent DID for the active workspace.",
+                    mimeType: "application/json",
+                },
+                {
+                    uri: "supermemory://profile",
+                    name: "Supermemory Active Space Profile",
+                    description: "Supermemory MCP compatible profile resource (static + dynamic facts and preferences) for the active workspace.",
+                    mimeType: "application/json",
+                },
+                {
+                    uri: "supermemory://spaces",
+                    name: "Supermemory Accessible Spaces",
+                    description: "Compact list of accessible workspace memory spaces with the active containerTag marked.",
+                    mimeType: "application/json",
+                },
+                {
+                    uri: "muxo://context",
+                    name: "Governed Workspace Run Context",
+                    description: "Ready-to-inject workspace context including guardrails, learned defaults, provisioned cloud resources, and Supermemory recall.",
+                    mimeType: "application/json",
+                },
+                {
+                    uri: "muxo://memory/graph",
+                    name: "Bi-Temporal Knowledge Graph",
+                    description: "Entity & relationship graph with active facts, superseded historical facts (validFrom/validTo), and Mermaid topology.",
+                    mimeType: "application/json",
+                },
+                {
+                    uri: "muxo://governance/policy",
+                    name: "Microsoft Agent Governance & Guardrails",
+                    description: "9-module Microsoft Agent Governance status, plain-English guardrails, Bayesian trust score, and OWASP ASI-06 scan status.",
+                    mimeType: "application/json",
+                },
+                {
+                    uri: "muxo://policy/brief",
+                    name: "LLM Policy, Risk Matrix & Parameter Guardrails Brief",
+                    description: "Structured LLM policy digest with riskLaneMatrix, conditional parameterRules compliance guidance, learned memory defaults, and control-plane commands.",
+                    mimeType: "application/json",
+                },
+                {
+                    uri: "muxo://receipts/chain",
+                    name: "Cryptographic AgenticReceipt Hash Chain",
+                    description: "Tamper-evident SHA-256 + portable Ed25519 AgenticReceipt chain verification report.",
+                    mimeType: "application/json",
+                },
+            ];
             return {
                 jsonrpc: "2.0",
                 id,
-                result: { resources },
+                result: {
+                    resultType: "complete",
+                    ttlMs: 60_000,
+                    cacheScope: "private",
+                    resources: [...MUXO_UI_RESOURCES, ...skillResources, ...dynamicResources],
+                },
             };
         }
         if (method === "resources/read") {
             const uri = String(params.uri || "").trim();
+            const uiResource = MUXO_UI_RESOURCES.find((r) => r.uri === uri);
+            if (uiResource) {
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        ttlMs: 300_000,
+                        cacheScope: "public",
+                        contents: [
+                            {
+                                uri: uiResource.uri,
+                                mimeType: uiResource.mimeType,
+                                text: renderMuxoUiWidgetHtml(),
+                                _meta: uiResource._meta,
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri === "muxo://profile" || uri === "supermemory://profile") {
+                const overview = await engine.getMemoryOverview(ctx);
+                const profile = engine.getProfile(ctx);
+                const payload = {
+                    uri,
+                    workspaceId: ctx.workspace.id,
+                    workspaceSlug: ctx.workspace.slug,
+                    namespace: overview.namespace,
+                    profile: overview.context.profile,
+                    activeDefaults: overview.activeDefaults,
+                    activeGuardrails: overview.activeGuardrails,
+                    actor: profile,
+                    explanation: overview.explanation,
+                };
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        ttlMs: 60_000,
+                        cacheScope: "private",
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(payload, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri === "muxo://spaces" || uri === "supermemory://spaces") {
+                const overview = await engine.getMemoryOverview(ctx);
+                const payload = {
+                    activeSpace: overview.namespace,
+                    spaces: [
+                        {
+                            id: overview.namespace,
+                            containerTag: overview.namespace,
+                            workspaceId: ctx.workspace.id,
+                            workspaceName: ctx.workspace.name,
+                            active: true,
+                        },
+                    ],
+                };
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        ttlMs: 60_000,
+                        cacheScope: "private",
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(payload, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri === "muxo://context") {
+                const runCtx = await engine.getRunContext(ctx);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        ttlMs: 60_000,
+                        cacheScope: "private",
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(runCtx, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri === "muxo://memory/graph") {
+                const graph = await engine.getMemoryGraph(ctx);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        ttlMs: 60_000,
+                        cacheScope: "private",
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(graph, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri === "muxo://governance/policy") {
+                const gov = engine.getGovernanceOverview(ctx);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        ttlMs: 60_000,
+                        cacheScope: "private",
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(gov, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri === "muxo://policy/brief") {
+                const gov = engine.getGovernanceOverview(ctx);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        ttlMs: 60_000,
+                        cacheScope: "private",
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(gov.llmPolicyBrief, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri === "muxo://receipts/chain") {
+                const chain = engine.verifyReceiptChain(ctx);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        resultType: "complete",
+                        ttlMs: 60_000,
+                        cacheScope: "private",
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(chain, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri.startsWith("muxo://tools/")) {
+                const slug = decodeURIComponent(uri.slice("muxo://tools/".length)).trim();
+                try {
+                    const inspected = await dispatchMcpToolCall(engine, ctx, "inspect_tool", {
+                        tool_slug: slug,
+                    });
+                    return {
+                        jsonrpc: "2.0",
+                        id,
+                        result: {
+                            resultType: "complete",
+                            ttlMs: 300_000,
+                            cacheScope: "public",
+                            contents: [
+                                {
+                                    uri,
+                                    mimeType: "application/json",
+                                    text: JSON.stringify(inspected, null, 2),
+                                },
+                            ],
+                        },
+                    };
+                }
+                catch {
+                    return {
+                        jsonrpc: "2.0",
+                        id,
+                        error: {
+                            code: -32602,
+                            message: `Resource not found: ${uri}`,
+                        },
+                    };
+                }
+            }
+            if (uri.startsWith("muxo://plans/")) {
+                const planId = decodeURIComponent(uri.slice("muxo://plans/".length)).trim();
+                try {
+                    const planRecord = await dispatchMcpToolCall(engine, ctx, "get_plan", {
+                        plan_id: planId,
+                    });
+                    return {
+                        jsonrpc: "2.0",
+                        id,
+                        result: {
+                            resultType: "complete",
+                            ttlMs: 30_000,
+                            cacheScope: "private",
+                            contents: [
+                                {
+                                    uri,
+                                    mimeType: "application/json",
+                                    text: JSON.stringify(planRecord, null, 2),
+                                },
+                            ],
+                        },
+                    };
+                }
+                catch {
+                    return {
+                        jsonrpc: "2.0",
+                        id,
+                        error: {
+                            code: -32602,
+                            message: `Resource not found: ${uri}`,
+                        },
+                    };
+                }
+            }
+            if (uri.startsWith("muxo://runs/")) {
+                const runId = decodeURIComponent(uri.slice("muxo://runs/".length)).trim();
+                try {
+                    const runRecord = await dispatchMcpToolCall(engine, ctx, "get_run", {
+                        run_id: runId,
+                    });
+                    return {
+                        jsonrpc: "2.0",
+                        id,
+                        result: {
+                            resultType: "complete",
+                            ttlMs: 30_000,
+                            cacheScope: "private",
+                            contents: [
+                                {
+                                    uri,
+                                    mimeType: "application/json",
+                                    text: JSON.stringify(runRecord, null, 2),
+                                },
+                            ],
+                        },
+                    };
+                }
+                catch {
+                    return {
+                        jsonrpc: "2.0",
+                        id,
+                        error: {
+                            code: -32602,
+                            message: `Resource not found: ${uri}`,
+                        },
+                    };
+                }
+            }
+            if (uri.startsWith("muxo://receipts/")) {
+                const receiptId = decodeURIComponent(uri.slice("muxo://receipts/".length)).trim();
+                try {
+                    const receiptRecord = await dispatchMcpToolCall(engine, ctx, "get_receipt", {
+                        receipt_id: receiptId,
+                    });
+                    return {
+                        jsonrpc: "2.0",
+                        id,
+                        result: {
+                            resultType: "complete",
+                            ttlMs: 60_000,
+                            cacheScope: "private",
+                            contents: [
+                                {
+                                    uri,
+                                    mimeType: "application/json",
+                                    text: JSON.stringify(receiptRecord, null, 2),
+                                },
+                            ],
+                        },
+                    };
+                }
+                catch {
+                    return {
+                        jsonrpc: "2.0",
+                        id,
+                        error: {
+                            code: -32602,
+                            message: `Resource not found: ${uri}`,
+                        },
+                    };
+                }
+            }
             const allFiles = getMuxoMcpSkills().flatMap((s) => s.files);
             const found = allFiles.find((f) => f.uri === uri);
             if (!found) {
@@ -874,6 +1311,9 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
                 jsonrpc: "2.0",
                 id,
                 result: {
+                    resultType: "complete",
+                    ttlMs: 300_000,
+                    cacheScope: "public",
                     contents: [
                         {
                             uri: found.uri,
@@ -894,19 +1334,21 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
         };
     }
     catch (err) {
+        const errPayload = errorPayloadFrom(err, "MCP tool execution failed");
+        const errMeta = buildMcpErrorResultMeta(err, engine?.config?.baseUrl || "https://api.muxo.ai");
         return {
             jsonrpc: "2.0",
             id,
             result: {
+                resultType: "complete",
+                structuredContent: errPayload,
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({
-                            ok: false,
-                            error: String(err?.message || err || "MCP tool execution failed"),
-                        }, null, 2),
+                        text: JSON.stringify(errPayload, null, 2),
                     },
                 ],
+                ...(errMeta ? { _meta: errMeta } : {}),
                 isError: true,
             },
         };