@codragraph/cli 2.1.1 → 2.1.4

package/dist/core/run-analyze.js

@@ -10,18 +10,52 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
+import { execFileSync } from 'node:child_process';
 import * as fsSync from 'node:fs';
 import * as v8 from 'node:v8';
+import { getLanguageFromFilename } from '../_shared/index.js';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initCgdb, loadGraphToCgdb, getCgdbStats, executeQuery, executeWithReusedStatement, closeCgdb, loadCachedEmbeddings, } from './cgdb/cgdb-adapter.js';
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, INDEX_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
+import { shouldIgnorePath } from '../config/ignore-service.js';
 import { recordAnalysisSnapshot } from './graphstore/index.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './cgdb/schema.js';
 import { STALE_HASH_SENTINEL } from './cgdb/schema.js';
 /** Threshold: auto-skip embeddings for repos with more nodes than this */
 const EMBEDDING_NODE_LIMIT = 50_000;
+const GENERATED_AGENT_CONTEXT_PATHS = new Set(['agents.md', 'claude.md']);
+const GENERATED_AGENT_CONTEXT_PREFIXES = [
+    '.claude/skills/generated/',
+    '.cursor/rules/codragraph-generated/',
+];
+const IGNORE_CONTROL_FILES = new Set(['.gitignore', '.codragraphignore']);
+const GRAPH_CONFIG_BASENAMES = new Set([
+    'package.json',
+    'tsconfig.json',
+    'jsconfig.json',
+    'go.mod',
+    'cargo.toml',
+    'pyproject.toml',
+    'requirements.txt',
+    'composer.json',
+    'gemfile',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+    'settings.gradle',
+    'settings.gradle.kts',
+    'pubspec.yaml',
+    'pubspec.yml',
+    'mix.exs',
+    'rebar.config',
+    'cmakelists.txt',
+    'makefile',
+    'dockerfile',
+]);
+const GRAPH_CONFIG_PATTERNS = [/^tsconfig\..+\.json$/i, /^jsconfig\..+\.json$/i];
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
 export const PHASE_LABELS = {
     extracting: 'Scanning files',
     structure: 'Building structure',
@@ -38,6 +72,119 @@ export const PHASE_LABELS = {
     embeddings: 'Generating embeddings',
     done: 'Done',
 };
+const normalizeGitPath = (filePath) => filePath.replace(/\\/g, '/');
+export const parseGitNameStatus = (raw) => {
+    const tokens = raw.split('\0').filter(Boolean);
+    const changes = [];
+    for (let i = 0; i < tokens.length;) {
+        const status = tokens[i++] ?? '';
+        const code = status[0]?.toUpperCase();
+        if (code === 'R' || code === 'C') {
+            const previousPath = tokens[i++];
+            const nextPath = tokens[i++];
+            if (previousPath && nextPath) {
+                changes.push({
+                    status,
+                    path: normalizeGitPath(nextPath),
+                    previousPath: normalizeGitPath(previousPath),
+                });
+            }
+            continue;
+        }
+        const changedPath = tokens[i++];
+        if (status && changedPath) {
+            changes.push({ status, path: normalizeGitPath(changedPath) });
+        }
+    }
+    return changes;
+};
+export const listChangedPathsBetweenCommits = (repoPath, fromRef, toRef) => {
+    if (!fromRef || !toRef || fromRef === toRef)
+        return [];
+    try {
+        const stdout = execFileSync('git', ['diff', '--name-status', '-z', `${fromRef}..${toRef}`], {
+            cwd: repoPath,
+            encoding: 'utf8',
+            maxBuffer: 20 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return parseGitNameStatus(stdout);
+    }
+    catch {
+        return null;
+    }
+};
+export const isGeneratedAgentContextPath = (filePath) => {
+    const normalized = normalizeGitPath(filePath).toLowerCase();
+    const basename = path.posix.basename(normalized);
+    return (GENERATED_AGENT_CONTEXT_PATHS.has(basename) ||
+        GENERATED_AGENT_CONTEXT_PREFIXES.some((prefix) => normalized.startsWith(prefix)));
+};
+export const isGraphContentPath = (filePath) => {
+    const normalized = normalizeGitPath(filePath);
+    const basename = path.posix.basename(normalized);
+    const lowerBasename = basename.toLowerCase();
+    if (isGeneratedAgentContextPath(normalized))
+        return false;
+    if (IGNORE_CONTROL_FILES.has(lowerBasename))
+        return true;
+    if (shouldIgnorePath(normalized))
+        return false;
+    if (getLanguageFromFilename(normalized) !== null)
+        return true;
+    const ext = path.posix.extname(lowerBasename);
+    if (MARKDOWN_EXTENSIONS.has(ext))
+        return true;
+    if (GRAPH_CONFIG_BASENAMES.has(lowerBasename))
+        return true;
+    return GRAPH_CONFIG_PATTERNS.some((pattern) => pattern.test(basename));
+};
+export const changedPathAffectsGraph = (change) => {
+    const statusCode = change.status[0]?.toUpperCase();
+    const paths = [change.path, change.previousPath].filter((p) => Boolean(p));
+    if (paths.some(isGraphContentPath))
+        return true;
+    // Add/delete/rename/copy can change File/Folder structure even when content
+    // is not parsed. Ignored or generated-agent paths are outside the index.
+    if (statusCode === 'A' || statusCode === 'D' || statusCode === 'R' || statusCode === 'C') {
+        return paths.some((p) => !isGeneratedAgentContextPath(p) && !shouldIgnorePath(p));
+    }
+    // Modified non-code/non-doc files keep the same path and are not read by the
+    // graph pipeline, so the existing graph can be reused.
+    if (statusCode === 'M' || statusCode === 'T')
+        return false;
+    // Unknown git status: rebuild rather than risk stale graph state.
+    return true;
+};
+export const getGraphRelevantChangedPaths = (changes) => changes.filter(changedPathAffectsGraph);
+export const getAnalyzeConfigRebuildReason = (existingMeta, options) => {
+    const existingCompress = existingMeta.compress ?? 'none';
+    if (options.compress && options.compress !== existingCompress) {
+        return `requested compression changed from ${existingCompress} to ${options.compress}`;
+    }
+    if (options.embeddings && (existingMeta.stats?.embeddings ?? 0) === 0) {
+        return 'embeddings were requested but the existing index has no vectors';
+    }
+    return null;
+};
+const formatChangeForLog = (change) => change.previousPath ? `${change.previousPath} -> ${change.path}` : change.path;
+const buildReusedMeta = (existingMeta, repoPath, currentCommit) => ({
+    ...existingMeta,
+    repoPath,
+    lastCommit: currentCommit,
+    indexedAt: new Date().toISOString(),
+    schemaVersion: INDEX_SCHEMA_VERSION,
+    remoteUrl: hasGitDir(repoPath) ? getRemoteUrl(repoPath) : existingMeta.remoteUrl,
+});
+const pathExists = async (targetPath) => {
+    try {
+        await fs.stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 // ---------------------------------------------------------------------------
 // Main orchestrator
 // ---------------------------------------------------------------------------
@@ -135,9 +282,18 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // end-to-end yet, so the supported migration path is re-analyze via a fresh
     // CREATE NODE TABLE.
     const schemaUpToDate = !!existingMeta && (existingMeta.schemaVersion ?? 0) >= INDEX_SCHEMA_VERSION;
+    const existingCgdbPresent = existingMeta ? await pathExists(cgdbPath) : false;
+    const storageRebuildReason = existingMeta && schemaUpToDate && !existingCgdbPresent
+        ? 'graph database files are missing'
+        : null;
+    const configRebuildReason = storageRebuildReason ??
+        (existingMeta && schemaUpToDate && !options.force
+            ? getAnalyzeConfigRebuildReason(existingMeta, options)
+            : null);
     if (existingMeta &&
         schemaUpToDate &&
         !options.force &&
+        !configRebuildReason &&
         existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
@@ -149,6 +305,51 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             };
         }
     }
+    if (existingMeta && schemaUpToDate && !options.force && configRebuildReason) {
+        log(`Re-analyzing: ${configRebuildReason}.`);
+    }
+    if (existingMeta &&
+        schemaUpToDate &&
+        !options.force &&
+        !configRebuildReason &&
+        currentCommit !== '' &&
+        existingMeta.lastCommit !== currentCommit) {
+        const changedPaths = listChangedPathsBetweenCommits(repoPath, existingMeta.lastCommit, currentCommit);
+        if (changedPaths) {
+            const graphRelevantChanges = getGraphRelevantChangedPaths(changedPaths);
+            if (graphRelevantChanges.length === 0) {
+                const reusedMeta = buildReusedMeta(existingMeta, repoPath, currentCommit);
+                await saveMeta(storagePath, reusedMeta);
+                const projectName = await registerRepo(repoPath, reusedMeta, {
+                    name: options.registryName,
+                    allowDuplicateName: options.allowDuplicateName,
+                });
+                if (hasGitDir(repoPath)) {
+                    await addToGitignore(repoPath);
+                }
+                const reuseReason = `Smart analyze reused the existing graph; ${changedPaths.length} changed ` +
+                    `file(s) did not affect indexed code, docs, config, or file structure.`;
+                log(reuseReason);
+                progress('done', 100, 'Existing graph reused');
+                return {
+                    repoName: projectName,
+                    repoPath,
+                    stats: reusedMeta.stats ?? {},
+                    alreadyUpToDate: true,
+                    reusedExistingIndex: true,
+                    reuseReason,
+                };
+            }
+            const preview = graphRelevantChanges.slice(0, 5).map(formatChangeForLog).join(', ');
+            const suffix = graphRelevantChanges.length > 5 ? ', ...' : '';
+            log(`Smart analyze: ${graphRelevantChanges.length} indexed change(s) require rebuild` +
+                (preview ? ` (${preview}${suffix})` : '') +
+                '.');
+        }
+        else {
+            log('Smart analyze: could not inspect git diff; rebuilding.');
+        }
+    }
     if (existingMeta && !schemaUpToDate) {
         log(`Index schema version ${existingMeta.schemaVersion ?? '<missing>'} is older than ` +
             `${INDEX_SCHEMA_VERSION} (FeatureCluster context-pack schema). ` +

package/dist/core/search/hybrid-search.js

@@ -111,8 +111,16 @@ export const formatHybridResults = (results) => {
  * The semanticSearch function is injected to keep this module environment-agnostic.
  */
 export const hybridSearch = async (query, limit, executeQuery, semanticSearch) => {
-    // Use LadybugDB FTS for always-fresh BM25 results
-    const bm25Results = await searchFTSFromCgdb(query, limit);
-    const semanticResults = await semanticSearch(executeQuery, query, limit);
+    const bm25Promise = searchFTSFromCgdb(query, limit);
+    // Start semantic work immediately, but gate its DB calls behind BM25.
+    // semanticSearch performs embedding before it calls executeQuery, so this
+    // overlaps CPU/model work with BM25 while avoiding concurrent queries on the
+    // singleton LadybugDB connection used by CLI/HTTP paths.
+    const executeAfterBm25 = async (cypher) => {
+        await bm25Promise;
+        return executeQuery(cypher);
+    };
+    const semanticPromise = semanticSearch(executeAfterBm25, query, limit);
+    const [bm25Results, semanticResults] = await Promise.all([bm25Promise, semanticPromise]);
     return mergeWithRRF(bm25Results, semanticResults, limit);
 };

package/dist/mcp/resources.js

@@ -685,8 +685,8 @@ async function getSetupResource(backend) {
             '',
             '## Cross-platform commands',
             '',
-            '- Use `npx @codragraph/cli ...` or `codragraph ...` in Windows PowerShell, macOS bash/zsh, and Linux shells.',
-            '- Prefer `npm --prefix <package> <script>` from repo root for package checks instead of shell-specific `cd dir && ...` chains.',
+            '- Use `npx @codragraph/cli ...`, `bunx @codragraph/cli ...`, or `codragraph ...` in Windows PowerShell, macOS bash/zsh, and Linux shells.',
+            '- Prefer `npm --prefix <package> <script>` or `bun run --filter <workspace> <script>` from repo root for package checks instead of shell-specific `cd dir && ...` chains.',
         ];
         sections.push(lines.join('\n'));
     }

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();
@@ -355,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;
@@ -371,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,
@@ -520,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) => {
@@ -995,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.
@@ -1006,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 });
         }
     });
@@ -1031,6 +1078,11 @@ 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' });
         }
     });
@@ -1050,6 +1102,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
             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' });
         }
     });
@@ -1070,6 +1127,11 @@ export const createServer = async (port, host = '127.0.0.1') => {
             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' });
         }
     });
@@ -1197,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' });
         }
     });
@@ -1813,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);
@@ -1823,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;