@codragraph/cli 2.1.0 → 2.1.4

package/dist/mcp/tools.js

@@ -84,6 +84,177 @@ SERVICE: optional monorepo path prefix (POSIX-style, case-sensitive segments). W
             required: ['query'],
         },
     },
+    {
+        name: 'feature_clusters',
+        description: `List human-facing feature clusters such as Settings, AI, Auth, Billing, MCP, or Ingestion.
+
+WHEN TO USE: First step for targeted implementation/refactoring when you need the functional area map before loading files. This is the product/domain layer above algorithmic Community nodes.
+AFTER THIS: Use feature_context(name) for members with file paths and line ranges, then context() or impact() on specific symbols.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Optional cluster owner search term (e.g. "settings", "AI", "billing").',
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max feature clusters to return (default: 100)',
+                    default: 100,
+                    minimum: 1,
+                    maximum: 500,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'feature_context',
+        description: `Get a complete context pack for one FeatureCluster.
+
+Returns the cluster metadata, member symbols/files with line ranges, outgoing/incoming feature dependencies, and related execution processes.
+
+WHEN TO USE: Before editing a feature area like Settings or AI. This narrows exploration to the exact files and symbols in that feature cluster.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Feature cluster name, slug, or id (e.g. "Settings", "settings").',
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max members to return (default: 100)',
+                    default: 100,
+                    minimum: 1,
+                    maximum: 500,
+                },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'cluster_query',
+        description: `Cluster-first alias for feature_clusters.
+
+WHEN TO USE: Ask which product/domain cluster owns an area like Settings, AI, Auth, or Billing before loading files.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Optional cluster owner search term (e.g. "settings", "AI", "billing").',
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max feature clusters to return (default: 100)',
+                    default: 100,
+                    minimum: 1,
+                    maximum: 500,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'cluster_context',
+        description: `Cluster-first alias for feature_context.
+
+Returns a FeatureCluster context pack with members, entry points, routes, tools, tests, docs, dependencies, and safe edit surface.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Feature cluster name, slug, or id (e.g. "Settings", "settings").',
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max members to return (default: 100)',
+                    default: 100,
+                    minimum: 1,
+                    maximum: 500,
+                },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'context_pack',
+        description: `Get the compact agent context pack for a FeatureCluster.
+
+WHEN TO USE: Before a refactor or implementation task where the agent should avoid re-exploring the full repo.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Feature cluster name, slug, or id (e.g. "AI", "ai").',
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max members to return (default: 100)',
+                    default: 100,
+                    minimum: 1,
+                    maximum: 500,
+                },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'cluster_impact',
+        description: `Assess feature-level blast radius for a FeatureCluster.
+
+Returns upstream/downstream cluster dependencies plus the same context pack and safe edit surface used for targeted edits.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Feature cluster name, slug, or id.',
+                },
+                direction: {
+                    type: 'string',
+                    enum: ['upstream', 'downstream', 'both'],
+                    description: 'Dependency direction to inspect.',
+                    default: 'upstream',
+                },
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max members to include in the context pack (default: 100)',
+                    default: 100,
+                    minimum: 1,
+                    maximum: 500,
+                },
+            },
+            required: ['name'],
+        },
+    },
     {
         name: 'cypher',
         description: `Execute Cypher query against the code knowledge graph.
@@ -92,10 +263,10 @@ WHEN TO USE: Complex structural queries that search/explore can't answer. READ c
 AFTER THIS: Use context() on result symbols for deeper context.
 
 SCHEMA:
-- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process, Route, Tool
+- Nodes: File, Folder, Function, Class, Interface, Method, CodeElement, Community, Process, FeatureCluster, Route, Tool
 - Multi-language nodes (use backticks): \`Struct\`, \`Enum\`, \`Trait\`, \`Impl\`, etc.
 - All edges via single CodeRelation table with 'type' property
-- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF
+- Edge types: CONTAINS, DEFINES, CALLS, IMPORTS, EXTENDS, IMPLEMENTS, HAS_METHOD, HAS_PROPERTY, ACCESSES, METHOD_OVERRIDES, METHOD_IMPLEMENTS, MEMBER_OF, STEP_IN_PROCESS, HANDLES_ROUTE, FETCHES, HANDLES_TOOL, ENTRY_POINT_OF, WRAPS, QUERIES, FEATURE_MEMBER_OF, FEATURE_DEPENDS_ON
 - Edge properties: type (STRING), confidence (DOUBLE), reason (STRING), step (INT32)
 
 EXAMPLES:
@@ -129,6 +300,7 @@ TIPS:
 - All relationships use single CodeRelation table — filter with {type: 'CALLS'} etc.
 - Community = auto-detected functional area (Leiden algorithm). Properties: heuristicLabel, cohesion, symbolCount, keywords, description, enrichedBy
 - Process = execution flow trace from entry point to terminal. Properties: heuristicLabel, processType, stepCount, communities, entryPointId, terminalId
+- FeatureCluster = product/domain area for targeted context packs. Properties: name, slug, featureKind, summary, repo, service, memberCount, entryPointIds, routes, tools, testCoverageHints, lastIndexedCommit, confidence, signals
 - Use heuristicLabel (not label) for human-readable community/process names`,
         inputSchema: {
             type: 'object',

package/dist/server/api.d.ts

@@ -9,6 +9,7 @@
  */
 import express from 'express';
 import { type GraphNode, type GraphRelationship } from '../_shared/index.js';
+import { type WebDashboardMode } from './web-dashboard.js';
 /**
  * Determine whether an HTTP Origin header value is allowed by CORS policy.
  *
@@ -20,13 +21,16 @@ import { type GraphNode, type GraphRelationship } from '../_shared/index.js';
  *     10.0.0.0/8      → 10.x.x.x
  *     172.16.0.0/12   → 172.16.x.x – 172.31.x.x
  *     192.168.0.0/16  → 192.168.x.x
- * - https://codragraph.vercel.app — the deployed CodraGraph web UI
+ * - Hosted CodraGraph web UI — defaults to https://codragraph.vercel.app
  *
  * @param origin - The value of the HTTP `Origin` request header, or `undefined`
  *                 when the header is absent (non-browser request).
  * @returns `true` if the origin is allowed, `false` otherwise.
  */
 export declare const isAllowedOrigin: (origin: string | undefined) => boolean;
+export interface CreateServerOptions {
+    web?: WebDashboardMode;
+}
 type GraphStreamRecord = {
     type: 'node';
     data: GraphNode;
@@ -41,7 +45,15 @@ export declare class ClientDisconnectedError extends Error {
     constructor();
 }
 export declare const isIgnorableGraphQueryError: (err: unknown) => boolean;
+export interface GraphStoreErrorResponse {
+    error: string;
+    code: 'GRAPHSTORE_CORRUPT';
+    operation: string;
+    recovery: string[];
+}
+export declare const isGraphStoreCorruptionError: (err: unknown) => boolean;
+export declare const getGraphStoreErrorResponse: (err: unknown, operation: string) => GraphStoreErrorResponse | null;
 export declare const writeNdjsonRecord: (res: express.Response, record: GraphStreamRecord, signal?: AbortSignal) => Promise<void>;
 export declare const streamGraphNdjson: (res: express.Response, includeContent?: boolean, signal?: AbortSignal) => Promise<void>;
-export declare const createServer: (port: number, host?: string) => Promise<void>;
+export declare const createServer: (port: number, host?: string, options?: CreateServerOptions) => Promise<void>;
 export {};

package/dist/server/api.js

@@ -22,7 +22,8 @@ import { hybridSearch } from '../core/search/hybrid-search.js';
 // Embedding imports are lazy (dynamic import) to avoid loading onnxruntime-node
 // at server startup — crashes on unsupported Node ABI versions (#89)
 import { LocalBackend } from '../mcp/local/local-backend.js';
-import { mountMCPEndpoints } from './mcp-http.js';
+import { getMcpHttpRouteGuidance, mountMCPEndpoints } from './mcp-http.js';
+import { HOSTED_WEB_APP_URL, getWebDashboardInfo, mountWebDashboard, } from './web-dashboard.js';
 import { fork } from 'child_process';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { JobManager } from './analyze-job.js';
@@ -40,7 +41,7 @@ const pkg = _require('../../package.json');
  *     10.0.0.0/8      → 10.x.x.x
  *     172.16.0.0/12   → 172.16.x.x – 172.31.x.x
  *     192.168.0.0/16  → 192.168.x.x
- * - https://codragraph.vercel.app — the deployed CodraGraph web UI
+ * - Hosted CodraGraph web UI — defaults to https://codragraph.vercel.app
  *
  * @param origin - The value of the HTTP `Origin` request header, or `undefined`
  *                 when the header is absent (non-browser request).
@@ -57,7 +58,7 @@ export const isAllowedOrigin = (origin) => {
         origin === 'http://127.0.0.1' ||
         origin.startsWith('http://[::1]:') ||
         origin === 'http://[::1]' ||
-        origin === 'https://codragraph.vercel.app') {
+        origin === HOSTED_WEB_APP_URL) {
         return true;
     }
     // RFC 1918 private network ranges — allow any port on these hosts.
@@ -104,6 +105,30 @@ export const isIgnorableGraphQueryError = (err) => {
         message.includes('not found') ||
         message.includes('No table named'));
 };
+export const isGraphStoreCorruptionError = (err) => {
+    const message = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (message.includes('wal checksum') ||
+        (message.includes('wal') && message.includes('corrupt')) ||
+        (message.includes('checksum') && message.includes('corrupt')) ||
+        message.includes('database disk image is malformed') ||
+        message.includes('database image is malformed'));
+};
+export const getGraphStoreErrorResponse = (err, operation) => {
+    if (!isGraphStoreCorruptionError(err))
+        return null;
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        error: message || 'Graph store is corrupted',
+        code: 'GRAPHSTORE_CORRUPT',
+        operation,
+        recovery: [
+            'Stop overlapping codragraph serve, mcp, analyze, and embedding jobs for this repo.',
+            'Retry: npx @codragraph/cli analyze --force',
+            'If this repo had embeddings, preserve them with: npx @codragraph/cli analyze --force --embeddings',
+            'Only after approval, use: npx @codragraph/cli clean --force',
+        ],
+    };
+};
 const ensureStreamIsWritable = (res, signal) => {
     if (signal?.aborted || res.destroyed || res.writableEnded) {
         throw new ClientDisconnectedError();
@@ -202,6 +227,9 @@ const getNodeQuery = (table, includeContent) => {
     if (table === 'Process') {
         return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.label AS label, n.heuristicLabel AS heuristicLabel, n.processType AS processType, n.stepCount AS stepCount, n.communities AS communities, n.entryPointId AS entryPointId, n.terminalId AS terminalId`;
     }
+    if (table === 'FeatureCluster') {
+        return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.slug AS slug, n.featureKind AS featureKind, n.summary AS summary, n.description AS description, n.repo AS repo, n.service AS service, n.signals AS signals, n.memberCount AS memberCount, n.entryPointIds AS entryPointIds, n.routes AS routes, n.tools AS tools, n.testCoverageHints AS testCoverageHints, n.lastIndexedCommit AS lastIndexedCommit, n.confidence AS confidence, n.source AS source`;
+    }
     if (table === 'Route') {
         return `MATCH (n:${tableLabel}) RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.responseKeys AS responseKeys, n.errorKeys AS errorKeys, n.middleware AS middleware`;
     }
@@ -233,6 +261,20 @@ const mapGraphNodeRow = (table, row, includeContent) => ({
         communities: row.communities,
         entryPointId: row.entryPointId,
         terminalId: row.terminalId,
+        slug: row.slug,
+        featureKind: row.featureKind,
+        summary: row.summary,
+        repo: row.repo,
+        service: row.service,
+        signals: row.signals,
+        memberCount: row.memberCount,
+        entryPointIds: row.entryPointIds,
+        routes: row.routes,
+        tools: row.tools,
+        testCoverageHints: row.testCoverageHints,
+        lastIndexedCommit: row.lastIndexedCommit,
+        confidence: row.confidence,
+        source: row.source,
     },
 });
 const mapGraphRelationshipRow = (row) => ({
@@ -338,6 +380,8 @@ const mountSSEProgress = (app, routePath, jm) => {
     });
 };
 const statusFromError = (err) => {
+    if (isGraphStoreCorruptionError(err))
+        return 503;
     const msg = String(err?.message ?? '');
     if (msg.includes('No indexed repositories') || msg.includes('not found'))
         return 404;
@@ -354,9 +398,14 @@ const requestedRepo = (req) => {
     }
     return undefined;
 };
-export const createServer = async (port, host = '127.0.0.1') => {
+export const createServer = async (port, host = '127.0.0.1', options = {}) => {
     const app = express();
     app.disable('x-powered-by');
+    let webDashboard = {
+        mode: options.web ?? 'local',
+        served: false,
+        hostedUrl: HOSTED_WEB_APP_URL,
+    };
     // CORS: allow localhost, private/LAN networks, and the deployed site.
     // Non-browser requests (curl, server-to-server) have no origin and are allowed.
     // Disallowed origins get the response without Access-Control-Allow-Origin,
@@ -503,7 +552,15 @@ export const createServer = async (port, host = '127.0.0.1') => {
         else {
             launchContext = 'global';
         }
-        res.json({ version: pkg.version, launchContext, nodeVersion: process.version });
+        const displayHost = host === '::' || host === '0.0.0.0' ? 'localhost' : host;
+        const apiBaseUrl = `http://${displayHost}:${port}`;
+        res.json({
+            version: pkg.version,
+            launchContext,
+            nodeVersion: process.version,
+            mcp: getMcpHttpRouteGuidance(),
+            web: getWebDashboardInfo(webDashboard, apiBaseUrl),
+        });
     });
     // List all registered repos
     app.get('/api/repos', async (_req, res) => {
@@ -978,10 +1035,13 @@ export const createServer = async (port, host = '127.0.0.1') => {
             if (err instanceof ClientDisconnectedError) {
                 return;
             }
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.graph');
             const message = err.message || 'Failed to build graph';
             if (res.headersSent) {
                 try {
-                    res.write(JSON.stringify({ type: 'error', error: message }) + '\n');
+                    res.write(JSON.stringify(graphStoreError
+                        ? { type: 'error', ...graphStoreError }
+                        : { type: 'error', error: message }) + '\n');
                 }
                 catch {
                     // Best-effort only after streaming has started.
@@ -989,6 +1049,10 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 res.end();
                 return;
             }
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
             res.status(500).json({ error: message });
         }
     });
@@ -1014,9 +1078,63 @@ export const createServer = async (port, host = '127.0.0.1') => {
             res.json({ result });
         }
         catch (err) {
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.query');
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
             res.status(500).json({ error: err.message || 'Query failed' });
         }
     });
+    // Symbol context through the same LocalBackend path as MCP `context`
+    app.post('/api/context', async (req, res) => {
+        try {
+            const name = String(req.body?.name ?? '').trim();
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" in request body' });
+                return;
+            }
+            const result = await backend.callTool('context', {
+                ...req.body,
+                name,
+                repo: requestedRepo(req),
+            });
+            res.json(result);
+        }
+        catch (err) {
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.context');
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
+            res.status(statusFromError(err)).json({ error: err.message || 'Context query failed' });
+        }
+    });
+    // Symbol impact through the same LocalBackend path as MCP `impact`
+    app.post('/api/impact', async (req, res) => {
+        try {
+            const target = String(req.body?.target ?? '').trim();
+            if (!target) {
+                res.status(400).json({ error: 'Missing "target" in request body' });
+                return;
+            }
+            const result = await backend.callTool('impact', {
+                ...req.body,
+                target,
+                direction: req.body?.direction ?? 'upstream',
+                repo: requestedRepo(req),
+            });
+            res.json(result);
+        }
+        catch (err) {
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.impact');
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
+            res.status(statusFromError(err)).json({ error: err.message || 'Impact query failed' });
+        }
+    });
     // Search (supports mode: 'hybrid' | 'semantic' | 'bm25', and optional enrichment)
     app.post('/api/search', async (req, res) => {
         try {
@@ -1141,6 +1259,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
             res.json({ results });
         }
         catch (err) {
+            const graphStoreError = getGraphStoreErrorResponse(err, 'api.search');
+            if (graphStoreError) {
+                res.status(503).json(graphStoreError);
+                return;
+            }
             res.status(500).json({ error: err.message || 'Search failed' });
         }
     });
@@ -1326,6 +1449,66 @@ export const createServer = async (port, host = '127.0.0.1') => {
                 .json({ error: err.message || 'Failed to query cluster detail' });
         }
     });
+    // List all feature clusters
+    app.get('/api/feature-clusters', async (req, res) => {
+        try {
+            const limit = req.query.limit ? Number.parseInt(String(req.query.limit), 10) : undefined;
+            const query = String(req.query.query ?? '');
+            const result = await backend.queryFeatureClusters(requestedRepo(req), limit, query);
+            res.json(result);
+        }
+        catch (err) {
+            res
+                .status(statusFromError(err))
+                .json({ error: err.message || 'Failed to query feature clusters' });
+        }
+    });
+    // Feature cluster detail
+    app.get('/api/feature-cluster', async (req, res) => {
+        try {
+            const name = String(req.query.name ?? '').trim();
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const limit = req.query.limit ? Number.parseInt(String(req.query.limit), 10) : undefined;
+            const result = await backend.queryFeatureContext(name, requestedRepo(req), limit);
+            if (result?.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res
+                .status(statusFromError(err))
+                .json({ error: err.message || 'Failed to query feature cluster detail' });
+        }
+    });
+    // Feature cluster impact/context pack
+    app.get(['/api/feature-impact', '/api/cluster-impact'], async (req, res) => {
+        try {
+            const name = String(req.query.name ?? '').trim();
+            if (!name) {
+                res.status(400).json({ error: 'Missing "name" query parameter' });
+                return;
+            }
+            const limit = req.query.limit ? Number.parseInt(String(req.query.limit), 10) : undefined;
+            const directionText = String(req.query.direction ?? 'upstream');
+            const direction = directionText === 'downstream' || directionText === 'both' ? directionText : 'upstream';
+            const result = await backend.queryFeatureImpact(name, requestedRepo(req), direction, limit);
+            if (result?.error) {
+                res.status(404).json({ error: result.error });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            res
+                .status(statusFromError(err))
+                .json({ error: err.message || 'Failed to query feature cluster impact' });
+        }
+    });
     // ── Analyze API ──────────────────────────────────────────────────────
     // POST /api/analyze — start a new analysis job
     app.post('/api/analyze', async (req, res) => {
@@ -1697,6 +1880,7 @@ export const createServer = async (port, host = '127.0.0.1') => {
         embedJobManager.cancelJob(req.params.jobId, 'Cancelled by user');
         res.json({ id: job.id, status: 'failed', error: 'Cancelled by user' });
     });
+    webDashboard = mountWebDashboard(app, { mode: options.web ?? 'local' });
     // Global error handler — catch anything the route handlers miss
     app.use((err, _req, res, _next) => {
         console.error('Unhandled error:', err);
@@ -1707,7 +1891,22 @@ export const createServer = async (port, host = '127.0.0.1') => {
     await new Promise((resolve, reject) => {
         const server = app.listen(port, host, () => {
             const displayHost = host === '::' || host === '0.0.0.0' ? 'localhost' : host;
-            console.log(`CodraGraph server running on http://${displayHost}:${port}`);
+            const localUrl = `http://${displayHost}:${port}`;
+            console.log(`CodraGraph server running on ${localUrl}`);
+            if (webDashboard.served) {
+                console.log(`Web dashboard: ${localUrl}`);
+            }
+            else if (webDashboard.mode === 'hosted') {
+                console.log(`Hosted dashboard: ${webDashboard.hostedUrl}`);
+                console.log(`Connect it to local API: ${localUrl}`);
+            }
+            else if (webDashboard.mode === 'off') {
+                console.log('Web dashboard disabled (--web off).');
+            }
+            else {
+                console.warn(`Web dashboard not bundled: ${webDashboard.reason}`);
+                console.warn(`Hosted dashboard: ${webDashboard.hostedUrl}`);
+            }
             resolve();
         });
         server.on('error', (err) => reject(err));

package/dist/server/mcp-http.d.ts

@@ -10,4 +10,26 @@
  */
 import type { Express } from 'express';
 import type { LocalBackend } from '../mcp/local/local-backend.js';
+export declare const MCP_HTTP_ENDPOINT = "/api/mcp";
+export declare const UNSUPPORTED_MCP_REST_EXAMPLE = "/api/mcp/tools/list";
+export interface McpHttpRouteGuidance {
+    endpoint: string;
+    transport: 'streamable-http';
+    note: string;
+    unsupportedRestExample: string;
+    powershellHealthCheck: string;
+    clientInstruction: string;
+}
+export declare const getMcpHttpRouteGuidance: () => McpHttpRouteGuidance;
+export declare const getUnsupportedMcpRestRouteResponse: (path: string) => {
+    endpoint: string;
+    transport: "streamable-http";
+    note: string;
+    unsupportedRestExample: string;
+    powershellHealthCheck: string;
+    clientInstruction: string;
+    error: string;
+    code: string;
+    unsupportedRoute: string;
+};
 export declare function mountMCPEndpoints(app: Express, backend: LocalBackend): () => Promise<void>;

package/dist/server/mcp-http.js

@@ -11,6 +11,22 @@
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { createMCPServer } from '../mcp/server.js';
 import { randomUUID } from 'crypto';
+export const MCP_HTTP_ENDPOINT = '/api/mcp';
+export const UNSUPPORTED_MCP_REST_EXAMPLE = '/api/mcp/tools/list';
+export const getMcpHttpRouteGuidance = () => ({
+    endpoint: MCP_HTTP_ENDPOINT,
+    transport: 'streamable-http',
+    note: 'HTTP MCP is a protocol endpoint, not a REST tools namespace.',
+    unsupportedRestExample: UNSUPPORTED_MCP_REST_EXAMPLE,
+    powershellHealthCheck: "Invoke-RestMethod -Uri 'http://127.0.0.1:4747/api/info' -TimeoutSec 10",
+    clientInstruction: 'Point an MCP client at http://127.0.0.1:4747/api/mcp using StreamableHTTP.',
+});
+export const getUnsupportedMcpRestRouteResponse = (path) => ({
+    error: 'Unsupported MCP HTTP REST route',
+    code: 'MCP_HTTP_REST_ROUTE_UNSUPPORTED',
+    unsupportedRoute: path,
+    ...getMcpHttpRouteGuidance(),
+});
 /** Idle sessions are evicted after 30 minutes */
 const SESSION_TTL_MS = 30 * 60 * 1000;
 /** Cleanup sweep runs every 5 minutes */
@@ -72,7 +88,7 @@ export function mountMCPEndpoints(app, backend) {
             });
         }
     };
-    app.all('/api/mcp', (req, res) => {
+    app.all(MCP_HTTP_ENDPOINT, (req, res) => {
         void handleMcpRequest(req, res).catch((err) => {
             console.error('MCP HTTP request failed:', err);
             if (res.headersSent)
@@ -84,6 +100,9 @@ export function mountMCPEndpoints(app, backend) {
             });
         });
     });
+    app.all(/^\/api\/mcp\/.+/, (req, res) => {
+        res.status(200).json(getUnsupportedMcpRestRouteResponse(req.path));
+    });
     const cleanup = async () => {
         clearInterval(cleanupTimer);
         const closers = [...sessions.values()].map(async (session) => {
@@ -95,6 +114,6 @@ export function mountMCPEndpoints(app, backend) {
         sessions.clear();
         await Promise.allSettled(closers);
     };
-    console.log('MCP HTTP endpoints mounted at /api/mcp');
+    console.log(`MCP HTTP endpoint mounted at ${MCP_HTTP_ENDPOINT}`);
     return cleanup;
 }

package/dist/server/web-dashboard.d.ts

@@ -0,0 +1,28 @@
+import { type Express } from 'express';
+export declare const HOSTED_WEB_APP_URL: string;
+export type WebDashboardMode = 'local' | 'hosted' | 'off';
+export interface WebDashboardMountOptions {
+    mode?: WebDashboardMode;
+    webAppPath?: string;
+}
+export interface WebDashboardMount {
+    mode: WebDashboardMode;
+    served: boolean;
+    hostedUrl: string;
+    localPath?: string;
+    reason?: string;
+}
+export interface WebDashboardInfo {
+    mode: WebDashboardMode;
+    served: boolean;
+    localUrl: string | null;
+    hostedUrl: string;
+    apiBaseUrl: string;
+    reason?: string;
+}
+export declare const normalizeWebDashboardMode: (raw: string | undefined) => WebDashboardMode;
+export declare const getBundledWebAppCandidates: () => string[];
+export declare const hasWebDashboardIndex: (candidate: string) => boolean;
+export declare const resolveBundledWebAppPath: (candidates?: readonly string[]) => string | null;
+export declare const mountWebDashboard: (app: Express, options?: WebDashboardMountOptions) => WebDashboardMount;
+export declare const getWebDashboardInfo: (mount: WebDashboardMount, apiBaseUrl: string) => WebDashboardInfo;