@hs-x/mcp 0.3.0 → 0.3.7

package/dist/index.js

@@ -1,9 +1,10 @@
 import { readFileSync } from 'node:fs';
+import { request as httpsRequest } from 'node:https';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validateProject } from '@hs-x/validator';
 import { Redacted } from 'effect';
-import { loadMcpConfig } from './config.js';
+import { isPrivateOrLoopbackHostname, loadMcpConfig } from './config.js';
 /**
  * serverInfo.version is read from this package's own package.json at runtime —
  * never hardcoded. (Hardcoded version constants shipped stale repeatedly:
@@ -31,6 +32,8 @@ export const MCP_PROTOCOL_VERSION = '2024-11-05';
 const rootArgSchema = {
     type: 'string',
     description: 'Project root. Defaults to the MCP server working directory.',
+    minLength: 1,
+    maxLength: 4096,
 };
 const tools = [
     {
@@ -38,6 +41,7 @@ const tools = [
         description: 'Return local HS-X project status using the same validation substrate as the CLI.',
         inputSchema: {
             type: 'object',
+            additionalProperties: false,
             properties: {
                 root: rootArgSchema,
             },
@@ -48,79 +52,50 @@ const tools = [
         description: 'Run hs-x check for a local project and return structured diagnostics.',
         inputSchema: {
             type: 'object',
+            additionalProperties: false,
             properties: {
                 root: rootArgSchema,
             },
         },
     },
     {
-        name: 'hsx.dev.capabilities',
-        description: 'List the workers and capabilities (tools, triggers, card backends, syncs) declared by a local HS-X project — the targets hsx.dev.invoke accepts.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                root: rootArgSchema,
-            },
-        },
-    },
-    {
-        name: 'hsx.dev.invoke',
-        description: 'Invoke one capability of a local HS-X project through the PRODUCTION runtime router (payload validation, context, handler, result envelope — exactly what a deployed Worker runs). Fixture defaults fill the dispatch payload; pass input/enrolledObject/install to override. Works on freshly-migrated apps.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                root: rootArgSchema,
-                capabilityId: { type: 'string', description: 'Capability id (see hsx.dev.capabilities).' },
-                input: { type: 'object', description: 'Handler input (default: {}).' },
-                enrolledObject: {
-                    type: 'object',
-                    description: 'Enrolled object {id, objectType, properties} (default: fixture).',
-                },
-                install: { type: 'object', description: 'Install identity (default: local fixture).' },
-            },
-        },
-    },
-    {
-        name: 'hsx.dev.invoke_last',
-        description: 'Replay the last recorded invocation for a local HS-X project (.hs-x/last-invocation.json) — the failure-replay loop.',
+        name: 'hsx.dev.session.status',
+        description: 'Health + identity of an existing HS-X project dev session.',
         inputSchema: {
             type: 'object',
-            properties: {
-                root: rootArgSchema,
-            },
+            additionalProperties: false,
+            properties: { root: rootArgSchema },
         },
     },
     {
-        name: 'hsx.dev.session.start',
-        description: 'Start a dev server for a local HS-X project (background process; logs to .hs-x/dev-server.log). Returns the URL once /_hsx/health responds. One session per project.',
+        name: 'hsx.dev.session.stop',
+        description: 'Stop the project dev session (SIGTERM to the recorded pid).',
         inputSchema: {
             type: 'object',
-            properties: {
-                root: rootArgSchema,
-                port: { type: 'number', description: 'Port (default 8787).' },
-            },
+            additionalProperties: false,
+            properties: { root: rootArgSchema },
         },
     },
-    {
-        name: 'hsx.dev.session.status',
-        description: 'Health + identity of the project dev session started via hsx.dev.session.start.',
-        inputSchema: { type: 'object', properties: { root: rootArgSchema } },
-    },
-    {
-        name: 'hsx.dev.session.stop',
-        description: 'Stop the project dev session (SIGTERM to the recorded pid).',
-        inputSchema: { type: 'object', properties: { root: rootArgSchema } },
-    },
     {
         name: 'hsx.dev.logs',
         description: 'The project log surface: tails the dev session log (.hs-x/dev-server.log) AND, when the project has a deployed HubSpot app binding, includes HubSpot app-log rows (card/extension renders, proxy executions, webhooks, OAuth) — the same merged timeline as `hs-x logs`.',
         inputSchema: {
             type: 'object',
+            additionalProperties: false,
             properties: {
                 root: rootArgSchema,
-                lines: { type: 'number', description: 'Trailing local lines (default 50).' },
+                lines: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 1000,
+                    default: 50,
+                    description: 'Trailing local lines (default 50, max 1000).',
+                },
                 sinceMinutes: {
-                    type: 'number',
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 10_080,
+                    default: 15,
                     description: 'HubSpot app-log lookback window in minutes (default 15, max 10080).',
                 },
             },
@@ -128,17 +103,22 @@ const tools = [
     },
     {
         name: 'hsx.secrets.hubspot_oauth.set',
-        description: 'Store a HubSpot app OAuth client secret for one HS-X account/project/environment/app.',
+        description: 'Store a HubSpot app OAuth client secret for one HS-X account/project/environment/app. This credential mutation requires confirm: true.',
         inputSchema: {
             type: 'object',
+            additionalProperties: false,
+            required: ['accountId', 'projectId', 'hubSpotAppId', 'clientId', 'clientSecret', 'confirm'],
             properties: {
-                accountId: { type: 'string' },
-                projectId: { type: 'string' },
-                hubSpotAppId: { type: 'number' },
-                clientId: { type: 'string' },
-                clientSecret: { type: 'string' },
+                accountId: { type: 'string', minLength: 1, maxLength: 128, pattern: '\\S' },
+                projectId: { type: 'string', minLength: 1, maxLength: 128, pattern: '\\S' },
+                hubSpotAppId: { type: 'integer', minimum: 1, maximum: Number.MAX_SAFE_INTEGER },
+                clientId: { type: 'string', minLength: 1, maxLength: 512, pattern: '\\S' },
+                clientSecret: { type: 'string', minLength: 1, maxLength: 4096, pattern: '\\S' },
                 environment: { type: 'string', enum: ['dev', 'staging', 'production'] },
-                controlPlaneUrl: { type: 'string' },
+                confirm: {
+                    type: 'boolean',
+                    description: 'Must be true to explicitly confirm this credential mutation before HS-X reads a bearer credential or sends a network request.',
+                },
             },
         },
     },
@@ -147,12 +127,23 @@ const tools = [
         description: 'Search the HS-X documentation (guides, answers, reference) by keyword. Returns ranked pages with title, section, the markdown URL, and a summary. Follow up with hsx.docs.fetch to read a page in full.',
         inputSchema: {
             type: 'object',
+            additionalProperties: false,
+            required: ['query'],
             properties: {
                 query: {
                     type: 'string',
+                    minLength: 1,
+                    maxLength: 512,
+                    pattern: '\\S',
                     description: 'Keywords to search for, e.g. "webhook signature dedup".',
                 },
-                limit: { type: 'number', description: 'Max results (default 8, max 25).' },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 25,
+                    default: 8,
+                    description: 'Max results (default 8, max 25).',
+                },
             },
         },
     },
@@ -161,8 +152,16 @@ const tools = [
         description: 'Fetch one HS-X documentation page as clean markdown. Pass a docs path or URL from hsx.docs.search (e.g. "/docs/guides/triggers" or "/docs/guides/triggers.md").',
         inputSchema: {
             type: 'object',
+            additionalProperties: false,
+            required: ['path'],
             properties: {
-                path: { type: 'string', description: 'Docs path or URL (with or without the .md suffix).' },
+                path: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 2048,
+                    pattern: '\\S',
+                    description: 'Docs path or URL (with or without the .md suffix).',
+                },
             },
         },
     },
@@ -170,7 +169,50 @@ const tools = [
 export function listMcpTools() {
     return tools;
 }
-export async function handleMcpRequest(request, context) {
+class JsonRpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function decodeJsonRpcRequest(input) {
+    if (!isRecord(input) || Array.isArray(input)) {
+        return { ok: false, message: 'Invalid Request: expected a JSON-RPC request object.' };
+    }
+    if (input.jsonrpc !== '2.0') {
+        return { ok: false, message: 'Invalid Request: jsonrpc must be "2.0".' };
+    }
+    if (typeof input.method !== 'string' || input.method.length === 0) {
+        return { ok: false, message: 'Invalid Request: method must be a non-empty string.' };
+    }
+    if (input.id !== undefined &&
+        !(typeof input.id === 'string' ||
+            (typeof input.id === 'number' && Number.isSafeInteger(input.id)))) {
+        return { ok: false, message: 'Invalid Request: id must be a string or integer.' };
+    }
+    if (input.params !== undefined && (!isRecord(input.params) || Array.isArray(input.params))) {
+        return { ok: false, message: 'Invalid Request: params must be an object when provided.' };
+    }
+    return {
+        ok: true,
+        request: {
+            jsonrpc: '2.0',
+            method: input.method,
+            ...(input.id !== undefined ? { id: input.id } : {}),
+            ...(input.params !== undefined ? { params: input.params } : {}),
+        },
+    };
+}
+function rpcFailure(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+export async function handleMcpRequest(input, context) {
+    const decoded = decodeJsonRpcRequest(input);
+    if (!decoded.ok) {
+        return rpcFailure(null, -32600, decoded.message);
+    }
+    const request = decoded.request;
     try {
         const result = await dispatchMcpRequest(request, context);
         if (request.id === undefined) {
@@ -182,18 +224,19 @@ export async function handleMcpRequest(request, context) {
         if (request.id === undefined) {
             return undefined;
         }
-        return {
-            jsonrpc: '2.0',
-            id: request.id ?? null,
-            error: {
-                code: -32000,
-                message: error instanceof Error ? error.message : String(error),
-            },
-        };
+        const code = error instanceof JsonRpcError ? error.code : -32000;
+        return rpcFailure(request.id ?? null, code, error instanceof Error ? error.message : String(error));
     }
 }
 export async function callMcpTool(name, args, context) {
-    const root = projectRoot(args, context);
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool)
+        throw new Error(`Unknown MCP tool: ${name}`);
+    validateToolArguments(tool, args);
+    if (name === 'hsx.secrets.hubspot_oauth.set' && args.confirm !== true) {
+        throw new Error('hsx.secrets.hubspot_oauth.set requires confirm: true before storing OAuth credentials.');
+    }
+    const root = await projectRoot(args, context);
     if (name === 'hsx.status') {
         const validation = await validateProject({ root });
         const diagnosticsBySeverity = { error: 0, warning: 0 };
@@ -215,6 +258,7 @@ export async function callMcpTool(name, args, context) {
         });
     }
     if (name === 'hsx.dev.capabilities') {
+        requireUnsafeProjectExecutionOptIn(context, name);
         const { loadProjectWorkers, DevInvokeError } = await import('@hs-x/cli/dev/invoke');
         try {
             const workers = await loadProjectWorkers(root);
@@ -236,6 +280,7 @@ export async function callMcpTool(name, args, context) {
         }
     }
     if (name === 'hsx.dev.invoke' || name === 'hsx.dev.invoke_last') {
+        requireUnsafeProjectExecutionOptIn(context, name);
         const { invokeCapabilityLocally, loadLastInvocation, DevInvokeError } = await import('@hs-x/cli/dev/invoke');
         let capabilityId;
         let payloadOverrides = {};
@@ -283,74 +328,119 @@ export async function callMcpTool(name, args, context) {
         }
     }
     if (name === 'hsx.dev.session.start') {
-        const port = typeof args.port === 'number' ? args.port : 8787;
+        requireUnsafeProjectExecutionOptIn(context, name);
+        const port = optionalPort(args.port);
         const existing = await readDevSession(root);
-        if (existing && (await devSessionHealthy(existing.port))) {
-            return content({ ok: true, command: 'dev session start', alreadyRunning: true, ...existing });
+        if (existing) {
+            if ((await devSessionMatchesProcess(existing, root)) &&
+                (await devSessionHealthy(existing.port))) {
+                return content({
+                    ok: true,
+                    command: 'dev session start',
+                    alreadyRunning: true,
+                    ...(await devSessionView(root, existing)),
+                });
+            }
+            throw new Error('The dev-session record does not identify a live HS-X dev process for this project. Refusing to overwrite it; verify the process, then remove .hs-x/dev-session.json manually.');
         }
         const { spawn } = await import('node:child_process');
-        const { mkdir } = await import('node:fs/promises');
-        const { createWriteStream } = await import('node:fs');
-        const { join } = await import('node:path');
-        await mkdir(join(root, '.hs-x'), { recursive: true });
-        const logPath = join(root, '.hs-x', 'dev-server.log');
-        const log = createWriteStream(logPath, { flags: 'a' });
         // HSX_MCP_DEV_BINARY lets tests point at the repo CLI; default = installed hs-x.
         const binary = process.env.HSX_MCP_DEV_BINARY ?? 'hs-x';
         const [command, ...prefixArgs] = binary.split(' ');
-        const child = spawn(command, [...prefixArgs, 'dev', '--cwd', root, '--port', String(port)], {
-            detached: true,
-            stdio: ['ignore', 'pipe', 'pipe'],
+        if (!command)
+            throw new Error('HSX_MCP_DEV_BINARY must name an executable.');
+        const { logPath, stream: log } = await openDevLogForAppend(root);
+        const child = (() => {
+            try {
+                return spawn(command, [...prefixArgs, 'dev', '--cwd', root, '--port', String(port)], {
+                    detached: true,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+            }
+            catch (error) {
+                log.end();
+                throw error;
+            }
+        })();
+        let spawnError;
+        child.once('error', (error) => {
+            spawnError = error;
         });
         child.stdout?.pipe(log);
         child.stderr?.pipe(log);
         child.unref();
-        const session = { pid: child.pid ?? 0, port, url: `http://127.0.0.1:${port}`, logPath };
-        await writeDevSession(root, session);
+        const childPid = child.pid;
+        if (!Number.isSafeInteger(childPid) || (childPid ?? 0) <= 0) {
+            log.end();
+            throw new Error('Could not start the HS-X dev process: no safe child pid was assigned.');
+        }
+        const session = { schemaVersion: 1, pid: childPid, port };
+        try {
+            await writeDevSession(root, session);
+        }
+        catch (error) {
+            child.kill('SIGTERM');
+            log.end();
+            throw error;
+        }
         // A source-loaded CLI can take longer to boot while the full CI suite is
         // saturating the runner. Keep polling for 30s before declaring failure.
         for (let attempt = 0; attempt < 120; attempt += 1) {
+            if (spawnError) {
+                await removeDevSession(root);
+                log.end();
+                throw new Error(`Could not start the HS-X dev process: ${spawnError.message}`);
+            }
             if (await devSessionHealthy(port)) {
-                return content({ ok: true, command: 'dev session start', ...session });
+                return content({
+                    ok: true,
+                    command: 'dev session start',
+                    ...(await devSessionView(root, session)),
+                });
             }
             await new Promise((resolve) => setTimeout(resolve, 250));
         }
-        const { readFile } = await import('node:fs/promises');
-        const logTail = await readFile(logPath, 'utf8')
-            .then((raw) => raw.split('\n').filter(Boolean).slice(-10).join('\n'))
-            .catch(() => '');
+        child.kill('SIGTERM');
+        await removeDevSession(root);
+        log.end();
+        const logTail = (await readBoundedLogTail(root, 10)).join('\n');
         throw new Error(`Dev server did not become healthy on port ${port} within 30s — read the log via hsx.dev.logs.${logTail ? `\n${logTail}` : ''}`);
     }
     if (name === 'hsx.dev.session.status') {
         const session = await readDevSession(root);
         if (!session)
             return content({ ok: false, command: 'dev session status', running: false });
-        const healthy = await devSessionHealthy(session.port);
-        return content({ ok: healthy, command: 'dev session status', running: healthy, ...session });
+        const processMatches = await devSessionMatchesProcess(session, root);
+        const healthy = processMatches && (await devSessionHealthy(session.port));
+        return content({
+            ok: healthy,
+            command: 'dev session status',
+            running: healthy,
+            ...(await devSessionView(root, session)),
+            ...(processMatches ? {} : { reason: 'recorded process identity mismatch' }),
+        });
     }
     if (name === 'hsx.dev.session.stop') {
         const session = await readDevSession(root);
         if (!session)
             return content({ ok: true, command: 'dev session stop', running: false });
+        if (!(await devSessionMatchesProcess(session, root))) {
+            throw new Error('Refusing to stop the recorded pid because it is not the HS-X dev process for this project.');
+        }
         try {
             process.kill(session.pid, 'SIGTERM');
         }
-        catch {
-            // already gone
+        catch (error) {
+            throw new Error(`Could not stop HS-X dev pid ${session.pid}: ${error instanceof Error ? error.message : String(error)}`);
         }
-        const { rm } = await import('node:fs/promises');
-        const { join } = await import('node:path');
-        await rm(join(root, '.hs-x', 'dev-session.json'), { force: true });
+        await removeDevSession(root);
         return content({ ok: true, command: 'dev session stop', stopped: session.pid });
     }
     if (name === 'hsx.dev.logs') {
-        const lines = typeof args.lines === 'number' ? args.lines : 50;
-        const { readFile } = await import('node:fs/promises');
-        const { join } = await import('node:path');
-        const session = await readDevSession(root);
-        const logPath = session?.logPath ?? join(root, '.hs-x', 'dev-server.log');
-        const raw = await readFile(logPath, 'utf8').catch(() => '');
-        const tail = raw.split('\n').filter(Boolean).slice(-lines);
+        const lines = optionalLogLines(args.lines);
+        const paths = await resolveDevStatePaths(root, false);
+        const logPath = paths.logPath;
+        const tail = await readBoundedLogTail(root, lines);
         // One log surface: the same HubSpot app-log rows `hs-x logs` merges.
         // Missing binding/credentials degrades to a reason, never an error.
         const sinceMinutes = typeof args.sinceMinutes === 'number'
@@ -396,20 +486,36 @@ export async function callMcpTool(name, args, context) {
         const clientSecret = requiredString(args, 'clientSecret');
         const environment = optionalString(args, 'environment') ?? 'production';
         const config = resolveMcpConfig(context);
-        const controlPlaneUrl = optionalString(args, 'controlPlaneUrl') ?? config.controlPlaneUrl.toString();
-        const response = await fetch(new URL(`/v1/accounts/${encodeURIComponent(accountId)}/projects/${encodeURIComponent(projectId)}/hubspot-apps/${encodeURIComponent(String(hubSpotAppId))}/oauth-secret`, controlPlaneUrl), {
-            method: 'PUT',
-            headers: {
-                'content-type': 'application/json',
+        if (args.controlPlaneUrl !== undefined) {
+            throw new Error('controlPlaneUrl is server-configured and cannot be supplied by an MCP tool call.');
+        }
+        const addresses = await requirePublicControlPlaneResolution(config.controlPlaneUrl, context.lookup);
+        const target = new URL(`/v1/accounts/${encodeURIComponent(accountId)}/projects/${encodeURIComponent(projectId)}/hubspot-apps/${encodeURIComponent(String(hubSpotAppId))}/oauth-secret`, config.controlPlaneUrl);
+        const requestBody = JSON.stringify({ clientId, clientSecret, environment });
+        const credentialResponse = context.fetch
+            ? await context.fetch(target, {
+                method: 'PUT',
+                redirect: 'error',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${sessionToken}`,
+                },
+                body: requestBody,
+            })
+            : await (context.credentialRequest ?? requestPinnedCredentialJson)({
+                url: target,
+                addresses,
                 authorization: `Bearer ${sessionToken}`,
-            },
-            body: JSON.stringify({ clientId, clientSecret, environment }),
-        });
-        const body = await response.json().catch(() => undefined);
-        if (!response.ok) {
+                body: requestBody,
+            });
+        const status = credentialResponse.status;
+        const body = credentialResponse instanceof Response
+            ? await readBoundedResponseJson(credentialResponse, MAX_CREDENTIAL_RESPONSE_BYTES, 'Control-plane credential response')
+            : credentialResponse.body;
+        if (status < 200 || status >= 300) {
             throw new Error(isRecord(body) && typeof body.message === 'string'
                 ? body.message
-                : `Control plane returned ${response.status}`);
+                : `Control plane returned ${status}`);
         }
         // Whitelist non-sensitive response fields. Never echo client secret material
         // (or any other token-shaped value) back through the MCP transport.
@@ -430,13 +536,17 @@ export async function callMcpTool(name, args, context) {
         const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), 25) : 8;
         const docsUrl = resolveMcpConfig(context).docsUrl;
         const catalogUrl = new URL('/llms.txt', docsUrl);
-        const response = await fetch(catalogUrl, { signal: AbortSignal.timeout(8000) }).catch((error) => {
+        const response = await (context.fetch ?? fetch)(catalogUrl, {
+            signal: AbortSignal.timeout(8000),
+        }).catch((error) => {
             throw new Error(`Could not reach the docs catalog at ${catalogUrl.toString()}: ${error instanceof Error ? error.message : String(error)}`);
         });
         if (!response.ok) {
+            void response.body?.cancel().catch(() => undefined);
             throw new Error(`Docs catalog returned ${response.status} from ${catalogUrl.toString()}`);
         }
-        const entries = parseDocsCatalog(await response.text());
+        const catalog = await readBoundedResponseText(response, MAX_DOCS_CATALOG_RESPONSE_BYTES, 'Docs catalog response');
+        const entries = parseDocsCatalog(catalog);
         const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
         const results = entries
             .map((entry) => ({ entry, score: scoreDocEntry(entry, terms) }))
@@ -476,17 +586,107 @@ export async function callMcpTool(name, args, context) {
         if (!path.endsWith('.md'))
             path = `${path.replace(/\/+$/, '')}.md`;
         const target = new URL(path, docsUrl);
-        const response = await fetch(target, { signal: AbortSignal.timeout(8000) }).catch((error) => {
+        const response = await (context.fetch ?? fetch)(target, {
+            signal: AbortSignal.timeout(8000),
+        }).catch((error) => {
             throw new Error(`Could not reach ${target.toString()}: ${error instanceof Error ? error.message : String(error)}`);
         });
         if (!response.ok) {
+            void response.body?.cancel().catch(() => undefined);
             throw new Error(`Doc not found (${response.status}): ${path}`);
         }
         // Return the markdown directly — it IS the useful payload for an agent.
-        return { content: [{ type: 'text', text: await response.text() }] };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: await readBoundedResponseText(response, MAX_DOCS_PAGE_RESPONSE_BYTES, 'Docs page response'),
+                },
+            ],
+        };
     }
     throw new Error(`Unknown MCP tool: ${name}`);
 }
+const MAX_DOCS_CATALOG_RESPONSE_BYTES = 1024 * 1024;
+const MAX_DOCS_PAGE_RESPONSE_BYTES = 2 * 1024 * 1024;
+async function readBoundedResponseJson(response, maxBytes, label) {
+    const text = await readBoundedResponseText(response, maxBytes, label);
+    return parseUpstreamJson(text, label);
+}
+async function readBoundedResponseText(response, maxBytes, label) {
+    if (declaredContentLengthExceeds(response.headers.get('content-length'), maxBytes)) {
+        void response.body?.cancel().catch(() => undefined);
+        throw new Error(`${label} exceeded ${formatByteLimit(maxBytes)}.`);
+    }
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+    let bytes = 0;
+    let text = '';
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            bytes += chunk.value.byteLength;
+            if (bytes > maxBytes) {
+                throw new Error(`${label} exceeded ${formatByteLimit(maxBytes)}.`);
+            }
+            try {
+                text += decoder.decode(chunk.value, { stream: true });
+            }
+            catch {
+                throw new Error(`${label} was not valid UTF-8.`);
+            }
+        }
+        try {
+            return text + decoder.decode();
+        }
+        catch {
+            throw new Error(`${label} was not valid UTF-8.`);
+        }
+    }
+    catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function decodeUpstreamUtf8(bytes, label) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new Error(`${label} was not valid UTF-8.`);
+    }
+}
+function parseUpstreamJson(text, label) {
+    if (text.length === 0) {
+        throw new Error(`${label} was empty; expected JSON.`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${label} was not valid JSON.`);
+    }
+}
+function declaredContentLengthExceeds(value, maxBytes) {
+    const normalized = value?.trim();
+    if (!normalized || !/^\d+$/.test(normalized))
+        return false;
+    return BigInt(normalized) > BigInt(maxBytes);
+}
+function formatByteLimit(maxBytes) {
+    if (maxBytes % (1024 * 1024) === 0)
+        return `${maxBytes / (1024 * 1024)} MiB`;
+    if (maxBytes % 1024 === 0)
+        return `${maxBytes / 1024} KiB`;
+    return `${maxBytes} bytes`;
+}
 /** Parse the docs site's /llms.txt catalog: `## Section` headers and
  *  `- [Title](/docs/...md): description` entries. */
 function parseDocsCatalog(text) {
@@ -495,16 +695,20 @@ function parseDocsCatalog(text) {
     for (const raw of text.split('\n')) {
         const line = raw.trimEnd();
         const sectionMatch = line.match(/^##\s+(.+)$/);
-        if (sectionMatch) {
-            section = sectionMatch[1].trim();
+        const sectionTitle = sectionMatch?.[1];
+        if (sectionTitle) {
+            section = sectionTitle.trim();
             continue;
         }
         const entryMatch = line.match(/^-\s+\[([^\]]+)\]\(([^)]+)\):\s*(.+)$/);
-        if (entryMatch) {
+        const title = entryMatch?.[1];
+        const url = entryMatch?.[2];
+        const description = entryMatch?.[3];
+        if (title && url && description) {
             entries.push({
-                title: entryMatch[1].trim(),
-                url: entryMatch[2].trim(),
-                description: entryMatch[3].trim(),
+                title: title.trim(),
+                url: url.trim(),
+                description: description.trim(),
                 section,
             });
         }
@@ -541,43 +745,160 @@ async function dispatchMcpRequest(request, context) {
     }
     if (request.method === 'tools/call') {
         const params = parseToolCallParams(request.params);
-        return callMcpTool(params.name, params.arguments, context);
+        if (!tools.some((tool) => tool.name === params.name)) {
+            throw new JsonRpcError(-32602, `Unknown MCP tool: ${params.name}`);
+        }
+        try {
+            return await callMcpTool(params.name, params.arguments, context);
+        }
+        catch (error) {
+            return toolError(params.name, error);
+        }
+    }
+    if (request.method === 'notifications/initialized' ||
+        request.method === 'notifications/cancelled') {
+        return {};
     }
-    throw new Error(`Unsupported MCP method: ${request.method ?? '(missing)'}`);
+    throw new JsonRpcError(-32601, `Unsupported MCP method: ${request.method}`);
 }
 function parseToolCallParams(params) {
-    if (!isRecord(params) || typeof params.name !== 'string') {
-        throw new Error('tools/call requires params.name');
+    if (!isRecord(params) || Array.isArray(params) || typeof params.name !== 'string') {
+        throw new JsonRpcError(-32602, 'tools/call requires params.name');
     }
-    if (params.arguments !== undefined && !isRecord(params.arguments)) {
-        throw new Error('tools/call params.arguments must be an object when provided');
+    for (const key of Object.keys(params)) {
+        if (key !== 'name' && key !== 'arguments') {
+            throw new JsonRpcError(-32602, `Unexpected tools/call parameter: ${key}`);
+        }
+    }
+    if (params.name.length === 0 || params.name.length > 256) {
+        throw new JsonRpcError(-32602, 'tools/call params.name must be 1 to 256 characters');
+    }
+    if (params.arguments !== undefined &&
+        (!isRecord(params.arguments) || Array.isArray(params.arguments))) {
+        throw new JsonRpcError(-32602, 'tools/call params.arguments must be an object when provided');
     }
     return {
         name: params.name,
         arguments: params.arguments ?? {},
     };
 }
-function projectRoot(args, context) {
+function validateToolArguments(tool, args) {
+    validateObjectAgainstSchema(args, tool.inputSchema, 'arguments');
+}
+function validateObjectAgainstSchema(value, schema, path) {
+    for (const required of schema.required ?? []) {
+        if (!(required in value) || value[required] === undefined) {
+            throw new Error(`${path}.${required} is required`);
+        }
+    }
+    if (schema.additionalProperties === false) {
+        for (const key of Object.keys(value)) {
+            if (!schema.properties || !(key in schema.properties)) {
+                throw new Error(`${path}.${key} is not allowed`);
+            }
+        }
+    }
+    for (const [key, propertySchema] of Object.entries(schema.properties ?? {})) {
+        const propertyValue = value[key];
+        if (propertyValue === undefined)
+            continue;
+        validateValueAgainstSchema(propertyValue, propertySchema, `${path}.${key}`);
+    }
+}
+function validateValueAgainstSchema(value, schema, path) {
+    if (schema.type === 'string') {
+        if (typeof value !== 'string')
+            throw new Error(`${path} must be a string`);
+        if (schema.minLength !== undefined && value.length < schema.minLength) {
+            throw new Error(`${path} must contain at least ${schema.minLength} character(s)`);
+        }
+        if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+            throw new Error(`${path} must contain at most ${schema.maxLength} characters`);
+        }
+        if (schema.pattern && !new RegExp(schema.pattern, 'u').test(value)) {
+            throw new Error(`${path} does not match the required format`);
+        }
+    }
+    else if (schema.type === 'number' || schema.type === 'integer') {
+        if (typeof value !== 'number' ||
+            !Number.isFinite(value) ||
+            (schema.type === 'integer' && !Number.isSafeInteger(value))) {
+            throw new Error(`${path} must be ${schema.type === 'integer' ? 'an integer' : 'a number'}`);
+        }
+        if (schema.minimum !== undefined && value < schema.minimum) {
+            throw new Error(`${path} must be at least ${schema.minimum}`);
+        }
+        if (schema.maximum !== undefined && value > schema.maximum) {
+            throw new Error(`${path} must be at most ${schema.maximum}`);
+        }
+    }
+    else if (schema.type === 'boolean') {
+        if (typeof value !== 'boolean')
+            throw new Error(`${path} must be a boolean`);
+    }
+    else {
+        if (!isRecord(value) || Array.isArray(value))
+            throw new Error(`${path} must be an object`);
+        if (schema.properties || schema.additionalProperties === false) {
+            validateObjectAgainstSchema(value, schema, path);
+        }
+    }
+    if (schema.enum && !schema.enum.includes(value)) {
+        throw new Error(`${path} must be one of: ${schema.enum.join(', ')}`);
+    }
+}
+async function projectRoot(args, context) {
     if (args.root !== undefined && typeof args.root !== 'string') {
         throw new Error('root must be a string when provided');
     }
     const rootArg = args.root ?? '.';
-    const allowedRoots = buildAllowedRoots(context);
     const resolved = resolve(context.cwd, rootArg);
+    const containmentError = 'root must resolve within the MCP working directory or an HSX_MCP_ALLOWED_ROOTS entry';
+    if (!buildLexicalAllowedRoots(context).some((allowed) => isWithin(resolved, allowed))) {
+        throw new Error(containmentError);
+    }
+    const { realpath, stat } = await import('node:fs/promises');
+    const allowedRoots = await buildAllowedRoots(context);
+    let canonicalRoot;
+    try {
+        canonicalRoot = await realpath(resolved);
+        if (!(await stat(canonicalRoot)).isDirectory()) {
+            throw new Error('root must resolve to a directory');
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'root must resolve to a directory')
+            throw error;
+        throw new Error('root must resolve to an existing directory');
+    }
     for (const allowed of allowedRoots) {
-        if (isWithin(resolved, allowed)) {
-            return resolved;
+        if (isWithin(canonicalRoot, allowed)) {
+            return canonicalRoot;
         }
     }
-    throw new Error('root must resolve within the MCP working directory or an HSX_MCP_ALLOWED_ROOTS entry');
+    throw new Error(containmentError);
 }
-function buildAllowedRoots(context) {
+function buildLexicalAllowedRoots(context) {
     const config = resolveMcpConfig(context);
-    const roots = new Set();
-    roots.add(resolve(context.cwd));
+    const lexicalRoots = new Set();
+    lexicalRoots.add(resolve(context.cwd));
     for (const entry of config.allowedRoots) {
         if (isAbsolute(entry)) {
-            roots.add(resolve(entry));
+            lexicalRoots.add(resolve(entry));
+        }
+    }
+    return Array.from(lexicalRoots);
+}
+async function buildAllowedRoots(context) {
+    const { realpath } = await import('node:fs/promises');
+    const lexicalRoots = buildLexicalAllowedRoots(context);
+    const roots = new Set();
+    for (const lexicalRoot of lexicalRoots) {
+        try {
+            roots.add(await realpath(lexicalRoot));
+        }
+        catch {
+            // A configured root that does not exist cannot authorize anything.
         }
     }
     return Array.from(roots);
@@ -605,6 +926,111 @@ function readSessionToken(_context) {
 function resolveMcpConfig(context) {
     return context.config ?? loadMcpConfig();
 }
+async function requirePublicControlPlaneResolution(origin, injectedLookup) {
+    const lookup = injectedLookup ??
+        (async (hostname) => {
+            const { lookup: dnsLookup } = await import('node:dns/promises');
+            return dnsLookup(hostname, { all: true, verbatim: true });
+        });
+    let addresses;
+    try {
+        addresses = await lookup(origin.hostname.replace(/^\[|\]$/g, ''));
+    }
+    catch (error) {
+        throw new Error(`Could not resolve the configured control-plane origin safely: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (addresses.length === 0 ||
+        addresses.some((entry) => isPrivateOrLoopbackHostname(entry.address))) {
+        throw new Error('The configured control-plane origin resolves to a private or loopback address; refusing to send credentials.');
+    }
+    return addresses;
+}
+const MAX_CREDENTIAL_RESPONSE_BYTES = 64 * 1024;
+class CredentialRequestPolicyError extends Error {
+}
+async function requestPinnedCredentialJson(input) {
+    if (input.addresses.length === 0) {
+        throw new Error('The configured control-plane origin resolved to no addresses.');
+    }
+    let lastError;
+    for (const pinned of input.addresses) {
+        try {
+            return await requestPinnedCredentialJsonAtAddress(input, pinned);
+        }
+        catch (error) {
+            if (error instanceof CredentialRequestPolicyError)
+                throw error;
+            lastError = error;
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error('Could not connect to any validated control-plane address.');
+}
+async function requestPinnedCredentialJsonAtAddress(input, pinned) {
+    const lookup = (_hostname, options, callback) => {
+        if (typeof options === 'object' && options.all) {
+            callback(null, [{ ...pinned }]);
+            return;
+        }
+        callback(null, pinned.address, pinned.family);
+    };
+    return new Promise((resolve, reject) => {
+        const request = httpsRequest(input.url, {
+            method: 'PUT',
+            lookup,
+            headers: {
+                accept: 'application/json',
+                authorization: input.authorization,
+                'content-type': 'application/json',
+                'content-length': Buffer.byteLength(input.body),
+            },
+        }, (response) => {
+            const status = response.statusCode ?? 0;
+            if (status >= 300 && status < 400) {
+                response.resume();
+                reject(new CredentialRequestPolicyError('Control-plane redirects are not allowed for credential requests.'));
+                return;
+            }
+            const declaredLength = response.headers['content-length'];
+            if (declaredContentLengthExceeds(Array.isArray(declaredLength) ? declaredLength[0] : declaredLength, MAX_CREDENTIAL_RESPONSE_BYTES)) {
+                response.resume();
+                reject(new CredentialRequestPolicyError(`Control-plane credential response exceeded ${formatByteLimit(MAX_CREDENTIAL_RESPONSE_BYTES)}.`));
+                return;
+            }
+            const chunks = [];
+            let bytes = 0;
+            response.on('data', (chunk) => {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                bytes += buffer.byteLength;
+                if (bytes > MAX_CREDENTIAL_RESPONSE_BYTES) {
+                    response.destroy(new CredentialRequestPolicyError(`Control-plane credential response exceeded ${formatByteLimit(MAX_CREDENTIAL_RESPONSE_BYTES)}.`));
+                    return;
+                }
+                chunks.push(buffer);
+            });
+            response.on('end', () => {
+                try {
+                    const text = decodeUpstreamUtf8(Buffer.concat(chunks), 'Control-plane credential response');
+                    resolve({ status, body: parseUpstreamJson(text, 'Control-plane credential response') });
+                }
+                catch (error) {
+                    reject(new CredentialRequestPolicyError(error instanceof Error ? error.message : String(error)));
+                }
+            });
+            response.on('error', reject);
+        });
+        request.setTimeout(8_000, () => {
+            request.destroy(new Error('Control-plane credential request timed out.'));
+        });
+        request.on('error', reject);
+        request.end(input.body);
+    });
+}
+function requireUnsafeProjectExecutionOptIn(context, toolName) {
+    void context;
+    throw new Error(`${toolName} is not available: HS-X does not expose project-code execution through the local MCP process. Use the hs-x CLI directly until an isolated execution service exists.`);
+}
 function requiredString(args, key) {
     const value = args[key];
     if (typeof value !== 'string' || value.length === 0) {
@@ -633,24 +1059,236 @@ function content(value) {
         content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     };
 }
+function toolError(toolName, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ ok: false, tool: toolName, error: message }, null, 2),
+            },
+        ],
+    };
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
 async function readDevSession(root) {
+    const { constants } = await import('node:fs');
+    const { open } = await import('node:fs/promises');
+    const paths = await resolveDevStatePaths(root, false);
+    if (!paths.stateDirectoryExists)
+        return undefined;
+    let handle;
+    let raw;
     try {
-        const { readFile } = await import('node:fs/promises');
-        const { join } = await import('node:path');
-        const parsed = JSON.parse(await readFile(join(root, '.hs-x', 'dev-session.json'), 'utf8'));
-        return typeof parsed.pid === 'number' && typeof parsed.port === 'number' ? parsed : undefined;
+        handle = await open(paths.sessionPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const metadata = await handle.stat();
+        if (!metadata.isFile()) {
+            throw new Error('The dev-session record is not a regular file; refusing to trust it.');
+        }
+        if (metadata.size > 16 * 1024) {
+            throw new Error('The dev-session record is too large; refusing to trust it.');
+        }
+        raw = await handle.readFile('utf8');
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
     }
     catch {
-        return undefined;
+        throw new Error('The dev-session record is not valid JSON; refusing to trust it.');
     }
+    if (!isRecord(parsed) || Array.isArray(parsed)) {
+        throw new Error('The dev-session record has an invalid schema; refusing to trust it.');
+    }
+    const keys = Object.keys(parsed).sort();
+    if (keys.join(',') !== 'pid,port,schemaVersion' ||
+        parsed.schemaVersion !== 1 ||
+        !Number.isSafeInteger(parsed.pid) ||
+        parsed.pid <= 0 ||
+        !Number.isSafeInteger(parsed.port) ||
+        parsed.port < 1 ||
+        parsed.port > 65_535) {
+        throw new Error('The dev-session record has an invalid schema; refusing to trust it.');
+    }
+    return parsed;
 }
 async function writeDevSession(root, session) {
-    const { writeFile } = await import('node:fs/promises');
+    const { open } = await import('node:fs/promises');
+    const paths = await resolveDevStatePaths(root, true);
+    let handle;
+    try {
+        handle = await open(paths.sessionPath, 'wx', 0o600);
+        await handle.writeFile(`${JSON.stringify(session, null, 2)}\n`, 'utf8');
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'EEXIST') {
+            throw new Error('A dev-session record already exists; refusing to overwrite it.');
+        }
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function removeDevSession(root) {
+    const { rm } = await import('node:fs/promises');
+    const paths = await resolveDevStatePaths(root, false);
+    if (paths.stateDirectoryExists)
+        await rm(paths.sessionPath, { force: true });
+}
+async function devSessionView(root, session) {
+    const paths = await resolveDevStatePaths(root, false);
+    return {
+        pid: session.pid,
+        port: session.port,
+        url: `http://127.0.0.1:${session.port}`,
+        logPath: paths.logPath,
+    };
+}
+async function devSessionMatchesProcess(session, root) {
+    if (!Number.isSafeInteger(session.pid) || session.pid <= 0)
+        return false;
+    const binary = process.env.HSX_MCP_DEV_BINARY ?? 'hs-x';
+    const [, ...prefixArgs] = binary.split(' ');
+    const expectedSuffix = [...prefixArgs, 'dev', '--cwd', root, '--port', String(session.port)].join(' ');
+    try {
+        const { execFile } = await import('node:child_process');
+        const command = await new Promise((resolvePromise, reject) => {
+            execFile('ps', ['-ww', '-p', String(session.pid), '-o', 'command='], { timeout: 1500, maxBuffer: 64 * 1024 }, (error, stdout) => {
+                if (error)
+                    reject(error);
+                else
+                    resolvePromise(stdout.trim());
+            });
+        });
+        return command === expectedSuffix || command.endsWith(` ${expectedSuffix}`);
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveDevStatePaths(root, create) {
+    const { mkdir, realpath, stat } = await import('node:fs/promises');
     const { join } = await import('node:path');
-    await writeFile(join(root, '.hs-x', 'dev-session.json'), `${JSON.stringify(session, null, 2)}\n`);
+    const canonicalRoot = await realpath(root);
+    const lexicalStateDirectory = join(canonicalRoot, '.hs-x');
+    if (create)
+        await mkdir(lexicalStateDirectory, { recursive: true, mode: 0o700 });
+    let canonicalStateDirectory;
+    try {
+        canonicalStateDirectory = await realpath(lexicalStateDirectory);
+    }
+    catch (error) {
+        if (!create && isNodeError(error) && error.code === 'ENOENT') {
+            return {
+                stateDirectoryExists: false,
+                stateDirectory: lexicalStateDirectory,
+                sessionPath: join(lexicalStateDirectory, 'dev-session.json'),
+                logPath: join(lexicalStateDirectory, 'dev-server.log'),
+            };
+        }
+        throw error;
+    }
+    if (!isWithin(canonicalStateDirectory, canonicalRoot)) {
+        throw new Error('The .hs-x directory resolves outside the project root; refusing access.');
+    }
+    const state = await stat(canonicalStateDirectory);
+    if (!state.isDirectory()) {
+        throw new Error('The .hs-x path is not a directory; refusing access.');
+    }
+    return {
+        stateDirectoryExists: true,
+        stateDirectory: canonicalStateDirectory,
+        sessionPath: join(canonicalStateDirectory, 'dev-session.json'),
+        logPath: join(canonicalStateDirectory, 'dev-server.log'),
+    };
+}
+const MAX_LOG_LINES = 1000;
+const MAX_LOG_TAIL_BYTES = 256 * 1024;
+function optionalLogLines(value) {
+    if (value === undefined)
+        return 50;
+    if (!Number.isSafeInteger(value) || value < 1 || value > MAX_LOG_LINES) {
+        throw new Error(`lines must be an integer from 1 to ${MAX_LOG_LINES}`);
+    }
+    return value;
+}
+function optionalPort(value) {
+    if (value === undefined)
+        return 8787;
+    if (!Number.isSafeInteger(value) || value < 1 || value > 65_535) {
+        throw new Error('port must be an integer from 1 to 65535');
+    }
+    return value;
+}
+async function readBoundedLogTail(root, lines) {
+    const { constants } = await import('node:fs');
+    const { open, realpath } = await import('node:fs/promises');
+    const paths = await resolveDevStatePaths(root, false);
+    if (!paths.stateDirectoryExists)
+        return [];
+    let canonicalLogPath;
+    try {
+        canonicalLogPath = await realpath(paths.logPath);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    if (!isWithin(canonicalLogPath, paths.stateDirectory)) {
+        throw new Error('The dev log resolves outside .hs-x; refusing access.');
+    }
+    const handle = await open(canonicalLogPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile()) {
+            throw new Error('The dev log is not a regular file; refusing access.');
+        }
+        const bytes = Math.min(metadata.size, MAX_LOG_TAIL_BYTES);
+        const start = metadata.size - bytes;
+        const buffer = Buffer.alloc(bytes);
+        const { bytesRead } = await handle.read(buffer, 0, bytes, start);
+        let text = buffer.subarray(0, bytesRead).toString('utf8');
+        if (start > 0)
+            text = text.slice(Math.max(0, text.indexOf('\n') + 1));
+        return text.split('\n').filter(Boolean).slice(-lines);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function openDevLogForAppend(root) {
+    const { constants } = await import('node:fs');
+    const { open } = await import('node:fs/promises');
+    const paths = await resolveDevStatePaths(root, true);
+    const handle = await open(paths.logPath, constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile()) {
+            throw new Error('The dev log is not a regular file; refusing access.');
+        }
+        await handle.chmod(0o600);
+        return { logPath: paths.logPath, stream: handle.createWriteStream() };
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
 }
 async function devSessionHealthy(port) {
     try {