c64bridge 1.0.7 → 1.1.0

package/dist/mcp-server.js

@@ -1,20 +1,25 @@
 #!/usr/bin/env node
 import "./bootstrap/stdio-logger.js";
 import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import { loadConfig } from "./config.js";
 import { C64Client } from "./c64Client.js";
 import { listKnowledgeResources, readKnowledgeResource, } from "./rag/knowledgeIndex.js";
 import { PLATFORM_RESOURCE_URI } from "./rag/resourceUris.js";
 import { createLazyRagRetriever, initRag } from "./rag/init.js";
 import { getMcpServerImplementationInfo } from "./mcp/metadata.js";
+import { stopAllBackgroundTasks } from "./tools/meta/background.js";
+import { delegateViceSignalHandling, stopManagedViceProcessesSync } from "./device.js";
 import { toolRegistry } from "./tools/registry/index.js";
-import { unknownErrorResult } from "./tools/errors.js";
+import { ACCESS_ENV_VAR, getAccessMode } from "./tools/access.js";
+import { ToolValidationError, unknownErrorResult } from "./tools/errors.js";
+import { publishedInputSchema } from "./tools/types.js";
 import { createPromptRegistry } from "./prompts/registry.js";
 import { describePlatformCapabilities, getPlatformStatus, setPlatform } from "./platform.js";
 import axios from "axios";
@@ -43,6 +48,84 @@ export function parseCliOptions(argv) {
     const portCandidate = argv[httpIndex + 1];
     return { mode: "http", port: parsePort(portCandidate) };
 }
+/**
+ * DNS-rebinding and cross-origin protection for the HTTP transport. Returns
+ * the rejection (status and message) or null when the request may proceed.
+ * Host must be a loopback name with the listening port, any Origin must be a
+ * loopback http origin on that port, and when a token is configured the
+ * request must carry the matching bearer token.
+ */
+export function checkHttpRequestAccess(headers, port, token) {
+    const allowedHosts = [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`];
+    const host = headers.host?.toLowerCase();
+    if (!host || !allowedHosts.includes(host)) {
+        return { status: 403, message: "Forbidden: invalid Host header" };
+    }
+    const origin = headers.origin;
+    if (origin !== undefined) {
+        const allowedOrigins = allowedHosts.map((entry) => `http://${entry}`);
+        if (typeof origin !== "string" || !allowedOrigins.includes(origin.toLowerCase())) {
+            return { status: 403, message: "Forbidden: invalid Origin header" };
+        }
+    }
+    if (token) {
+        const header = headers.authorization;
+        const presented = typeof header === "string" && /^Bearer /i.test(header) ? header.slice(7) : "";
+        const expectedBuffer = Buffer.from(token, "utf8");
+        const presentedBuffer = Buffer.from(presented, "utf8");
+        if (presentedBuffer.length !== expectedBuffer.length || !timingSafeEqual(presentedBuffer, expectedBuffer)) {
+            return { status: 401, message: "Unauthorized" };
+        }
+    }
+    return null;
+}
+const SHUTDOWN_CLEANUP_TIMEOUT_MS = 2000;
+/**
+ * Installs the single shutdown path. The first trigger stops background
+ * tasks, releases any capture session and stops managed VICE processes, then
+ * exits. Later triggers return the same promise. Stdin end/close is a
+ * trigger only in stdio mode (the client went away).
+ */
+function installShutdown(client, mode) {
+    delegateViceSignalHandling();
+    let shutdownPromise = null;
+    const shutdown = (reason, exitCode) => {
+        if (shutdownPromise)
+            return shutdownPromise;
+        writeDiagnosticEvent("server_shutdown", { reason });
+        console.error(`c64bridge shutting down (${reason})`);
+        shutdownPromise = (async () => {
+            try {
+                const cleanup = Promise.allSettled([
+                    stopAllBackgroundTasks(),
+                    client.releaseVideoCapture(),
+                ]);
+                await Promise.race([
+                    cleanup,
+                    new Promise((resolve) => setTimeout(resolve, SHUTDOWN_CLEANUP_TIMEOUT_MS).unref()),
+                ]);
+            }
+            catch {
+                // Cleanup is best effort; always continue to exit.
+            }
+            try {
+                stopManagedViceProcessesSync();
+            }
+            catch {
+                // ignore
+            }
+            process.exit(exitCode);
+        })();
+        return shutdownPromise;
+    };
+    process.on("SIGTERM", () => void shutdown("SIGTERM", 143));
+    process.on("SIGINT", () => void shutdown("SIGINT", 130));
+    process.on("SIGHUP", () => void shutdown("SIGHUP", 129));
+    if (mode === "stdio") {
+        process.stdin.once("end", () => void shutdown("stdin end", 0));
+        process.stdin.once("close", () => void shutdown("stdin close", 0));
+    }
+}
 function parsePort(raw) {
     if (!raw || raw.startsWith("--")) {
         return undefined;
@@ -109,344 +192,377 @@ async function main() {
     const promptRegistry = createPromptRegistry();
     const getPromptRegistry = createPromptRegistryGetter();
     const implementationInfo = getMcpServerImplementationInfo();
-    // Create MCP server
-    const server = new Server(implementationInfo, {
-        capabilities: {
-            resources: {},
-            tools: {},
-            prompts: {},
-        },
-    });
-    // RESOURCES: Expose C64 knowledge base
-    server.setRequestHandler(ListResourcesRequestSchema, async () => {
-        const startedAt = Date.now();
-        writeDiagnosticEvent("mcp_list_resources_start");
-        try {
-            const knowledgeResources = listKnowledgeResources().map((resource) => ({
-                uri: resource.uri,
-                name: resource.name,
-                description: resource.description,
-                mimeType: resource.mimeType,
-                _meta: resource.metadata,
-            }));
-            const platformResource = createPlatformResourceDescriptor();
-            const response = {
-                resources: [...knowledgeResources, platformResource],
-            };
-            const latency = Date.now() - startedAt;
-            const bytes = payloadByteLength(response);
-            resourceLogger.info(`list resources count=${response.resources.length} bytes=${bytes} latencyMs=${latency}`);
-            if (resourceLogger.isDebugEnabled()) {
-                resourceLogger.debug("list resources request", { request: {} });
-                resourceLogger.debug("list resources response", { response: formatPayloadForDebug(response) });
-            }
-            writeDiagnosticEvent("mcp_list_resources_ok", {
-                count: response.resources.length,
-                latencyMs: latency,
-            });
-            return response;
-        }
-        catch (error) {
-            const latency = Date.now() - startedAt;
-            resourceLogger.error(`list resources failed bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
-            if (resourceLogger.isDebugEnabled()) {
-                resourceLogger.debug("list resources request", { request: {} });
-                resourceLogger.debug("list resources error", { error: formatErrorMessage(error) });
-            }
-            writeDiagnosticEvent("mcp_list_resources_failed", { latencyMs: latency, error });
-            throw error;
-        }
-    });
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-        const startedAt = Date.now();
-        writeDiagnosticEvent("mcp_read_resource_start", { uri: request.params.uri });
-        try {
-            let response;
-            if (request.params.uri === PLATFORM_RESOURCE_URI) {
-                response = {
-                    contents: [
-                        {
-                            uri: PLATFORM_RESOURCE_URI,
-                            mimeType: "text/markdown",
-                            text: await renderPlatformStatusMarkdown(client),
-                        },
-                    ],
+    // Create MCP server. Stateless HTTP mode needs a fresh Server and transport
+    // per request (the SDK rejects reuse of a stateless transport), so server
+    // creation and handler registration live in this factory. The handler bodies
+    // below are unchanged and intentionally not re-indented.
+    const createMcpServer = () => {
+        const server = new Server(implementationInfo, {
+            capabilities: {
+                resources: {},
+                tools: {},
+                prompts: {},
+            },
+        });
+        // RESOURCES: Expose C64 knowledge base
+        server.setRequestHandler(ListResourcesRequestSchema, async () => {
+            const startedAt = Date.now();
+            writeDiagnosticEvent("mcp_list_resources_start");
+            try {
+                const knowledgeResources = listKnowledgeResources().map((resource) => ({
+                    uri: resource.uri,
+                    name: resource.name,
+                    description: resource.description,
+                    mimeType: resource.mimeType,
+                    _meta: resource.metadata,
+                }));
+                const platformResource = createPlatformResourceDescriptor();
+                const response = {
+                    resources: [...knowledgeResources, platformResource],
                 };
+                const latency = Date.now() - startedAt;
+                const bytes = payloadByteLength(response);
+                resourceLogger.info(`list resources count=${response.resources.length} bytes=${bytes} latencyMs=${latency}`);
+                if (resourceLogger.isDebugEnabled()) {
+                    resourceLogger.debug("list resources request", { request: {} });
+                    resourceLogger.debug("list resources response", { response: formatPayloadForDebug(response) });
+                }
+                writeDiagnosticEvent("mcp_list_resources_ok", {
+                    count: response.resources.length,
+                    latencyMs: latency,
+                });
+                return response;
             }
-            else {
-                const result = readKnowledgeResource(request.params.uri, PROJECT_ROOT);
-                if (!result) {
-                    throw new Error(`Unknown resource: ${request.params.uri}`);
+            catch (error) {
+                const latency = Date.now() - startedAt;
+                resourceLogger.error(`list resources failed bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
+                if (resourceLogger.isDebugEnabled()) {
+                    resourceLogger.debug("list resources request", { request: {} });
+                    resourceLogger.debug("list resources error", { error: formatErrorMessage(error) });
                 }
-                response = {
-                    contents: [result],
-                };
+                writeDiagnosticEvent("mcp_list_resources_failed", { latencyMs: latency, error });
+                throw error;
             }
-            const latency = Date.now() - startedAt;
-            const bytes = payloadByteLength(response);
-            resourceLogger.info(`read resource uri=${request.params.uri} bytes=${bytes} latencyMs=${latency}`);
-            if (resourceLogger.isDebugEnabled()) {
-                resourceLogger.debug("read resource request", { request: formatPayloadForDebug(request.params) });
-                resourceLogger.debug("read resource response", { response: formatPayloadForDebug(response) });
+        });
+        server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            const startedAt = Date.now();
+            writeDiagnosticEvent("mcp_read_resource_start", { uri: request.params.uri });
+            try {
+                let response;
+                if (request.params.uri === PLATFORM_RESOURCE_URI) {
+                    response = {
+                        contents: [
+                            {
+                                uri: PLATFORM_RESOURCE_URI,
+                                mimeType: "text/markdown",
+                                text: await renderPlatformStatusMarkdown(client),
+                            },
+                        ],
+                    };
+                }
+                else {
+                    const result = readKnowledgeResource(request.params.uri, PROJECT_ROOT);
+                    if (!result) {
+                        throw new Error(`Unknown resource: ${request.params.uri}`);
+                    }
+                    response = {
+                        contents: [result],
+                    };
+                }
+                const latency = Date.now() - startedAt;
+                const bytes = payloadByteLength(response);
+                resourceLogger.info(`read resource uri=${request.params.uri} bytes=${bytes} latencyMs=${latency}`);
+                if (resourceLogger.isDebugEnabled()) {
+                    resourceLogger.debug("read resource request", { request: formatPayloadForDebug(request.params) });
+                    resourceLogger.debug("read resource response", { response: formatPayloadForDebug(response) });
+                }
+                writeDiagnosticEvent("mcp_read_resource_ok", {
+                    uri: request.params.uri,
+                    latencyMs: latency,
+                });
+                return response;
             }
-            writeDiagnosticEvent("mcp_read_resource_ok", {
-                uri: request.params.uri,
-                latencyMs: latency,
-            });
-            return response;
-        }
-        catch (error) {
-            const latency = Date.now() - startedAt;
-            resourceLogger.error(`read resource uri=${request.params.uri} bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
-            if (resourceLogger.isDebugEnabled()) {
-                resourceLogger.debug("read resource request", { request: formatPayloadForDebug(request.params) });
-                resourceLogger.debug("read resource error", { error: formatErrorMessage(error) });
+            catch (error) {
+                const latency = Date.now() - startedAt;
+                resourceLogger.error(`read resource uri=${request.params.uri} bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
+                if (resourceLogger.isDebugEnabled()) {
+                    resourceLogger.debug("read resource request", { request: formatPayloadForDebug(request.params) });
+                    resourceLogger.debug("read resource error", { error: formatErrorMessage(error) });
+                }
+                writeDiagnosticEvent("mcp_read_resource_failed", {
+                    uri: request.params.uri,
+                    latencyMs: latency,
+                    error,
+                });
+                throw error;
             }
-            writeDiagnosticEvent("mcp_read_resource_failed", {
-                uri: request.params.uri,
-                latencyMs: latency,
-                error,
-            });
-            throw error;
-        }
-    });
-    server.setRequestHandler(ListToolsRequestSchema, async () => {
-        const startedAt = Date.now();
-        writeDiagnosticEvent("mcp_list_tools_start");
-        try {
-            const response = {
-                tools: toolRegistry.list().map((tool) => ({
-                    name: tool.name,
-                    title: tool.metadata.summary,
-                    description: tool.description,
-                    inputSchema: tool.inputSchema,
-                    _meta: tool.metadata,
-                })),
-            };
-            const latency = Date.now() - startedAt;
-            const bytes = payloadByteLength(response);
-            toolLogger.info(`list tools count=${response.tools.length} bytes=${bytes} latencyMs=${latency}`);
-            if (toolLogger.isDebugEnabled()) {
-                toolLogger.debug("list tools request", { request: {} });
-                toolLogger.debug("list tools response", { response: formatPayloadForDebug(response) });
+        });
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            const startedAt = Date.now();
+            writeDiagnosticEvent("mcp_list_tools_start");
+            try {
+                const response = {
+                    tools: toolRegistry.list().map((tool) => ({
+                        name: tool.name,
+                        title: tool.metadata.summary,
+                        description: tool.description,
+                        inputSchema: publishedInputSchema(tool.inputSchema),
+                        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+                        _meta: tool.metadata,
+                    })),
+                };
+                const latency = Date.now() - startedAt;
+                const bytes = payloadByteLength(response);
+                toolLogger.info(`list tools count=${response.tools.length} bytes=${bytes} latencyMs=${latency}`);
+                if (toolLogger.isDebugEnabled()) {
+                    toolLogger.debug("list tools request", { request: {} });
+                    toolLogger.debug("list tools response", { response: formatPayloadForDebug(response) });
+                }
+                writeDiagnosticEvent("mcp_list_tools_ok", {
+                    count: response.tools.length,
+                    latencyMs: latency,
+                });
+                return response;
             }
-            writeDiagnosticEvent("mcp_list_tools_ok", {
-                count: response.tools.length,
-                latencyMs: latency,
-            });
-            return response;
-        }
-        catch (error) {
-            const latency = Date.now() - startedAt;
-            toolLogger.error(`list tools failed bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
-            if (toolLogger.isDebugEnabled()) {
-                toolLogger.debug("list tools request", { request: {} });
-                toolLogger.debug("list tools error", { error: formatErrorMessage(error) });
+            catch (error) {
+                const latency = Date.now() - startedAt;
+                toolLogger.error(`list tools failed bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
+                if (toolLogger.isDebugEnabled()) {
+                    toolLogger.debug("list tools request", { request: {} });
+                    toolLogger.debug("list tools error", { error: formatErrorMessage(error) });
+                }
+                writeDiagnosticEvent("mcp_list_tools_failed", { latencyMs: latency, error });
+                throw error;
             }
-            writeDiagnosticEvent("mcp_list_tools_failed", { latencyMs: latency, error });
-            throw error;
-        }
-    });
-    server.setRequestHandler(ListPromptsRequestSchema, async () => {
-        const startedAt = Date.now();
-        writeDiagnosticEvent("mcp_list_prompts_start");
-        try {
-            const entries = promptRegistry.list();
-            const response = {
-                prompts: entries.map((entry) => ({
-                    name: entry.descriptor.name,
-                    title: entry.descriptor.title,
-                    description: entry.descriptor.description,
-                    arguments: entry.arguments?.map((argument) => ({
-                        name: argument.name,
-                        description: argument.description,
-                        required: argument.required,
-                        options: argument.options,
+        });
+        server.setRequestHandler(ListPromptsRequestSchema, async () => {
+            const startedAt = Date.now();
+            writeDiagnosticEvent("mcp_list_prompts_start");
+            try {
+                const entries = promptRegistry.list();
+                const response = {
+                    prompts: entries.map((entry) => ({
+                        name: entry.descriptor.name,
+                        title: entry.descriptor.title,
+                        description: entry.descriptor.description,
+                        arguments: entry.arguments?.map((argument) => ({
+                            name: argument.name,
+                            description: argument.description,
+                            required: argument.required,
+                            options: argument.options,
+                        })),
+                        _meta: {
+                            requiredResources: entry.descriptor.requiredResources,
+                            optionalResources: entry.descriptor.optionalResources ?? [],
+                            tools: entry.descriptor.tools,
+                            tags: entry.descriptor.tags ?? [],
+                            argumentOptions: Object.fromEntries((entry.arguments ?? [])
+                                .filter((argument) => Array.isArray(argument.options) && argument.options.length > 0)
+                                .map((argument) => [argument.name, argument.options])),
+                        },
                     })),
-                    _meta: {
-                        requiredResources: entry.descriptor.requiredResources,
-                        optionalResources: entry.descriptor.optionalResources ?? [],
-                        tools: entry.descriptor.tools,
-                        tags: entry.descriptor.tags ?? [],
-                        argumentOptions: Object.fromEntries((entry.arguments ?? [])
-                            .filter((argument) => Array.isArray(argument.options) && argument.options.length > 0)
-                            .map((argument) => [argument.name, argument.options])),
-                    },
-                })),
-            };
-            const latency = Date.now() - startedAt;
-            const bytes = payloadByteLength(response);
-            promptLogger.info(`list prompts count=${response.prompts.length} bytes=${bytes} latencyMs=${latency}`);
-            if (promptLogger.isDebugEnabled()) {
-                promptLogger.debug("list prompts request", { request: {} });
-                promptLogger.debug("list prompts response", { response: formatPayloadForDebug(response) });
+                };
+                const latency = Date.now() - startedAt;
+                const bytes = payloadByteLength(response);
+                promptLogger.info(`list prompts count=${response.prompts.length} bytes=${bytes} latencyMs=${latency}`);
+                if (promptLogger.isDebugEnabled()) {
+                    promptLogger.debug("list prompts request", { request: {} });
+                    promptLogger.debug("list prompts response", { response: formatPayloadForDebug(response) });
+                }
+                writeDiagnosticEvent("mcp_list_prompts_ok", {
+                    count: response.prompts.length,
+                    latencyMs: latency,
+                });
+                return response;
             }
-            writeDiagnosticEvent("mcp_list_prompts_ok", {
-                count: response.prompts.length,
-                latencyMs: latency,
-            });
-            return response;
-        }
-        catch (error) {
-            const latency = Date.now() - startedAt;
-            promptLogger.error(`list prompts failed bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
-            if (promptLogger.isDebugEnabled()) {
-                promptLogger.debug("list prompts request", { request: {} });
-                promptLogger.debug("list prompts error", { error: formatErrorMessage(error) });
+            catch (error) {
+                const latency = Date.now() - startedAt;
+                promptLogger.error(`list prompts failed bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
+                if (promptLogger.isDebugEnabled()) {
+                    promptLogger.debug("list prompts request", { request: {} });
+                    promptLogger.debug("list prompts error", { error: formatErrorMessage(error) });
+                }
+                writeDiagnosticEvent("mcp_list_prompts_failed", { latencyMs: latency, error });
+                throw error;
             }
-            writeDiagnosticEvent("mcp_list_prompts_failed", { latencyMs: latency, error });
-            throw error;
-        }
-    });
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name } = request.params;
-        const args = request.params.arguments ?? {};
-        const startedAt = Date.now();
-        writeDiagnosticEvent("mcp_call_tool_start", {
-            name,
-            arguments: formatPayloadForDebug(args),
         });
-        if (toolLogger.isDebugEnabled()) {
-            toolLogger.debug("tool request", {
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name } = request.params;
+            const args = request.params.arguments ?? {};
+            const startedAt = Date.now();
+            writeDiagnosticEvent("mcp_call_tool_start", {
                 name,
                 arguments: formatPayloadForDebug(args),
             });
-        }
-        try {
-            const result = await toolRegistry.invoke(name, args, {
-                client,
-                rag,
-                logger: toolLogger,
-                platform: getPlatformStatus(),
-                setPlatform,
-            });
-            const response = toCallToolResult(result);
-            const latency = Date.now() - startedAt;
-            const bytes = payloadByteLength(response);
-            const status = result.isError ? "error" : "ok";
-            toolLogger.info(`call tool name=${name} status=${status} bytes=${bytes} latencyMs=${latency}`);
             if (toolLogger.isDebugEnabled()) {
-                toolLogger.debug("tool response", {
+                toolLogger.debug("tool request", {
                     name,
-                    response: formatPayloadForDebug(response),
+                    arguments: formatPayloadForDebug(args),
                 });
             }
-            writeDiagnosticEvent("mcp_call_tool_ok", {
-                name,
-                latencyMs: latency,
-                isError: result.isError === true,
-            });
-            return response;
-        }
-        catch (error) {
-            const latency = Date.now() - startedAt;
-            const fallback = unknownErrorResult(error);
-            const response = toCallToolResult(fallback);
-            const bytes = payloadByteLength(response);
-            toolLogger.error(`call tool name=${name} status=failed bytes=${bytes} latencyMs=${latency} error=${formatErrorMessage(error)}`);
-            if (toolLogger.isDebugEnabled()) {
-                toolLogger.debug("tool response", {
+            try {
+                const result = await toolRegistry.invoke(name, args, {
+                    client,
+                    rag,
+                    logger: toolLogger,
+                    platform: getPlatformStatus(),
+                    setPlatform,
+                });
+                const response = toCallToolResult(result);
+                const latency = Date.now() - startedAt;
+                const bytes = payloadByteLength(response);
+                const status = result.isError ? "error" : "ok";
+                toolLogger.info(`call tool name=${name} status=${status} bytes=${bytes} latencyMs=${latency}`);
+                if (toolLogger.isDebugEnabled()) {
+                    toolLogger.debug("tool response", {
+                        name,
+                        response: formatPayloadForDebug(response),
+                    });
+                }
+                writeDiagnosticEvent("mcp_call_tool_ok", {
                     name,
-                    response: formatPayloadForDebug(response),
-                    error: formatErrorMessage(error),
+                    latencyMs: latency,
+                    isError: result.isError === true,
                 });
+                return response;
             }
-            writeDiagnosticEvent("mcp_call_tool_failed", {
-                name,
-                latencyMs: latency,
-                error,
-            });
-            return response;
-        }
-    });
-    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-        const { name } = request.params;
-        const args = request.params.arguments ?? {};
-        const startedAt = Date.now();
-        writeDiagnosticEvent("mcp_get_prompt_start", {
-            name,
-            arguments: formatPayloadForDebug(args),
-        });
-        if (promptLogger.isDebugEnabled()) {
-            promptLogger.debug("prompt request", {
-                name,
-                arguments: formatPayloadForDebug(args),
-            });
-        }
-        try {
-            const resolved = promptRegistry.resolve(name, args);
-            const response = {
-                description: resolved.description,
-                messages: resolved.messages.map(toPromptMessage),
-                _meta: {
-                    arguments: resolved.arguments,
-                    resources: resolved.resources.map((resource) => ({
-                        uri: resource.uri,
-                        name: resource.name,
-                        description: resource.description,
-                        mimeType: resource.mimeType,
-                        metadata: resource.metadata,
-                    })),
-                    tools: resolved.tools,
-                },
-            };
-            const latency = Date.now() - startedAt;
-            const bytes = payloadByteLength(response);
-            promptLogger.info(`get prompt name=${name} bytes=${bytes} latencyMs=${latency}`);
-            if (promptLogger.isDebugEnabled()) {
-                promptLogger.debug("prompt response", {
+            catch (error) {
+                const latency = Date.now() - startedAt;
+                const fallback = unknownErrorResult(error);
+                const response = toCallToolResult(fallback);
+                const bytes = payloadByteLength(response);
+                toolLogger.error(`call tool name=${name} status=failed bytes=${bytes} latencyMs=${latency} error=${formatErrorMessage(error)}`);
+                if (toolLogger.isDebugEnabled()) {
+                    toolLogger.debug("tool response", {
+                        name,
+                        response: formatPayloadForDebug(response),
+                        error: formatErrorMessage(error),
+                    });
+                }
+                writeDiagnosticEvent("mcp_call_tool_failed", {
                     name,
-                    response: formatPayloadForDebug(response),
+                    latencyMs: latency,
+                    error,
                 });
+                return response;
             }
-            writeDiagnosticEvent("mcp_get_prompt_ok", {
+        });
+        server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const { name } = request.params;
+            const args = request.params.arguments ?? {};
+            const startedAt = Date.now();
+            writeDiagnosticEvent("mcp_get_prompt_start", {
                 name,
-                latencyMs: latency,
+                arguments: formatPayloadForDebug(args),
             });
-            return response;
-        }
-        catch (error) {
-            const latency = Date.now() - startedAt;
-            promptLogger.error(`get prompt name=${name} bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
             if (promptLogger.isDebugEnabled()) {
                 promptLogger.debug("prompt request", {
                     name,
                     arguments: formatPayloadForDebug(args),
                 });
-                promptLogger.debug("prompt error", { name, error: formatErrorMessage(error) });
             }
-            writeDiagnosticEvent("mcp_get_prompt_failed", {
-                name,
-                latencyMs: latency,
-                error,
-            });
-            throw error;
-        }
-    });
+            try {
+                const resolved = promptRegistry.resolve(name, args);
+                const response = {
+                    description: resolved.description,
+                    messages: resolved.messages.map(toPromptMessage),
+                    _meta: {
+                        arguments: resolved.arguments,
+                        resources: resolved.resources.map((resource) => ({
+                            uri: resource.uri,
+                            name: resource.name,
+                            description: resource.description,
+                            mimeType: resource.mimeType,
+                            metadata: resource.metadata,
+                        })),
+                        tools: resolved.tools,
+                    },
+                };
+                const latency = Date.now() - startedAt;
+                const bytes = payloadByteLength(response);
+                promptLogger.info(`get prompt name=${name} bytes=${bytes} latencyMs=${latency}`);
+                if (promptLogger.isDebugEnabled()) {
+                    promptLogger.debug("prompt response", {
+                        name,
+                        response: formatPayloadForDebug(response),
+                    });
+                }
+                writeDiagnosticEvent("mcp_get_prompt_ok", {
+                    name,
+                    latencyMs: latency,
+                });
+                return response;
+            }
+            catch (error) {
+                const latency = Date.now() - startedAt;
+                promptLogger.error(`get prompt name=${name} bytes=0 latencyMs=${latency} error=${formatErrorMessage(error)}`);
+                if (promptLogger.isDebugEnabled()) {
+                    promptLogger.debug("prompt request", {
+                        name,
+                        arguments: formatPayloadForDebug(args),
+                    });
+                    promptLogger.debug("prompt error", { name, error: formatErrorMessage(error) });
+                }
+                writeDiagnosticEvent("mcp_get_prompt_failed", {
+                    name,
+                    latencyMs: latency,
+                    error,
+                });
+                if (error instanceof ToolValidationError) {
+                    throw new McpError(ErrorCode.InvalidParams, error.message);
+                }
+                throw error;
+            }
+        });
+        return server;
+    };
     const cli = parseCliOptions(process.argv.slice(2));
     if (cli.mode === "http") {
-        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-        await server.connect(transport);
         const port = cli.port ?? 3000;
+        const httpToken = process.env.C64BRIDGE_HTTP_TOKEN || undefined;
+        if (httpToken) {
+            registerSecret(httpToken);
+        }
         const httpServer = createServer((request, response) => {
+            const rejection = checkHttpRequestAccess(request.headers, port, httpToken);
+            if (rejection) {
+                response.statusCode = rejection.status;
+                if (rejection.status === 401)
+                    response.setHeader("WWW-Authenticate", "Bearer");
+                response.end(rejection.message);
+                return;
+            }
             if (request.url?.split("?")[0] !== "/mcp") {
                 response.statusCode = 404;
                 response.end("Not found");
                 return;
             }
-            void transport.handleRequest(request, response).catch((error) => {
+            // Stateless mode: one Server and one transport per request.
+            const server = createMcpServer();
+            const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+            response.once("close", () => {
+                void transport.close().catch(() => { });
+                void server.close().catch(() => { });
+            });
+            void server
+                .connect(transport)
+                .then(() => transport.handleRequest(request, response))
+                .catch((error) => {
                 if (!response.headersSent)
                     response.statusCode = 500;
                 response.end(error instanceof Error ? error.message : "MCP transport error");
             });
         });
         await new Promise((resolve, reject) => httpServer.listen(port, "127.0.0.1", resolve).once("error", reject));
+        installShutdown(client, "http");
         writeDiagnosticEvent("mcp_transport_connected", { mode: "http", port });
         console.error(`c64bridge MCP server running on HTTP at http://127.0.0.1:${port}/mcp`);
     }
     else {
+        const server = createMcpServer();
         const transport = new StdioServerTransport();
         await server.connect(transport);
+        installShutdown(client, "stdio");
         writeDiagnosticEvent("mcp_transport_connected", { mode: "stdio" });
         console.error("c64bridge MCP server running on stdio");
     }
@@ -489,6 +605,8 @@ export async function renderPlatformStatusMarkdown(client) {
         "",
         `Current platform: \`${status.id}\``,
         "",
+        `Access mode: \`${getAccessMode()}\` (\`${ACCESS_ENV_VAR}\`; full allows everything, no-destructive blocks power, flash, drive ROM, image creation and debug register operations, read-only allows only read operations)`,
+        "",
         "## Available Backends",
         "",
         ...availableBackends.map((backend) => `- \`${backend}\`${backend === status.id ? " (active)" : ""}`),
@@ -520,6 +638,11 @@ export async function renderPlatformStatusMarkdown(client) {
                 .map((tool) => `\`${tool}\``)
                 .join(", ")}`
             : "- Unsupported tools: _none_");
+        lines.push(info.unsupported_operations.length > 0
+            ? `- Unsupported operations of supported tools (${info.unsupported_operations.length}): ${info.unsupported_operations
+                .map((operation) => `\`${operation}\``)
+                .join(", ")}`
+            : "- Unsupported operations of supported tools: _none_");
         lines.push("");
     }
     lines.push("> Use `c64_select_backend` to switch to another available backend without restarting the MCP server.");