@muxoai/platform 1.4.0 → 1.4.1

package/dist/mcp.js

@@ -2,524 +2,9 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { ROOT_DIR } from "./config.js";
+import { APPROVED_PLAN_STATUSES, DEFAULT_TOOL_SECURITY_SCHEMES, MUXO_MCP_SERVER_INSTRUCTIONS, MUXO_MCP_TOOLS, OPENAI_COMPANY_KNOWLEDGE_TOOLS, PUBLIC_MCP_TOOL_NAMES, PUBLIC_TOOL_SECURITY_SCHEMES, attachMcpHarnessGuidance, MuxoToolError, buildApprovalUrl, buildOnboardTeamGuide, clampWaitSeconds, errorPayloadFrom, findMcpSkill, securitySchemesForTool, } from "./mcp-schema.js";
 import { MUXO_VERSION } from "./version.js";
-const DEFAULT_TOOL_SECURITY_SCHEMES = [
-    { type: "noauth" },
-    {
-        type: "oauth2",
-        scopes: ["muxo:mcp", "muxo:read", "muxo:execute", "muxo:provision"],
-    },
-];
-/**
- * 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 (Connected Apps: app.*), Instant tools (instant.*), Cloud Infrastructure (resource.*), Workspace Memory recall, and verifiable audit records. 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: {
-            $schema: "https://json-schema.org/draft/2020-12/schema",
-            type: "object",
-            properties: {
-                id: {
-                    type: "string",
-                    minLength: 1,
-                    pattern: "\\S",
-                    description: "Unique identifier for the user.",
-                },
-                name: {
-                    type: "string",
-                    description: "Full name of the user.",
-                },
-                email: {
-                    type: "string",
-                    description: "Email address of the user.",
-                },
-                nickname: {
-                    type: "string",
-                    description: "Handle or username of the user.",
-                },
-                workspaceId: {
-                    type: "string",
-                    description: "Active workspace ID.",
-                },
-                workspaceName: {
-                    type: "string",
-                    description: "Active workspace name.",
-                },
-                tier: {
-                    type: "string",
-                    description: "Workspace subscription tier.",
-                },
-                authType: {
-                    type: "string",
-                    description: "Authentication type (session or api_key).",
-                },
-                actorId: {
-                    type: "string",
-                    description: "Actor identifier.",
-                },
-                user: {
-                    type: "object",
-                    description: "User profile record.",
-                },
-            },
-            required: ["id"],
-            additionalProperties: false,
-        },
-        securitySchemes: [
-            { type: "noauth" },
-            { type: "oauth2", scopes: ["muxo:read"] },
-        ],
-        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 (app.*), Instant Tools (instant.*), and Cloud Infrastructure (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 Connected Apps, Instant Tools, and linked Cloud Infrastructure 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 connection status from upstream providers",
-                },
-            },
-            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 or link a Cloud Infrastructure provider.",
-        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, Workspace Memory recall, safety guardrails, 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,
-        },
-    },
-];
+export { DEFAULT_TOOL_SECURITY_SCHEMES, MUXO_MCP_SERVER_INSTRUCTIONS, MUXO_MCP_TOOLS, OPENAI_COMPANY_KNOWLEDGE_TOOLS, PUBLIC_MCP_TOOL_NAMES, PUBLIC_TOOL_SECURITY_SCHEMES, attachMcpHarnessGuidance, securitySchemesForTool, };
 function sha256Digest(content) {
     const hash = crypto
         .createHash("sha256")
@@ -692,9 +177,7 @@ export async function dispatchMcpToolCall(engine, ctx, toolName, args = {}) {
         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, {
@@ -708,9 +191,128 @@ 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 === "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":
@@ -726,9 +328,92 @@ 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 "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();
@@ -789,7 +474,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) {
@@ -819,6 +504,7 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
                     capabilities: {
                         tools: { listChanged: false },
                         resources: { listChanged: false },
+                        prompts: { listChanged: false },
                         extensions: {
                             "io.modelcontextprotocol/skills": {},
                         },
@@ -829,6 +515,126 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
         if (method === "ping") {
             return { jsonrpc: "2.0", id, result: {} };
         }
+        if (method === "prompts/list") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    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: [],
+                        },
+                    ],
+                },
+            };
+        }
+        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: {
+                        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 === "governed_execution") {
+                const task = String(promptArgs.task || "the user's requested operation");
+                const runCtx = await engine.getRunContext(ctx);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        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: {
+                        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",
@@ -836,7 +642,7 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
                 result: {
                     tools: MUXO_MCP_TOOLS.map((t) => ({
                         ...t,
-                        securitySchemes: t.securitySchemes || DEFAULT_TOOL_SECURITY_SCHEMES,
+                        securitySchemes: securitySchemesForTool(t.name),
                     })),
                 },
             };
@@ -844,7 +650,8 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
         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 };
@@ -885,16 +692,14 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
             };
         }
         if (method === "skills/get") {
-            const requestedUri = String(params.uri || "").trim();
-            const requestedName = String(params.name || "muxo").trim();
-            const skill = getMuxoMcpSkills().find((s) => s.uri === requestedUri || s.name === requestedName);
+            const { skill, requested } = findMcpSkill(getMuxoMcpSkills(), params);
             if (!skill) {
                 return {
                     jsonrpc: "2.0",
                     id,
                     error: {
                         code: -32602,
-                        message: `Skill not found: ${requestedUri || requestedName}`,
+                        message: `Skill not found: ${requested}`,
                     },
                 };
             }
@@ -929,20 +734,184 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
             };
         }
         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://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: { resources: [...skillResources, ...dynamicResources] },
             };
         }
         if (method === "resources/read") {
             const uri = String(params.uri || "").trim();
+            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: {
+                        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: {
+                        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: {
+                        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: {
+                        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: {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(gov, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
+            if (uri === "muxo://receipts/chain") {
+                const chain = engine.verifyReceiptChain(ctx);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        contents: [
+                            {
+                                uri,
+                                mimeType: "application/json",
+                                text: JSON.stringify(chain, null, 2),
+                            },
+                        ],
+                    },
+                };
+            }
             const allFiles = getMuxoMcpSkills().flatMap((s) => s.files);
             const found = allFiles.find((f) => f.uri === uri);
             if (!found) {
@@ -979,10 +948,7 @@ export async function handleJsonRpcMcpRequest(engine, ctx, rpc) {
         };
     }
     catch (err) {
-        const errPayload = {
-            ok: false,
-            error: String(err?.message || err || "MCP tool execution failed"),
-        };
+        const errPayload = errorPayloadFrom(err, "MCP tool execution failed");
         return {
             jsonrpc: "2.0",
             id,