@runtimescope/mcp-server 0.8.0 → 0.9.1

package/dist/index.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { execSync as execSync2 } from "child_process";
 import { existsSync as existsSync2 } from "fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -23,24 +22,44 @@ import {
   Redactor,
   resolveTlsConfig,
   PmStore,
-  ProjectDiscovery
+  ProjectDiscovery,
+  getPidsOnPort
 } from "@runtimescope/collector";
 
 // src/tools/network.ts
+import { z as z2 } from "zod";
+
+// src/tools/shared.ts
 import { z } from "zod";
+var projectIdParam = z.string().optional().describe(
+  "Scope to a specific project by its project ID (proj_xxx). Omit to query all sessions."
+);
+function resolveSessionContext(store, projectId) {
+  const all = store.getSessionInfo();
+  const sessions = projectId ? all.filter((s) => s.projectId === projectId) : all;
+  return {
+    sessions,
+    sessionId: sessions[0]?.sessionId ?? null,
+    projectId
+  };
+}
+
+// src/tools/network.ts
 function registerNetworkTools(server, store) {
   server.tool(
     "get_network_requests",
     "Get captured network (fetch) requests from the running web app. Returns URL, method, status, timing, and optional GraphQL operation info.",
     {
-      since_seconds: z.number().optional().describe("Only return requests from the last N seconds"),
-      url_pattern: z.string().optional().describe("Filter by URL substring match"),
-      status: z.number().optional().describe("Filter by HTTP status code"),
-      method: z.string().optional().describe("Filter by HTTP method (GET, POST, etc.)"),
-      limit: z.number().optional().describe("Max results to return (default 200, max 1000)")
+      project_id: projectIdParam,
+      since_seconds: z2.number().optional().describe("Only return requests from the last N seconds"),
+      url_pattern: z2.string().optional().describe("Filter by URL substring match"),
+      status: z2.number().optional().describe("Filter by HTTP status code"),
+      method: z2.string().optional().describe("Filter by HTTP method (GET, POST, etc.)"),
+      limit: z2.number().optional().describe("Max results to return (default 200, max 1000)")
     },
-    async ({ since_seconds, url_pattern, status, method, limit }) => {
+    async ({ project_id, since_seconds, url_pattern, status, method, limit }) => {
       const allEvents = store.getNetworkRequests({
+        projectId: project_id,
         sinceSeconds: since_seconds,
         urlPattern: url_pattern,
         status,
@@ -50,8 +69,7 @@ function registerNetworkTools(server, store) {
       const truncated = allEvents.length > maxLimit;
       const events = truncated ? allEvents.slice(0, maxLimit) : allEvents;
       const timeRange = events.length > 0 ? { from: events[events.length - 1].timestamp, to: events[0].timestamp } : { from: 0, to: 0 };
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const failedCount = events.filter((e) => e.status >= 400).length;
       const avgDuration = events.length > 0 ? (events.reduce((s, e) => s + e.duration, 0) / events.length).toFixed(0) : "0";
       const issues = [];
@@ -89,7 +107,7 @@ function registerNetworkTools(server, store) {
           timestamp: new Date(e.timestamp).toISOString()
         })),
         issues,
-        metadata: { timeRange, eventCount: events.length, totalCount: allEvents.length, truncated, sessionId }
+        metadata: { timeRange, eventCount: events.length, totalCount: allEvents.length, truncated, sessionId, projectId: project_id ?? null }
       };
       return {
         content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
@@ -99,19 +117,21 @@ function registerNetworkTools(server, store) {
 }
 
 // src/tools/console.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 function registerConsoleTools(server, store) {
   server.tool(
     "get_console_messages",
     "Get captured console messages (log, warn, error, info, debug, trace) from the running web app. Includes message text, args, and stack traces for errors.",
     {
-      level: z2.enum(["log", "warn", "error", "info", "debug", "trace"]).optional().describe("Filter by console level"),
-      since_seconds: z2.number().optional().describe("Only return messages from the last N seconds"),
-      search: z2.string().optional().describe("Search message text (case-insensitive substring match)"),
-      limit: z2.number().optional().describe("Max results to return (default 200, max 1000)")
+      project_id: projectIdParam,
+      level: z3.enum(["log", "warn", "error", "info", "debug", "trace"]).optional().describe("Filter by console level"),
+      since_seconds: z3.number().optional().describe("Only return messages from the last N seconds"),
+      search: z3.string().optional().describe("Search message text (case-insensitive substring match)"),
+      limit: z3.number().optional().describe("Max results to return (default 200, max 1000)")
     },
-    async ({ level, since_seconds, search, limit }) => {
+    async ({ project_id, level, since_seconds, search, limit }) => {
       const allEvents = store.getConsoleMessages({
+        projectId: project_id,
         level,
         sinceSeconds: since_seconds,
         search
@@ -120,8 +140,7 @@ function registerConsoleTools(server, store) {
       const truncated = allEvents.length > maxLimit;
       const events = truncated ? allEvents.slice(0, maxLimit) : allEvents;
       const timeRange = events.length > 0 ? { from: events[events.length - 1].timestamp, to: events[0].timestamp } : { from: 0, to: 0 };
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const levelCounts = {};
       for (const e of events) {
         levelCounts[e.level] = (levelCounts[e.level] || 0) + 1;
@@ -158,7 +177,7 @@ function registerConsoleTools(server, store) {
           timestamp: new Date(e.timestamp).toISOString()
         })),
         issues,
-        metadata: { timeRange, eventCount: events.length, totalCount: allEvents.length, truncated, sessionId }
+        metadata: { timeRange, eventCount: events.length, totalCount: allEvents.length, truncated, sessionId, projectId: project_id ?? null }
       };
       return {
         content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
@@ -172,13 +191,16 @@ function registerSessionTools(server, store) {
   server.tool(
     "get_session_info",
     "Get information about connected browser sessions and overall event statistics. Use this to check if the SDK is connected.",
-    {},
-    async () => {
-      const sessions = store.getSessionInfo();
+    {
+      project_id: projectIdParam
+    },
+    async ({ project_id }) => {
+      const { sessions, sessionId } = resolveSessionContext(store, project_id);
       const response = {
         summary: sessions.length > 0 ? `${sessions.length} session(s) connected. Total events captured: ${store.eventCount}.` : "No active sessions. Make sure the RuntimeScope SDK is injected in your app and connected to ws://localhost:9090.",
         data: sessions.map((s) => ({
           sessionId: s.sessionId,
+          projectId: s.projectId ?? null,
           appName: s.appName,
           sdkVersion: s.sdkVersion,
           connectedAt: new Date(s.connectedAt).toISOString(),
@@ -189,7 +211,8 @@ function registerSessionTools(server, store) {
         metadata: {
           timeRange: { from: 0, to: Date.now() },
           eventCount: store.eventCount,
-          sessionId: sessions[0]?.sessionId ?? null
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -221,18 +244,19 @@ function registerSessionTools(server, store) {
 }
 
 // src/tools/issues.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 import { detectIssues } from "@runtimescope/collector";
 function registerIssueTools(server, store, apiDiscovery, processMonitor) {
   server.tool(
     "detect_issues",
     "Run all pattern detectors against captured runtime data and return prioritized issues. Detects: failed requests, slow requests (>3s), N+1 request patterns, console error spam, high error rates, slow DB queries (>500ms), N+1 DB queries, API degradation, high latency endpoints, orphaned processes, and more. Use this as the first tool when investigating performance problems.",
     {
-      since_seconds: z3.number().optional().describe("Analyze events from the last N seconds (default: all events)"),
-      severity_filter: z3.enum(["high", "medium", "low"]).optional().describe("Only return issues at this severity or above")
+      project_id: projectIdParam,
+      since_seconds: z4.number().optional().describe("Analyze events from the last N seconds (default: all events)"),
+      severity_filter: z4.enum(["high", "medium", "low"]).optional().describe("Only return issues at this severity or above")
     },
-    async ({ since_seconds, severity_filter }) => {
-      const events = store.getAllEvents(since_seconds);
+    async ({ project_id, since_seconds, severity_filter }) => {
+      const events = store.getAllEvents(since_seconds, void 0, project_id);
       const allIssues = [...detectIssues(events)];
       if (apiDiscovery) {
         try {
@@ -252,8 +276,7 @@ function registerIssueTools(server, store, apiDiscovery, processMonitor) {
       const issues = allIssues.filter(
         (i) => severityOrder[i.severity] <= filterThreshold
       );
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const highCount = issues.filter((i) => i.severity === "high").length;
       const mediumCount = issues.filter((i) => i.severity === "medium").length;
       const lowCount = issues.filter((i) => i.severity === "low").length;
@@ -284,7 +307,8 @@ function registerIssueTools(server, store, apiDiscovery, processMonitor) {
             to: events.length > 0 ? events[events.length - 1].timestamp : 0
           },
           eventCount: events.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -295,26 +319,27 @@ function registerIssueTools(server, store, apiDiscovery, processMonitor) {
 }
 
 // src/tools/timeline.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 function registerTimelineTools(server, store) {
   server.tool(
     "get_event_timeline",
     "Get a chronological view of ALL events (network requests, console messages) interleaved by timestamp. Essential for understanding causal chains \u2014 e.g. seeing that an API call failed, then an error was logged, then another retry fired. Events are in chronological order (oldest first).",
     {
-      since_seconds: z4.number().optional().describe("Only return events from the last N seconds (default: 60)"),
-      event_types: z4.array(z4.enum(["network", "console", "session", "state", "render", "performance", "dom_snapshot", "database", "custom"])).optional().describe("Filter by event types (default: all)"),
-      limit: z4.number().optional().describe("Max events to return (default: 200, max: 1000)")
+      project_id: projectIdParam,
+      since_seconds: z5.number().optional().describe("Only return events from the last N seconds (default: 60)"),
+      event_types: z5.array(z5.enum(["network", "console", "session", "state", "render", "performance", "dom_snapshot", "database", "custom"])).optional().describe("Filter by event types (default: all)"),
+      limit: z5.number().optional().describe("Max events to return (default: 200, max: 1000)")
     },
-    async ({ since_seconds, event_types, limit }) => {
+    async ({ project_id, since_seconds, event_types, limit }) => {
       const sinceSeconds = since_seconds ?? 60;
       const maxEvents = Math.min(limit ?? 200, 1e3);
       const events = store.getEventTimeline({
+        projectId: project_id,
         sinceSeconds,
         eventTypes: event_types
       });
       const trimmed = events.length > maxEvents ? events.slice(events.length - maxEvents) : events;
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const typeCounts = {};
       for (const e of trimmed) {
         typeCounts[e.eventType] = (typeCounts[e.eventType] || 0) + 1;
@@ -331,7 +356,8 @@ function registerTimelineTools(server, store) {
           },
           eventCount: trimmed.length,
           totalInWindow: events.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -439,26 +465,27 @@ function formatTimelineEvent(event) {
 }
 
 // src/tools/state.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 function registerStateTools(server, store) {
   server.tool(
     "get_state_snapshots",
     "Get state store snapshots and diffs from Zustand or Redux stores. Shows state changes over time with action history, mutation frequency, and shallow diffs showing which keys changed.",
     {
-      store_name: z5.string().optional().describe("Filter by store name/ID"),
-      since_seconds: z5.number().optional().describe("Only return events from the last N seconds"),
-      limit: z5.number().optional().describe("Max results to return (default 200, max 1000)")
+      project_id: projectIdParam,
+      store_name: z6.string().optional().describe("Filter by store name/ID"),
+      since_seconds: z6.number().optional().describe("Only return events from the last N seconds"),
+      limit: z6.number().optional().describe("Max results to return (default 200, max 1000)")
     },
-    async ({ store_name, since_seconds, limit }) => {
+    async ({ project_id, store_name, since_seconds, limit }) => {
       const allEvents = store.getStateEvents({
+        projectId: project_id,
         storeId: store_name,
         sinceSeconds: since_seconds
       });
       const maxLimit = Math.min(limit ?? 200, 1e3);
       const truncated = allEvents.length > maxLimit;
       const events = truncated ? allEvents.slice(0, maxLimit) : allEvents;
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const issues = [];
       const storeUpdates = /* @__PURE__ */ new Map();
       for (const e of events) {
@@ -497,7 +524,8 @@ function registerStateTools(server, store) {
           eventCount: events.length,
           totalCount: allEvents.length,
           truncated,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -508,22 +536,23 @@ function registerStateTools(server, store) {
 }
 
 // src/tools/renders.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 function registerRenderTools(server, store) {
   server.tool(
     "get_render_profile",
     "Get React component render profiles showing render counts, velocity, average duration, and render causes. Flags suspicious components that are re-rendering excessively. Requires captureRenders: true in the SDK config and React dev mode for accurate timing data.",
     {
-      component_name: z6.string().optional().describe("Filter by component name (substring match)"),
-      since_seconds: z6.number().optional().describe("Only return events from the last N seconds")
+      project_id: projectIdParam,
+      component_name: z7.string().optional().describe("Filter by component name (substring match)"),
+      since_seconds: z7.number().optional().describe("Only return events from the last N seconds")
     },
-    async ({ component_name, since_seconds }) => {
+    async ({ project_id, component_name, since_seconds }) => {
       const events = store.getRenderEvents({
+        projectId: project_id,
         componentName: component_name,
         sinceSeconds: since_seconds
       });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const issues = [];
       const merged = /* @__PURE__ */ new Map();
       const allSuspicious = /* @__PURE__ */ new Set();
@@ -572,7 +601,8 @@ function registerRenderTools(server, store) {
             to: events.length > 0 ? events[events.length - 1].timestamp : 0
           },
           eventCount: events.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -583,7 +613,7 @@ function registerRenderTools(server, store) {
 }
 
 // src/tools/performance.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var WEB_VITAL_METRICS = ["LCP", "FCP", "CLS", "TTFB", "FID", "INP"];
 var SERVER_METRICS = [
   "memory.rss",
@@ -609,12 +639,14 @@ function registerPerformanceTools(server, store) {
     "get_performance_metrics",
     "Get performance metrics from browser (Web Vitals: LCP, FCP, CLS, TTFB, FID, INP) and/or server (memory, event loop lag, GC pauses, CPU usage). Browser metrics include quality ratings. Server metrics require capturePerformance: true in the server-SDK config.",
     {
-      metric_name: z7.enum(ALL_METRICS).optional().describe("Filter by specific metric name"),
-      source: z7.enum(["browser", "server", "all"]).optional().default("all").describe("Filter by metric source: browser (Web Vitals), server (Node.js runtime), or all"),
-      since_seconds: z7.number().optional().describe("Only return metrics from the last N seconds")
+      project_id: projectIdParam,
+      metric_name: z8.enum(ALL_METRICS).optional().describe("Filter by specific metric name"),
+      source: z8.enum(["browser", "server", "all"]).optional().default("all").describe("Filter by metric source: browser (Web Vitals), server (Node.js runtime), or all"),
+      since_seconds: z8.number().optional().describe("Only return metrics from the last N seconds")
     },
-    async ({ metric_name, source, since_seconds }) => {
+    async ({ project_id, metric_name, source, since_seconds }) => {
       let events = store.getPerformanceMetrics({
+        projectId: project_id,
         metricName: metric_name,
         sinceSeconds: since_seconds
       });
@@ -623,8 +655,7 @@ function registerPerformanceTools(server, store) {
       } else if (source === "server") {
         events = events.filter((e) => !isWebVital(e.metricName));
       }
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const issues = [];
       const poor = events.filter((e) => e.rating === "poor");
       const needsImprovement = events.filter((e) => e.rating === "needs-improvement");
@@ -676,7 +707,8 @@ function registerPerformanceTools(server, store) {
             to: events.length > 0 ? events[events.length - 1].timestamp : 0
           },
           eventCount: events.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -687,7 +719,7 @@ function registerPerformanceTools(server, store) {
 }
 
 // src/tools/dom-snapshot.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 function generateRequestId() {
   return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
 }
@@ -696,10 +728,11 @@ function registerDomSnapshotTools(server, store, collector) {
     "get_dom_snapshot",
     "Capture a live DOM snapshot from the running web app. Sends a command to the SDK which serializes document.documentElement.outerHTML and returns it along with the current URL, viewport dimensions, scroll position, and element count. Useful for understanding what the user sees.",
     {
-      max_size: z8.number().optional().describe("Maximum HTML size in bytes (default: 500000). Larger pages will be truncated.")
+      project_id: projectIdParam,
+      max_size: z9.number().optional().describe("Maximum HTML size in bytes (default: 500000). Larger pages will be truncated.")
     },
-    async ({ max_size }) => {
-      const sessions = store.getSessionInfo();
+    async ({ project_id, max_size }) => {
+      const { sessions, sessionId: resolvedSessionId } = resolveSessionContext(store, project_id);
       const sessionId = collector.getFirstSessionId();
       const activeSession = sessions[0] ?? null;
       if (!sessionId || !activeSession?.isConnected) {
@@ -736,7 +769,8 @@ function registerDomSnapshotTools(server, store, collector) {
           metadata: {
             timeRange: { from: Date.now(), to: Date.now() },
             eventCount: 1,
-            sessionId
+            sessionId,
+            projectId: project_id ?? null
           }
         };
         return {
@@ -751,7 +785,7 @@ function registerDomSnapshotTools(server, store, collector) {
               summary: `Failed to capture DOM snapshot: ${errorMsg}`,
               data: null,
               issues: [errorMsg],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -761,24 +795,25 @@ function registerDomSnapshotTools(server, store, collector) {
 }
 
 // src/tools/har.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function registerHarTools(server, store) {
   server.tool(
     "capture_har",
     "Export captured network requests as a HAR (HTTP Archive) 1.2 JSON file. This is the standard format used by browser DevTools, Charles Proxy, and other tools. Includes request/response headers, body content (if captureBody was enabled in the SDK), and timing data.",
     {
-      since_seconds: z9.number().optional().describe("Only include requests from the last N seconds"),
-      limit: z9.number().optional().describe("Max entries to include (default 200, max 1000)")
+      project_id: projectIdParam,
+      since_seconds: z10.number().optional().describe("Only include requests from the last N seconds"),
+      limit: z10.number().optional().describe("Max entries to include (default 200, max 1000)")
     },
-    async ({ since_seconds, limit }) => {
+    async ({ project_id, since_seconds, limit }) => {
       const allEvents = store.getNetworkRequests({
+        projectId: project_id,
         sinceSeconds: since_seconds
       });
       const maxLimit = Math.min(limit ?? 200, 1e3);
       const truncated = allEvents.length > maxLimit;
       const events = truncated ? allEvents.slice(0, maxLimit) : allEvents;
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const har = buildHar(events);
       const response = {
         summary: `HAR export: ${events.length} request(s)${truncated ? ` (showing ${maxLimit} of ${allEvents.length})` : ""}${since_seconds ? ` from the last ${since_seconds}s` : ""}. Import into Chrome DevTools or any HAR viewer.`,
@@ -792,7 +827,8 @@ function registerHarTools(server, store) {
           eventCount: events.length,
           totalCount: allEvents.length,
           truncated,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -900,25 +936,26 @@ function statusText(status) {
 }
 
 // src/tools/errors.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 function registerErrorTools(server, store) {
   server.tool(
     "get_errors_with_source_context",
     "Get console errors with parsed stack traces and surrounding source code lines. Fetches the actual source files from the dev server (e.g. http://localhost:3000/src/...) and shows the lines around the error. This gives you the same context as clicking a stack frame in DevTools.",
     {
-      since_seconds: z10.number().optional().describe("Only return errors from the last N seconds"),
-      fetch_source: z10.boolean().optional().describe("Whether to fetch source files for context (default: true). Set false for faster results."),
-      context_lines: z10.number().optional().describe("Number of source lines to show above and below the error line (default: 5)")
+      project_id: projectIdParam,
+      since_seconds: z11.number().optional().describe("Only return errors from the last N seconds"),
+      fetch_source: z11.boolean().optional().describe("Whether to fetch source files for context (default: true). Set false for faster results."),
+      context_lines: z11.number().optional().describe("Number of source lines to show above and below the error line (default: 5)")
     },
-    async ({ since_seconds, fetch_source, context_lines }) => {
+    async ({ project_id, since_seconds, fetch_source, context_lines }) => {
       const shouldFetch = fetch_source !== false;
       const contextSize = context_lines ?? 5;
       const events = store.getConsoleMessages({
+        projectId: project_id,
         level: "error",
         sinceSeconds: since_seconds
       });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const limited = events.slice(0, 50);
       const sourceCache = /* @__PURE__ */ new Map();
       const errors = [];
@@ -958,7 +995,8 @@ function registerErrorTools(server, store) {
             to: limited.length > 0 ? limited[limited.length - 1].timestamp : 0
           },
           eventCount: limited.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -1021,20 +1059,20 @@ function extractContext(source, targetLine, contextSize) {
 }
 
 // src/tools/api-discovery.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 function registerApiDiscoveryTools(server, store, engine) {
   server.tool(
     "get_api_catalog",
     "Discover all API endpoints the app is communicating with, auto-grouped by service. Shows normalized paths, call counts, auth patterns, and inferred response shapes.",
     {
-      service: z11.string().optional().describe('Filter by service name (e.g. "Supabase", "Your API")'),
-      min_calls: z11.number().optional().describe("Only show endpoints with at least N calls")
+      project_id: projectIdParam,
+      service: z12.string().optional().describe('Filter by service name (e.g. "Supabase", "Your API")'),
+      min_calls: z12.number().optional().describe("Only show endpoints with at least N calls")
     },
-    async ({ service, min_calls }) => {
+    async ({ project_id, service, min_calls }) => {
       const catalog = engine.getCatalog({ service, minCalls: min_calls });
       const services = engine.getServiceMap();
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const response = {
         summary: `Discovered ${catalog.length} API endpoint(s) across ${services.length} service(s).`,
         data: {
@@ -1064,7 +1102,8 @@ function registerApiDiscoveryTools(server, store, engine) {
         metadata: {
           timeRange: catalog.length > 0 ? { from: Math.min(...catalog.map((e) => e.firstSeen)), to: Math.max(...catalog.map((e) => e.lastSeen)) } : { from: 0, to: 0 },
           eventCount: catalog.reduce((s, e) => s + e.callCount, 0),
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -1076,13 +1115,13 @@ function registerApiDiscoveryTools(server, store, engine) {
     "get_api_health",
     "Get health metrics for discovered API endpoints: success rate, latency percentiles (p50/p95), error rates and error codes.",
     {
-      endpoint: z11.string().optional().describe("Filter by endpoint path substring"),
-      since_seconds: z11.number().optional().describe("Only consider requests from the last N seconds")
+      project_id: projectIdParam,
+      endpoint: z12.string().optional().describe("Filter by endpoint path substring"),
+      since_seconds: z12.number().optional().describe("Only consider requests from the last N seconds")
     },
-    async ({ endpoint, since_seconds }) => {
+    async ({ project_id, endpoint, since_seconds }) => {
       const health = engine.getHealth({ endpoint, sinceSeconds: since_seconds });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const issues = [];
       for (const ep of health) {
         if (ep.errorRate > 0.5) issues.push(`${ep.method} ${ep.normalizedPath}: ${(ep.errorRate * 100).toFixed(0)}% error rate`);
@@ -1106,7 +1145,8 @@ function registerApiDiscoveryTools(server, store, engine) {
         metadata: {
           timeRange: { from: 0, to: Date.now() },
           eventCount: health.reduce((s, e) => s + e.callCount, 0),
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -1118,9 +1158,10 @@ function registerApiDiscoveryTools(server, store, engine) {
     "get_api_documentation",
     "Generate API documentation from observed network traffic. Shows endpoints, auth, latency, and inferred response shapes in markdown format.",
     {
-      service: z11.string().optional().describe("Generate docs for a specific service only")
+      project_id: projectIdParam,
+      service: z12.string().optional().describe("Generate docs for a specific service only")
     },
-    async ({ service }) => {
+    async ({ project_id, service }) => {
       const docs = engine.getDocumentation({ service });
       return {
         content: [{ type: "text", text: docs }]
@@ -1130,11 +1171,12 @@ function registerApiDiscoveryTools(server, store, engine) {
   server.tool(
     "get_service_map",
     "Get a topology map of all external services the app communicates with, including detected platforms (Supabase, Vercel, Stripe, etc.), call counts, and latency.",
-    {},
-    async () => {
+    {
+      project_id: projectIdParam
+    },
+    async ({ project_id }) => {
       const services = engine.getServiceMap();
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const response = {
         summary: `${services.length} service(s) detected from network traffic.`,
         data: services.map((s) => ({
@@ -1151,7 +1193,8 @@ function registerApiDiscoveryTools(server, store, engine) {
         metadata: {
           timeRange: { from: 0, to: Date.now() },
           eventCount: services.reduce((s, e) => s + e.totalCalls, 0),
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -1163,13 +1206,13 @@ function registerApiDiscoveryTools(server, store, engine) {
     "get_api_changes",
     "Compare API endpoints between two sessions. Detects added/removed endpoints and response shape changes.",
     {
-      session_a: z11.string().describe("First session ID"),
-      session_b: z11.string().describe("Second session ID")
+      project_id: projectIdParam,
+      session_a: z12.string().describe("First session ID"),
+      session_b: z12.string().describe("Second session ID")
     },
-    async ({ session_a, session_b }) => {
+    async ({ project_id, session_a, session_b }) => {
       const changes = engine.getApiChanges(session_a, session_b);
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const added = changes.filter((c) => c.changeType === "added").length;
       const removed = changes.filter((c) => c.changeType === "removed").length;
       const modified = changes.filter((c) => c.changeType === "modified").length;
@@ -1180,7 +1223,8 @@ function registerApiDiscoveryTools(server, store, engine) {
         metadata: {
           timeRange: { from: 0, to: Date.now() },
           eventCount: changes.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -1191,7 +1235,7 @@ function registerApiDiscoveryTools(server, store, engine) {
 }
 
 // src/tools/database.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 import {
   aggregateQueryStats,
   detectN1Queries,
@@ -1203,20 +1247,21 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
     "get_query_log",
     "Get captured database queries with SQL, timing, rows returned, and source ORM. Requires server-side SDK instrumentation.",
     {
-      since_seconds: z12.number().optional().describe("Only return queries from the last N seconds"),
-      table: z12.string().optional().describe("Filter by table name"),
-      min_duration_ms: z12.number().optional().describe("Only return queries slower than N ms"),
-      search: z12.string().optional().describe("Search query text")
+      project_id: projectIdParam,
+      since_seconds: z13.number().optional().describe("Only return queries from the last N seconds"),
+      table: z13.string().optional().describe("Filter by table name"),
+      min_duration_ms: z13.number().optional().describe("Only return queries slower than N ms"),
+      search: z13.string().optional().describe("Search query text")
     },
-    async ({ since_seconds, table, min_duration_ms, search }) => {
+    async ({ project_id, since_seconds, table, min_duration_ms, search }) => {
       const events = store.getDatabaseEvents({
+        projectId: project_id,
         sinceSeconds: since_seconds,
         table,
         minDurationMs: min_duration_ms,
         search
       });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const totalDuration = events.reduce((s, e) => s + e.duration, 0);
       const avgDuration = events.length > 0 ? totalDuration / events.length : 0;
       const errorCount = events.filter((e) => e.error).length;
@@ -1243,7 +1288,8 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
         metadata: {
           timeRange: events.length > 0 ? { from: events[0].timestamp, to: events[events.length - 1].timestamp } : { from: 0, to: 0 },
           eventCount: events.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -1255,15 +1301,15 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
     "get_query_performance",
     "Get aggregated database query performance stats: avg/max/p95 duration, call counts, N+1 detection, and slow query analysis.",
     {
-      since_seconds: z12.number().optional().describe("Analyze queries from the last N seconds")
+      project_id: projectIdParam,
+      since_seconds: z13.number().optional().describe("Analyze queries from the last N seconds")
     },
-    async ({ since_seconds }) => {
-      const events = store.getDatabaseEvents({ sinceSeconds: since_seconds });
+    async ({ project_id, since_seconds }) => {
+      const events = store.getDatabaseEvents({ projectId: project_id, sinceSeconds: since_seconds });
       const stats = aggregateQueryStats(events);
       const n1Issues = detectN1Queries(events);
       const slowIssues = detectSlowQueries(events);
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const issues = [
         ...n1Issues.map((i) => i.title),
         ...slowIssues.map((i) => i.title)
@@ -1288,7 +1334,8 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
         metadata: {
           timeRange: { from: 0, to: Date.now() },
           eventCount: events.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -1300,8 +1347,8 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
     "get_schema_map",
     "Get the full database schema: tables, columns, types, foreign keys, and indexes. Requires a configured database connection.",
     {
-      connection_id: z12.string().optional().describe("Connection ID (defaults to first available)"),
-      table: z12.string().optional().describe("Introspect a specific table only")
+      connection_id: z13.string().optional().describe("Connection ID (defaults to first available)"),
+      table: z13.string().optional().describe("Introspect a specific table only")
     },
     async ({ connection_id, table }) => {
       const connections = connectionManager.listConnections();
@@ -1371,12 +1418,12 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
     "get_table_data",
     "Read rows from a database table with pagination. Requires a configured database connection.",
     {
-      table: z12.string().describe("Table name to read"),
-      connection_id: z12.string().optional().describe("Connection ID"),
-      limit: z12.number().optional().describe("Max rows (default 50, max 1000)"),
-      offset: z12.number().optional().describe("Pagination offset"),
-      where: z12.string().optional().describe("SQL WHERE clause (without WHERE keyword)"),
-      order_by: z12.string().optional().describe("SQL ORDER BY clause (without ORDER BY keyword)")
+      table: z13.string().describe("Table name to read"),
+      connection_id: z13.string().optional().describe("Connection ID"),
+      limit: z13.number().optional().describe("Max rows (default 50, max 1000)"),
+      offset: z13.number().optional().describe("Pagination offset"),
+      where: z13.string().optional().describe("SQL WHERE clause (without WHERE keyword)"),
+      order_by: z13.string().optional().describe("SQL ORDER BY clause (without ORDER BY keyword)")
     },
     async ({ table, connection_id, limit, offset, where, order_by }) => {
       const connections = connectionManager.listConnections();
@@ -1429,11 +1476,11 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
     "modify_table_data",
     "Insert, update, or delete rows in a LOCAL DEV database. Safety guarded: localhost only, WHERE required for update/delete, max 100 affected rows, wrapped in transaction.",
     {
-      table: z12.string().describe("Table name"),
-      operation: z12.enum(["insert", "update", "delete"]).describe("Operation type"),
-      connection_id: z12.string().optional().describe("Connection ID"),
-      data: z12.record(z12.unknown()).optional().describe("Row data (for insert/update)"),
-      where: z12.string().optional().describe("WHERE clause (required for update/delete)")
+      table: z13.string().describe("Table name"),
+      operation: z13.enum(["insert", "update", "delete"]).describe("Operation type"),
+      connection_id: z13.string().optional().describe("Connection ID"),
+      data: z13.record(z13.unknown()).optional().describe("Row data (for insert/update)"),
+      where: z13.string().optional().describe("WHERE clause (required for update/delete)")
     },
     async ({ table, operation, connection_id, data, where }) => {
       const connections = connectionManager.listConnections();
@@ -1512,13 +1559,13 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
     "suggest_indexes",
     "Analyze captured database queries and suggest missing indexes based on WHERE/ORDER BY columns and query performance.",
     {
-      since_seconds: z12.number().optional().describe("Analyze queries from the last N seconds")
+      project_id: projectIdParam,
+      since_seconds: z13.number().optional().describe("Analyze queries from the last N seconds")
     },
-    async ({ since_seconds }) => {
-      const events = store.getDatabaseEvents({ sinceSeconds: since_seconds });
+    async ({ project_id, since_seconds }) => {
+      const events = store.getDatabaseEvents({ projectId: project_id, sinceSeconds: since_seconds });
       const suggestions = suggestIndexes(events);
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const response = {
         summary: `${suggestions.length} index suggestion(s) based on ${events.length} captured queries.`,
         data: suggestions.map((s) => ({
@@ -1533,7 +1580,8 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
         metadata: {
           timeRange: { from: 0, to: Date.now() },
           eventCount: events.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -1544,7 +1592,7 @@ function registerDatabaseTools(server, store, connectionManager, schemaIntrospec
 }
 
 // src/tools/process-monitor.ts
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 import { execSync, spawn } from "child_process";
 import { existsSync, statSync, rmSync } from "fs";
 import { join } from "path";
@@ -1553,8 +1601,8 @@ function registerProcessMonitorTools(server, processMonitor) {
     "get_dev_processes",
     "List all running dev processes (Next.js, Vite, Prisma, Docker, databases, etc.) with PID, port, memory, and CPU usage.",
     {
-      type: z13.string().optional().describe("Filter by process type (next, vite, docker, postgres, etc.)"),
-      project: z13.string().optional().describe("Filter by project name")
+      type: z14.string().optional().describe("Filter by process type (next, vite, docker, postgres, etc.)"),
+      project: z14.string().optional().describe("Filter by project name")
     },
     async ({ type, project }) => {
       processMonitor.scan();
@@ -1592,8 +1640,8 @@ function registerProcessMonitorTools(server, processMonitor) {
     "kill_process",
     "Terminate a dev process by PID. Default signal is SIGTERM; use SIGKILL for force kill.",
     {
-      pid: z13.number().describe("Process ID to kill"),
-      signal: z13.enum(["SIGTERM", "SIGKILL"]).optional().describe("Signal to send (default: SIGTERM)")
+      pid: z14.number().describe("Process ID to kill"),
+      signal: z14.enum(["SIGTERM", "SIGKILL"]).optional().describe("Signal to send (default: SIGTERM)")
     },
     async ({ pid, signal }) => {
       if (pid < 2 || pid === process.pid) {
@@ -1626,7 +1674,7 @@ function registerProcessMonitorTools(server, processMonitor) {
     "get_port_usage",
     "Show which dev processes are bound to which ports. Useful for debugging port conflicts.",
     {
-      port: z13.number().optional().describe("Filter by specific port number")
+      port: z14.number().optional().describe("Filter by specific port number")
     },
     async ({ port }) => {
       processMonitor.scan();
@@ -1656,8 +1704,8 @@ function registerProcessMonitorTools(server, processMonitor) {
     "purge_caches",
     "Delete common build/dev cache directories (.next/cache, node_modules/.cache, .vite, .turbo, .swc, .parcel-cache, etc.) for a project directory. Reports size freed per cache.",
     {
-      directory: z13.string().describe("Absolute path to the project directory"),
-      dryRun: z13.boolean().optional().describe("If true, report what would be deleted without actually deleting (default: false)")
+      directory: z14.string().describe("Absolute path to the project directory"),
+      dryRun: z14.boolean().optional().describe("If true, report what would be deleted without actually deleting (default: false)")
     },
     async ({ directory, dryRun }) => {
       const CACHE_TARGETS = [
@@ -1714,10 +1762,10 @@ function registerProcessMonitorTools(server, processMonitor) {
     "restart_dev_server",
     "Kill a dev server process, purge build caches in its working directory, and restart it with the same or a custom command. Combines kill_process + purge_caches + spawn into one operation.",
     {
-      pid: z13.number().describe("PID of the dev server process to restart"),
-      command: z13.string().optional().describe('Custom start command (e.g. "npm run dev"). If omitted, infers from process type.'),
-      skipCachePurge: z13.boolean().optional().describe("If true, skip cache purging (default: false)"),
-      signal: z13.enum(["SIGTERM", "SIGKILL"]).optional().describe("Kill signal (default: SIGTERM)")
+      pid: z14.number().describe("PID of the dev server process to restart"),
+      command: z14.string().optional().describe('Custom start command (e.g. "npm run dev"). If omitted, infers from process type.'),
+      skipCachePurge: z14.boolean().optional().describe("If true, skip cache purging (default: false)"),
+      signal: z14.enum(["SIGTERM", "SIGKILL"]).optional().describe("Kill signal (default: SIGTERM)")
     },
     async ({ pid, command, skipCachePurge, signal }) => {
       if (pid < 2 || pid === process.pid) {
@@ -1867,15 +1915,15 @@ function inferStartCommand(type, rawCommand) {
 }
 
 // src/tools/infra-connector.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 function registerInfraTools(server, infraConnector) {
   server.tool(
     "get_deploy_logs",
     "Get deployment history from connected platforms (Vercel, Cloudflare, Railway). Shows build status, branch, commit, and timing.",
     {
-      project: z14.string().optional().describe("Project name"),
-      platform: z14.string().optional().describe("Filter by platform (vercel, cloudflare, railway)"),
-      deploy_id: z14.string().optional().describe("Get details for a specific deployment")
+      project: z15.string().optional().describe("Project name"),
+      platform: z15.string().optional().describe("Filter by platform (vercel, cloudflare, railway)"),
+      deploy_id: z15.string().optional().describe("Get details for a specific deployment")
     },
     async ({ project, platform, deploy_id }) => {
       const logs = await infraConnector.getDeployLogs(project ?? "default", platform, deploy_id);
@@ -1908,10 +1956,10 @@ function registerInfraTools(server, infraConnector) {
     "get_runtime_logs",
     "Get runtime error/info logs from connected deployment platforms.",
     {
-      project: z14.string().optional().describe("Project name"),
-      platform: z14.string().optional().describe("Filter by platform"),
-      level: z14.string().optional().describe("Filter by log level (info, warn, error)"),
-      since_seconds: z14.number().optional().describe("Only return logs from the last N seconds")
+      project: z15.string().optional().describe("Project name"),
+      platform: z15.string().optional().describe("Filter by platform"),
+      level: z15.string().optional().describe("Filter by log level (info, warn, error)"),
+      since_seconds: z15.number().optional().describe("Only return logs from the last N seconds")
     },
     async ({ project, platform, level, since_seconds }) => {
       const since = since_seconds ? Date.now() - since_seconds * 1e3 : void 0;
@@ -1941,7 +1989,7 @@ function registerInfraTools(server, infraConnector) {
     "get_build_status",
     "Get the current deployment status for each connected platform.",
     {
-      project: z14.string().optional().describe("Project name")
+      project: z15.string().optional().describe("Project name")
     },
     async ({ project }) => {
       const statuses = await infraConnector.getBuildStatus(project ?? "default");
@@ -1971,7 +2019,7 @@ function registerInfraTools(server, infraConnector) {
     "get_infra_overview",
     "Overview of which platforms a project uses, combining explicit configuration with auto-detection from network traffic.",
     {
-      project: z14.string().optional().describe("Project name")
+      project: z15.string().optional().describe("Project name")
     },
     async ({ project }) => {
       const overview = infraConnector.getInfraOverview(project);
@@ -1993,18 +2041,19 @@ function registerInfraTools(server, infraConnector) {
 }
 
 // src/tools/session-diff.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 import { compareSessions } from "@runtimescope/collector";
-function registerSessionDiffTools(server, sessionManager, collector) {
+function registerSessionDiffTools(server, sessionManager, collector, projectManager) {
   server.tool(
     "create_session_snapshot",
     "Capture a point-in-time snapshot of a live or recent session. Use before/after code changes to compare how your app behaves at different moments. Each session can have multiple snapshots.",
     {
-      session_id: z15.string().optional().describe("Session ID (defaults to first active session)"),
-      label: z15.string().optional().describe('Label for this snapshot (e.g., "before-fix", "baseline", "after-deploy")'),
-      project: z15.string().optional().describe("Project name")
+      session_id: z16.string().optional().describe("Session ID (defaults to first active session)"),
+      label: z16.string().optional().describe('Label for this snapshot (e.g., "before-fix", "baseline", "after-deploy")'),
+      project: z16.string().optional().describe("Project name"),
+      project_id: projectIdParam
     },
-    async ({ session_id, label, project }) => {
+    async ({ session_id, label, project, project_id }) => {
       const sessionId = session_id ?? collector.getFirstSessionId();
       if (!sessionId) {
         return {
@@ -2016,7 +2065,7 @@ function registerSessionDiffTools(server, sessionManager, collector) {
           }, null, 2) }]
         };
       }
-      const projectName = project ?? collector.getProjectForSession(sessionId) ?? "default";
+      const projectName = project ?? (project_id && projectManager ? projectManager.getAppForProjectId(project_id) : void 0) ?? collector.getProjectForSession(sessionId) ?? "default";
       const snapshot = sessionManager.createSnapshot(sessionId, projectName, label);
       const response = {
         summary: `Snapshot captured for session ${sessionId.slice(0, 8)}${label ? ` (label: "${label}")` : ""}. ${snapshot.metrics.totalEvents} events, ${snapshot.metrics.errorCount} errors.`,
@@ -2051,11 +2100,12 @@ function registerSessionDiffTools(server, sessionManager, collector) {
     "get_session_snapshots",
     "List all snapshots for a session. Use with compare_sessions to track how your app changed over time within a single session.",
     {
-      session_id: z15.string().describe("Session ID"),
-      project: z15.string().optional().describe("Project name")
+      session_id: z16.string().describe("Session ID"),
+      project: z16.string().optional().describe("Project name"),
+      project_id: projectIdParam
     },
-    async ({ session_id, project }) => {
-      const projectName = project ?? collector.getProjectForSession(session_id) ?? "default";
+    async ({ session_id, project, project_id }) => {
+      const projectName = project ?? (project_id && projectManager ? projectManager.getAppForProjectId(project_id) : void 0) ?? collector.getProjectForSession(session_id) ?? "default";
       const snapshots = sessionManager.getSessionSnapshots(projectName, session_id);
       const response = {
         summary: `${snapshots.length} snapshot(s) for session ${session_id.slice(0, 8)}.`,
@@ -2085,14 +2135,15 @@ function registerSessionDiffTools(server, sessionManager, collector) {
     "compare_sessions",
     "Compare two sessions or two snapshots: render counts, API latency, errors, Web Vitals, and query performance. Shows regressions and improvements. Use snapshot_a/snapshot_b to compare specific snapshots within or across sessions.",
     {
-      session_a: z15.string().optional().describe("First session ID (baseline) \u2014 used when comparing sessions"),
-      session_b: z15.string().optional().describe("Second session ID (comparison) \u2014 used when comparing sessions"),
-      snapshot_a: z15.number().optional().describe("First snapshot ID (baseline) \u2014 used when comparing snapshots"),
-      snapshot_b: z15.number().optional().describe("Second snapshot ID (comparison) \u2014 used when comparing snapshots"),
-      project: z15.string().optional().describe("Project name")
+      session_a: z16.string().optional().describe("First session ID (baseline) \u2014 used when comparing sessions"),
+      session_b: z16.string().optional().describe("Second session ID (comparison) \u2014 used when comparing sessions"),
+      snapshot_a: z16.number().optional().describe("First snapshot ID (baseline) \u2014 used when comparing snapshots"),
+      snapshot_b: z16.number().optional().describe("Second snapshot ID (comparison) \u2014 used when comparing snapshots"),
+      project: z16.string().optional().describe("Project name"),
+      project_id: projectIdParam
     },
-    async ({ session_a, session_b, snapshot_a, snapshot_b, project }) => {
-      const projectName = project ?? "default";
+    async ({ session_a, session_b, snapshot_a, snapshot_b, project, project_id }) => {
+      const projectName = project ?? (project_id && projectManager ? projectManager.getAppForProjectId(project_id) : void 0) ?? "default";
       let metricsA = null;
       let metricsB = null;
       let labelA = "";
@@ -2202,8 +2253,8 @@ function registerSessionDiffTools(server, sessionManager, collector) {
     "get_session_history",
     "List past sessions with build metadata, event counts, and timestamps. Requires SQLite persistence.",
     {
-      project: z15.string().optional().describe("Project name"),
-      limit: z15.number().optional().describe("Max sessions to return (default 20)")
+      project: z16.string().optional().describe("Project name"),
+      limit: z16.number().optional().describe("Max sessions to return (default 20)")
     },
     async ({ project, limit }) => {
       const projectName = project ?? "default";
@@ -2235,19 +2286,20 @@ function registerSessionDiffTools(server, sessionManager, collector) {
 }
 
 // src/tools/recon-metadata.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 function registerReconMetadataTools(server, store, collector) {
   server.tool(
     "get_page_metadata",
     "Get page metadata and tech stack detection for the current page. Returns URL, viewport, meta tags, detected framework/UI library/build tool/hosting, external stylesheets and scripts. Requires the RuntimeScope extension to be connected.",
     {
-      url: z16.string().optional().describe("Filter by URL substring"),
-      force_refresh: z16.boolean().optional().default(false).describe("Send a recon_scan command to the extension to capture fresh data")
+      project_id: projectIdParam,
+      url: z17.string().optional().describe("Filter by URL substring"),
+      force_refresh: z17.boolean().optional().default(false).describe("Send a recon_scan command to the extension to capture fresh data")
     },
-    async ({ url, force_refresh }) => {
+    async ({ project_id, url, force_refresh }) => {
       if (force_refresh) {
-        const sessions2 = store.getSessionInfo();
-        const activeSession = sessions2.find((s) => s.isConnected);
+        const sessions = store.getSessionInfo();
+        const activeSession = sessions.find((s) => s.isConnected);
         if (activeSession) {
           try {
             await collector.sendCommand(activeSession.sessionId, {
@@ -2260,8 +2312,7 @@ function registerReconMetadataTools(server, store, collector) {
         }
       }
       const event = store.getReconMetadata({ url });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       if (!event) {
         return {
           content: [{
@@ -2270,7 +2321,7 @@ function registerReconMetadataTools(server, store, collector) {
               summary: "No page metadata captured yet. Ensure the RuntimeScope extension is connected and has scanned a page.",
               data: null,
               issues: ["No recon_metadata events found in the event store"],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -2313,7 +2364,8 @@ function registerReconMetadataTools(server, store, collector) {
         metadata: {
           timeRange: { from: event.timestamp, to: event.timestamp },
           eventCount: 1,
-          sessionId: event.sessionId
+          sessionId: event.sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -2324,20 +2376,21 @@ function registerReconMetadataTools(server, store, collector) {
 }
 
 // src/tools/recon-design-tokens.ts
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 function registerReconDesignTokenTools(server, store, collector) {
   server.tool(
     "get_design_tokens",
     "Extract the design system from the current page: CSS custom properties (--variables), color palette, typography scale, spacing scale, border radii, box shadows, and CSS architecture detection. Essential for matching a site's visual style when recreating UI.",
     {
-      url: z17.string().optional().describe("Filter by URL substring"),
-      category: z17.enum(["all", "colors", "typography", "spacing", "custom_properties", "shadows"]).optional().default("all").describe("Return only a specific token category"),
-      force_refresh: z17.boolean().optional().default(false).describe("Send a recon_scan command to capture fresh data")
+      project_id: projectIdParam,
+      url: z18.string().optional().describe("Filter by URL substring"),
+      category: z18.enum(["all", "colors", "typography", "spacing", "custom_properties", "shadows"]).optional().default("all").describe("Return only a specific token category"),
+      force_refresh: z18.boolean().optional().default(false).describe("Send a recon_scan command to capture fresh data")
     },
-    async ({ url, category, force_refresh }) => {
+    async ({ project_id, url, category, force_refresh }) => {
       if (force_refresh) {
-        const sessions2 = store.getSessionInfo();
-        const activeSession = sessions2.find((s) => s.isConnected);
+        const sessions = store.getSessionInfo();
+        const activeSession = sessions.find((s) => s.isConnected);
         if (activeSession) {
           try {
             await collector.sendCommand(activeSession.sessionId, {
@@ -2350,8 +2403,7 @@ function registerReconDesignTokenTools(server, store, collector) {
         }
       }
       const event = store.getReconDesignTokens({ url });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       if (!event) {
         return {
           content: [{
@@ -2360,7 +2412,7 @@ function registerReconDesignTokenTools(server, store, collector) {
               summary: "No design tokens captured yet. Ensure the RuntimeScope extension is connected and has scanned a page.",
               data: null,
               issues: ["No recon_design_tokens events found in the event store"],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -2411,7 +2463,8 @@ function registerReconDesignTokenTools(server, store, collector) {
         metadata: {
           timeRange: { from: event.timestamp, to: event.timestamp },
           eventCount: 1,
-          sessionId: event.sessionId
+          sessionId: event.sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -2422,18 +2475,18 @@ function registerReconDesignTokenTools(server, store, collector) {
 }
 
 // src/tools/recon-fonts.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 function registerReconFontTools(server, store) {
   server.tool(
     "get_font_info",
     "Get typography details for the current page: @font-face declarations, font families actually used in computed styles, icon fonts with glyph usage, and font loading strategy. Critical for matching typography when recreating UI.",
     {
-      url: z18.string().optional().describe("Filter by URL substring")
+      project_id: projectIdParam,
+      url: z19.string().optional().describe("Filter by URL substring")
     },
-    async ({ url }) => {
+    async ({ project_id, url }) => {
       const event = store.getReconFonts({ url });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       if (!event) {
         return {
           content: [{
@@ -2442,7 +2495,7 @@ function registerReconFontTools(server, store) {
               summary: "No font data captured yet. Ensure the RuntimeScope extension is connected and has scanned a page.",
               data: null,
               issues: ["No recon_fonts events found in the event store"],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -2469,7 +2522,8 @@ function registerReconFontTools(server, store) {
         metadata: {
           timeRange: { from: event.timestamp, to: event.timestamp },
           eventCount: 1,
-          sessionId: event.sessionId
+          sessionId: event.sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -2480,21 +2534,22 @@ function registerReconFontTools(server, store) {
 }
 
 // src/tools/recon-layout.ts
-import { z as z19 } from "zod";
+import { z as z20 } from "zod";
 function registerReconLayoutTools(server, store, collector) {
   server.tool(
     "get_layout_tree",
     "Get the DOM structure with layout information: element tags, classes, bounding rects, display mode (flex/grid/block), flex/grid properties (direction, justify, align, gap, template columns/rows), position, and z-index. Optionally scoped to a CSS selector. Essential for understanding page structure when recreating UI.",
     {
-      selector: z19.string().optional().describe('CSS selector to scope the tree (e.g., "nav", ".hero", "main"). Omit for full page.'),
-      max_depth: z19.number().optional().default(10).describe("Maximum depth of the tree to return (default 10)"),
-      url: z19.string().optional().describe("Filter by URL substring"),
-      force_refresh: z19.boolean().optional().default(false).describe("Request fresh capture from extension")
+      project_id: projectIdParam,
+      selector: z20.string().optional().describe('CSS selector to scope the tree (e.g., "nav", ".hero", "main"). Omit for full page.'),
+      max_depth: z20.number().optional().default(10).describe("Maximum depth of the tree to return (default 10)"),
+      url: z20.string().optional().describe("Filter by URL substring"),
+      force_refresh: z20.boolean().optional().default(false).describe("Request fresh capture from extension")
     },
-    async ({ selector, max_depth, url, force_refresh }) => {
+    async ({ project_id, selector, max_depth, url, force_refresh }) => {
       if (force_refresh) {
-        const sessions2 = store.getSessionInfo();
-        const activeSession = sessions2.find((s) => s.isConnected);
+        const sessions = store.getSessionInfo();
+        const activeSession = sessions.find((s) => s.isConnected);
         if (activeSession) {
           try {
             await collector.sendCommand(activeSession.sessionId, {
@@ -2507,8 +2562,7 @@ function registerReconLayoutTools(server, store, collector) {
         }
       }
       const event = store.getReconLayoutTree({ url });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       if (!event) {
         return {
           content: [{
@@ -2517,7 +2571,7 @@ function registerReconLayoutTools(server, store, collector) {
               summary: "No layout tree captured yet. Ensure the RuntimeScope extension is connected and has scanned a page.",
               data: null,
               issues: ["No recon_layout_tree events found in the event store"],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -2549,7 +2603,8 @@ function registerReconLayoutTools(server, store, collector) {
         metadata: {
           timeRange: { from: event.timestamp, to: event.timestamp },
           eventCount: 1,
-          sessionId: event.sessionId
+          sessionId: event.sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -2602,18 +2657,18 @@ function pruneTree(node, maxDepth, currentDepth = 0) {
 }
 
 // src/tools/recon-accessibility.ts
-import { z as z20 } from "zod";
+import { z as z21 } from "zod";
 function registerReconAccessibilityTools(server, store) {
   server.tool(
     "get_accessibility_tree",
     "Get the accessibility structure of the current page: heading hierarchy (h1-h6), ARIA landmarks (nav, main, aside), form fields with labels, buttons, links, and images with alt text status. Useful for ensuring UI recreations maintain proper semantic HTML and accessibility.",
     {
-      url: z20.string().optional().describe("Filter by URL substring")
+      project_id: projectIdParam,
+      url: z21.string().optional().describe("Filter by URL substring")
     },
-    async ({ url }) => {
+    async ({ project_id, url }) => {
       const event = store.getReconAccessibility({ url });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       if (!event) {
         return {
           content: [{
@@ -2622,7 +2677,7 @@ function registerReconAccessibilityTools(server, store) {
               summary: "No accessibility data captured yet. Ensure the RuntimeScope extension is connected and has scanned a page.",
               data: null,
               issues: ["No recon_accessibility events found in the event store"],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -2664,7 +2719,8 @@ function registerReconAccessibilityTools(server, store) {
         metadata: {
           timeRange: { from: event.timestamp, to: event.timestamp },
           eventCount: 1,
-          sessionId: event.sessionId
+          sessionId: event.sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -2675,7 +2731,7 @@ function registerReconAccessibilityTools(server, store) {
 }
 
 // src/tools/recon-computed-styles.ts
-import { z as z21 } from "zod";
+import { z as z22 } from "zod";
 var PROPERTY_GROUPS = {
   colors: [
     "color",
@@ -2779,16 +2835,17 @@ function registerReconComputedStyleTools(server, store, collector, scanner) {
     "get_computed_styles",
     "Get computed CSS styles for elements matching a selector. Returns the actual resolved values the browser uses to render each element. Can filter by property group (colors, typography, spacing, layout, borders, visual) or specific property names. When multiple elements match, highlights variations between them.",
     {
-      selector: z21.string().describe('CSS selector to query (e.g., ".btn-primary", "nav > ul > li", "[data-testid=hero]")'),
-      properties: z21.enum(["all", "colors", "typography", "spacing", "layout", "borders", "visual"]).optional().default("all").describe('Property group to return, or "all" for everything'),
-      specific_properties: z21.array(z21.string()).optional().describe("Specific CSS property names to return (overrides the properties group)"),
-      force_refresh: z21.boolean().optional().default(false).describe("Request fresh capture from extension or scanner for this selector")
+      project_id: projectIdParam,
+      selector: z22.string().describe('CSS selector to query (e.g., ".btn-primary", "nav > ul > li", "[data-testid=hero]")'),
+      properties: z22.enum(["all", "colors", "typography", "spacing", "layout", "borders", "visual"]).optional().default("all").describe('Property group to return, or "all" for everything'),
+      specific_properties: z22.array(z22.string()).optional().describe("Specific CSS property names to return (overrides the properties group)"),
+      force_refresh: z22.boolean().optional().default(false).describe("Request fresh capture from extension or scanner for this selector")
     },
-    async ({ selector, properties, specific_properties, force_refresh }) => {
+    async ({ project_id, selector, properties, specific_properties, force_refresh }) => {
       const propFilter = specific_properties ?? (properties !== "all" ? PROPERTY_GROUPS[properties] : void 0);
       if (force_refresh) {
-        const sessions2 = store.getSessionInfo();
-        const activeSession = sessions2.find((s) => s.isConnected);
+        const sessions = store.getSessionInfo();
+        const activeSession = sessions.find((s) => s.isConnected);
         if (activeSession) {
           try {
             await collector.sendCommand(activeSession.sessionId, {
@@ -2823,8 +2880,7 @@ function registerReconComputedStyleTools(server, store, collector, scanner) {
         } catch {
         }
       }
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       if (!event || event.entries.length === 0) {
         const hint = scanner.getLastScannedUrl() ? `No elements matched "${selector}" on the scanned page. Check the selector and try again.` : `No computed styles captured for "${selector}". Run scan_website first to scan a page, then query selectors on it.`;
         return {
@@ -2834,7 +2890,7 @@ function registerReconComputedStyleTools(server, store, collector, scanner) {
               summary: hint,
               data: null,
               issues: ["No computed style data available for this selector"],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -2882,7 +2938,8 @@ function registerReconComputedStyleTools(server, store, collector, scanner) {
         metadata: {
           timeRange: { from: event.timestamp, to: event.timestamp },
           eventCount: 1,
-          sessionId: event.sessionId
+          sessionId: event.sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -2893,20 +2950,21 @@ function registerReconComputedStyleTools(server, store, collector, scanner) {
 }
 
 // src/tools/recon-element-snapshot.ts
-import { z as z22 } from "zod";
+import { z as z23 } from "zod";
 function registerReconElementSnapshotTools(server, store, collector, scanner) {
   server.tool(
     "get_element_snapshot",
     'Deep snapshot of a specific element and its children: structure, attributes, text content, bounding rects, and key computed styles for every node. This is the "zoom in" tool \u2014 use it when you need the full picture of a component (a card, a nav bar, a form) for recreation. More detailed than get_layout_tree, more targeted than get_computed_styles.',
     {
-      selector: z22.string().describe('CSS selector for the root element (e.g., ".card", "#hero", "[data-testid=checkout-form]")'),
-      depth: z22.number().optional().default(5).describe("How many levels deep to capture children (default 5)"),
-      force_refresh: z22.boolean().optional().default(false).describe("Request fresh capture from extension or scanner for this element")
+      project_id: projectIdParam,
+      selector: z23.string().describe('CSS selector for the root element (e.g., ".card", "#hero", "[data-testid=checkout-form]")'),
+      depth: z23.number().optional().default(5).describe("How many levels deep to capture children (default 5)"),
+      force_refresh: z23.boolean().optional().default(false).describe("Request fresh capture from extension or scanner for this element")
     },
-    async ({ selector, depth, force_refresh }) => {
+    async ({ project_id, selector, depth, force_refresh }) => {
       if (force_refresh) {
-        const sessions2 = store.getSessionInfo();
-        const activeSession = sessions2.find((s) => s.isConnected);
+        const sessions = store.getSessionInfo();
+        const activeSession = sessions.find((s) => s.isConnected);
         if (activeSession) {
           try {
             await collector.sendCommand(activeSession.sessionId, {
@@ -2942,8 +3000,7 @@ function registerReconElementSnapshotTools(server, store, collector, scanner) {
         } catch {
         }
       }
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       if (!event) {
         const hint = scanner.getLastScannedUrl() ? `No element found matching "${selector}" on the scanned page. Check the selector and try again.` : `No element snapshot captured for "${selector}". Run scan_website first to scan a page, then query selectors on it.`;
         return {
@@ -2953,7 +3010,7 @@ function registerReconElementSnapshotTools(server, store, collector, scanner) {
               summary: hint,
               data: null,
               issues: ["No element snapshot data available for this selector"],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -2975,7 +3032,8 @@ function registerReconElementSnapshotTools(server, store, collector, scanner) {
         metadata: {
           timeRange: { from: event.timestamp, to: event.timestamp },
           eventCount: 1,
-          sessionId: event.sessionId
+          sessionId: event.sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -2986,19 +3044,19 @@ function registerReconElementSnapshotTools(server, store, collector, scanner) {
 }
 
 // src/tools/recon-assets.ts
-import { z as z23 } from "zod";
+import { z as z24 } from "zod";
 function registerReconAssetTools(server, store) {
   server.tool(
     "get_asset_inventory",
     "Sprite-aware asset inventory for the current page. Detects and extracts: standard images, inline SVGs, SVG sprite sheets (<symbol>/<use> references), CSS background sprites (with crop coordinates and extracted frames), CSS mask sprites, and icon fonts (with glyph codepoints). For CSS sprites, calculates the exact crop rectangle from background-position/size and can provide extracted individual frames as data URLs.",
     {
-      category: z23.enum(["all", "images", "svg", "sprites", "icon_fonts"]).optional().default("all").describe("Filter by asset category"),
-      url: z23.string().optional().describe("Filter by page URL substring")
+      project_id: projectIdParam,
+      category: z24.enum(["all", "images", "svg", "sprites", "icon_fonts"]).optional().default("all").describe("Filter by asset category"),
+      url: z24.string().optional().describe("Filter by page URL substring")
     },
-    async ({ category, url }) => {
+    async ({ project_id, category, url }) => {
       const event = store.getReconAssetInventory({ url });
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       if (!event) {
         return {
           content: [{
@@ -3007,7 +3065,7 @@ function registerReconAssetTools(server, store) {
               summary: "No asset inventory captured yet. Ensure the RuntimeScope extension is connected and has scanned a page.",
               data: null,
               issues: ["No recon_asset_inventory events found in the event store"],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -3073,7 +3131,8 @@ function registerReconAssetTools(server, store) {
         metadata: {
           timeRange: { from: event.timestamp, to: event.timestamp },
           eventCount: 1,
-          sessionId: event.sessionId
+          sessionId: event.sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -3084,7 +3143,7 @@ function registerReconAssetTools(server, store) {
 }
 
 // src/tools/recon-style-diff.ts
-import { z as z24 } from "zod";
+import { z as z25 } from "zod";
 var VISUAL_PROPERTIES = [
   "color",
   "background-color",
@@ -3128,15 +3187,15 @@ function registerReconStyleDiffTools(server, store) {
     "get_style_diff",
     "Compare computed styles between two captured element snapshots to check how closely a recreation matches the original. Compares two selectors from stored computed style events and reports property-by-property differences with a match percentage. Use this to verify UI recreation fidelity.",
     {
-      source_selector: z24.string().describe("CSS selector for the source/original element"),
-      target_selector: z24.string().describe("CSS selector for the target/recreation element"),
-      properties: z24.enum(["visual", "all"]).optional().default("visual").describe('"visual" compares only visually-significant properties (colors, typography, spacing, layout). "all" compares everything.'),
-      specific_properties: z24.array(z24.string()).optional().describe("Specific CSS property names to compare (overrides properties group)")
+      project_id: projectIdParam,
+      source_selector: z25.string().describe("CSS selector for the source/original element"),
+      target_selector: z25.string().describe("CSS selector for the target/recreation element"),
+      properties: z25.enum(["visual", "all"]).optional().default("visual").describe('"visual" compares only visually-significant properties (colors, typography, spacing, layout). "all" compares everything.'),
+      specific_properties: z25.array(z25.string()).optional().describe("Specific CSS property names to compare (overrides properties group)")
     },
-    async ({ source_selector, target_selector, properties, specific_properties }) => {
+    async ({ project_id, source_selector, target_selector, properties, specific_properties }) => {
       const events = store.getReconComputedStyles();
-      const sessions = store.getSessionInfo();
-      const sessionId = sessions[0]?.sessionId ?? null;
+      const { sessionId } = resolveSessionContext(store, project_id);
       const sourceEvent = events.find(
         (e) => e.entries.some((entry) => entry.selector === source_selector)
       );
@@ -3154,7 +3213,7 @@ function registerReconStyleDiffTools(server, store) {
               summary: `Missing computed styles for ${missing.join(" and ")}. Capture computed styles for both selectors first using get_computed_styles with force_refresh=true.`,
               data: null,
               issues: [`No captured styles for: ${missing.join(", ")}`],
-              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId }
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId, projectId: project_id ?? null }
             }, null, 2)
           }]
         };
@@ -3223,7 +3282,8 @@ function registerReconStyleDiffTools(server, store) {
             to: Math.max(sourceEvent.timestamp, targetEvent.timestamp)
           },
           eventCount: 2,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -4389,23 +4449,28 @@ var PlaywrightScanner = class _PlaywrightScanner {
 };
 
 // src/tools/scanner.ts
-import { z as z25 } from "zod";
+import { z as z26 } from "zod";
+import { getOrCreateProjectId } from "@runtimescope/collector";
 var COLLECTOR_PORT = process.env.RUNTIMESCOPE_PORT ?? "9090";
 var HTTP_PORT = process.env.RUNTIMESCOPE_HTTP_PORT ?? "9091";
-function registerScannerTools(server, store, scanner) {
+function registerScannerTools(server, store, scanner, projectManager) {
   server.tool(
     "get_sdk_snippet",
     "Generate a ready-to-paste code snippet to connect any web application to RuntimeScope for live runtime monitoring. Works with ANY tech stack \u2014 React, Vue, Angular, Svelte, plain HTML, Flask/Django templates, Rails ERB, PHP, WordPress, etc. Returns the appropriate installation method based on the project type.",
     {
-      app_name: z25.string().optional().default("my-app").describe('Name for the app in RuntimeScope (e.g., "echo-frontend", "dashboard")'),
-      framework: z25.enum(["html", "react", "vue", "angular", "svelte", "nextjs", "nuxt", "flask", "django", "rails", "php", "wordpress", "workers", "other"]).optional().default("html").describe('The framework/tech stack of the project. Use "html" for any plain HTML or server-rendered pages. Use "workers" for Cloudflare Workers.')
+      app_name: z26.string().optional().default("my-app").describe('Name for the app in RuntimeScope (e.g., "echo-frontend", "dashboard")'),
+      framework: z26.enum(["html", "react", "vue", "angular", "svelte", "nextjs", "nuxt", "flask", "django", "rails", "php", "wordpress", "workers", "other"]).optional().default("html").describe('The framework/tech stack of the project. Use "html" for any plain HTML or server-rendered pages. Use "workers" for Cloudflare Workers.'),
+      project_id: z26.string().optional().describe("Existing project ID to use (proj_xxx). If omitted, one is auto-generated and persisted.")
     },
-    async ({ app_name, framework }) => {
+    async ({ app_name, framework, project_id }) => {
+      const resolvedProjectId = project_id ?? (projectManager ? getOrCreateProjectId(projectManager, app_name) : void 0);
+      const projectIdLine = resolvedProjectId ? `
+    projectId: '${resolvedProjectId}',` : "";
       const scriptTagSnippet = `<!-- RuntimeScope \u2014 paste before </body> -->
 <script src="http://localhost:${HTTP_PORT}/runtimescope.js"></script>
 <script>
   RuntimeScope.init({
-    appName: '${app_name}',
+    appName: '${app_name}',${projectIdLine}
     endpoint: 'ws://localhost:${COLLECTOR_PORT}',
   });
 </script>`;
@@ -4413,7 +4478,7 @@ function registerScannerTools(server, store, scanner) {
 import { RuntimeScope } from '@runtimescope/sdk';
 
 RuntimeScope.init({
-  appName: '${app_name}',
+  appName: '${app_name}',${projectIdLine}
   endpoint: 'ws://localhost:${COLLECTOR_PORT}',
 });`;
       const workersSnippet = `// npm install @runtimescope/workers-sdk
@@ -4435,7 +4500,7 @@ export default withRuntimeScope({
     return new Response('Hello!');
   },
 }, {
-  appName: '${app_name}',
+  appName: '${app_name}',${projectIdLine}
   httpEndpoint: 'http://localhost:${HTTP_PORT}/api/events',
   // captureConsole: true,    // Capture console.log/warn/error (default: true)
   // captureHeaders: false,   // Include request/response headers (default: false)
@@ -4497,7 +4562,7 @@ export default withRuntimeScope({
           whatItCaptures: isWorkers ? workersCaptures : browserCaptures
         },
         issues: [],
-        metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null }
+        metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null, projectId: resolvedProjectId ?? null }
       };
       return {
         content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
@@ -4508,10 +4573,10 @@ export default withRuntimeScope({
     "scan_website",
     "Visit a website with a headless browser and extract comprehensive data: tech stack (7,221 technologies), design tokens (colors, typography, spacing, CSS variables), layout tree (DOM with bounding rects, flex/grid), accessibility structure, fonts, and asset inventory (images, SVGs, sprites). After scanning, all recon tools (get_design_tokens, get_layout_tree, get_font_info, etc.) will return data from the scanned page. This is the primary way to analyze any website.",
     {
-      url: z25.string().describe('The full URL to scan (e.g., "https://stripe.com")'),
-      viewport_width: z25.number().optional().default(1280).describe("Viewport width in pixels (default: 1280)"),
-      viewport_height: z25.number().optional().default(720).describe("Viewport height in pixels (default: 720)"),
-      wait_for: z25.enum(["load", "networkidle", "domcontentloaded"]).optional().default("networkidle").describe("Wait condition before scanning (default: networkidle)")
+      url: z26.string().describe('The full URL to scan (e.g., "https://stripe.com")'),
+      viewport_width: z26.number().optional().default(1280).describe("Viewport width in pixels (default: 1280)"),
+      viewport_height: z26.number().optional().default(720).describe("Viewport height in pixels (default: 720)"),
+      wait_for: z26.enum(["load", "networkidle", "domcontentloaded"]).optional().default("networkidle").describe("Wait condition before scanning (default: networkidle)")
     },
     async ({ url, viewport_width, viewport_height, wait_for }) => {
       try {
@@ -4591,19 +4656,21 @@ export default withRuntimeScope({
 }
 
 // src/tools/custom-events.ts
-import { z as z26 } from "zod";
+import { z as z27 } from "zod";
 function registerCustomEventTools(server, store) {
   server.tool(
     "get_custom_events",
     "Get custom business/product events tracked via RuntimeScope.track(). Shows event catalog (all unique event names with counts) and recent occurrences. Use this to see what events are being tracked and their frequency.",
     {
-      name: z26.string().optional().describe("Filter by event name (exact match)"),
-      since_seconds: z26.number().optional().describe("Only events from the last N seconds (default: 300)"),
-      session_id: z26.string().optional().describe("Filter by session ID")
+      project_id: projectIdParam,
+      name: z27.string().optional().describe("Filter by event name (exact match)"),
+      since_seconds: z27.number().optional().describe("Only events from the last N seconds (default: 300)"),
+      session_id: z27.string().optional().describe("Filter by session ID")
     },
-    async ({ name, since_seconds, session_id }) => {
+    async ({ project_id, name, since_seconds, session_id }) => {
       const sinceSeconds = since_seconds ?? 300;
       const events = store.getCustomEvents({
+        projectId: project_id,
         name,
         sinceSeconds,
         sessionId: session_id
@@ -4625,8 +4692,8 @@ function registerCustomEventTools(server, store) {
         lastSeen: new Date(info.lastSeen).toISOString(),
         sampleProperties: info.sampleProperties
       }));
-      const sessions = store.getSessionInfo();
-      const sessionId = session_id ?? sessions[0]?.sessionId ?? null;
+      const { sessionId: resolvedSessionId } = resolveSessionContext(store, project_id);
+      const sessionId = session_id ?? resolvedSessionId;
       const response = {
         summary: `${events.length} custom event(s) across ${catalogList.length} unique event name(s) in the last ${sinceSeconds}s.${name ? ` Filtered by: "${name}".` : ""}`,
         data: {
@@ -4645,7 +4712,8 @@ function registerCustomEventTools(server, store) {
             to: events.length > 0 ? events[0].timestamp : 0
           },
           eventCount: events.length,
-          sessionId
+          sessionId,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -4657,13 +4725,14 @@ function registerCustomEventTools(server, store) {
     "get_event_flow",
     "Analyze a user flow as a funnel. Given an ordered list of custom event names (steps), shows how many sessions completed each step, where drop-offs happen, and what errors/failures occurred between steps. Each step includes correlated telemetry (network errors, console errors, failed DB queries) that happened between the previous step and this one \u2014 this is the key to finding WHY a step failed.",
     {
-      steps: z26.array(z26.string()).min(2).describe('Ordered list of custom event names representing the flow (e.g. ["create_profile", "generate_campaign", "export_ad"])'),
-      since_seconds: z26.number().optional().describe("Only analyze events from the last N seconds (default: 3600)"),
-      session_id: z26.string().optional().describe("Analyze a specific session (default: all sessions)")
+      project_id: projectIdParam,
+      steps: z27.array(z27.string()).min(2).describe('Ordered list of custom event names representing the flow (e.g. ["create_profile", "generate_campaign", "export_ad"])'),
+      since_seconds: z27.number().optional().describe("Only analyze events from the last N seconds (default: 3600)"),
+      session_id: z27.string().optional().describe("Analyze a specific session (default: all sessions)")
     },
-    async ({ steps, since_seconds, session_id }) => {
+    async ({ project_id, steps, since_seconds, session_id }) => {
       const sinceSeconds = since_seconds ?? 3600;
-      const allCustom = store.getCustomEvents({ sinceSeconds, sessionId: session_id });
+      const allCustom = store.getCustomEvents({ projectId: project_id, sinceSeconds, sessionId: session_id });
       const bySession = /* @__PURE__ */ new Map();
       for (const e of allCustom) {
         if (!bySession.has(e.sessionId)) bySession.set(e.sessionId, []);
@@ -4672,9 +4741,9 @@ function registerCustomEventTools(server, store) {
       for (const events of bySession.values()) {
         events.sort((a, b) => a.timestamp - b.timestamp);
       }
-      const networkErrors = store.getNetworkRequests({ sinceSeconds, sessionId: session_id }).filter((e) => e.status >= 400 || e.errorPhase);
-      const consoleErrors = store.getConsoleMessages({ sinceSeconds, sessionId: session_id }).filter((e) => e.level === "error");
-      const dbErrors = store.getDatabaseEvents({ sinceSeconds, sessionId: session_id }).filter((e) => !!e.error);
+      const networkErrors = store.getNetworkRequests({ projectId: project_id, sinceSeconds, sessionId: session_id }).filter((e) => e.status >= 400 || e.errorPhase);
+      const consoleErrors = store.getConsoleMessages({ projectId: project_id, sinceSeconds, sessionId: session_id }).filter((e) => e.level === "error");
+      const dbErrors = store.getDatabaseEvents({ projectId: project_id, sinceSeconds, sessionId: session_id }).filter((e) => !!e.error);
       const stepResults = steps.map(() => ({
         step: "",
         sessionsReached: 0,
@@ -4771,7 +4840,8 @@ function registerCustomEventTools(server, store) {
             to: allCustom.length > 0 ? allCustom[0].timestamp : 0
           },
           eventCount: allCustom.length,
-          sessionId: session_id ?? null
+          sessionId: session_id ?? null,
+          projectId: project_id ?? null
         }
       };
       return {
@@ -4824,7 +4894,7 @@ function dedup(arr, limit) {
 }
 
 // src/tools/breadcrumbs.ts
-import { z as z27 } from "zod";
+import { z as z28 } from "zod";
 function eventToBreadcrumb(event, anchorTs) {
   const base = {
     timestamp: new Date(event.timestamp).toISOString(),
@@ -4915,17 +4985,19 @@ function registerBreadcrumbTools(server, store) {
     "get_breadcrumbs",
     "Get the chronological trail of user actions, navigation, clicks, console logs, network requests, and state changes leading up to a point in time (or an error). This is the primary debugging context tool \u2014 use it when investigating errors, unexpected behavior, or user-reported issues.",
     {
-      since_seconds: z27.number().optional().describe("How far back to look (default: 60 seconds)"),
-      session_id: z27.string().optional().describe("Filter to a specific session"),
-      before_timestamp: z27.number().optional().describe('Only show breadcrumbs before this Unix ms timestamp (useful for "what happened before this error")'),
-      categories: z27.array(z27.string()).optional().describe("Filter to specific categories: navigation, ui.click, breadcrumb, console.error, console.warn, console.log, http, state, custom.*"),
-      level: z27.enum(["debug", "info", "warning", "error"]).optional().describe("Minimum breadcrumb level to include (default: debug = show all)"),
-      limit: z27.number().optional().describe(`Max breadcrumbs to return (default/max: ${MAX_BREADCRUMBS})`)
+      project_id: projectIdParam,
+      since_seconds: z28.number().optional().describe("How far back to look (default: 60 seconds)"),
+      session_id: z28.string().optional().describe("Filter to a specific session"),
+      before_timestamp: z28.number().optional().describe('Only show breadcrumbs before this Unix ms timestamp (useful for "what happened before this error")'),
+      categories: z28.array(z28.string()).optional().describe("Filter to specific categories: navigation, ui.click, breadcrumb, console.error, console.warn, console.log, http, state, custom.*"),
+      level: z28.enum(["debug", "info", "warning", "error"]).optional().describe("Minimum breadcrumb level to include (default: debug = show all)"),
+      limit: z28.number().optional().describe(`Max breadcrumbs to return (default/max: ${MAX_BREADCRUMBS})`)
     },
-    async ({ since_seconds, session_id, before_timestamp, categories, level, limit }) => {
+    async ({ project_id, since_seconds, session_id, before_timestamp, categories, level, limit }) => {
       const sinceSeconds = since_seconds ?? 60;
       const maxItems = Math.min(limit ?? MAX_BREADCRUMBS, MAX_BREADCRUMBS);
       const allEvents = store.getEventTimeline({
+        projectId: project_id,
         sinceSeconds,
         sessionId: session_id,
         eventTypes: ["navigation", "ui", "console", "network", "state", "custom"]
@@ -4952,8 +5024,8 @@ function registerBreadcrumbTools(server, store) {
         breadcrumbs = breadcrumbs.slice(-maxItems);
       }
       const lastError = breadcrumbs.findLast((bc) => bc.level === "error");
-      const sessions = store.getSessionInfo();
-      const sessionId = session_id ?? sessions[0]?.sessionId ?? null;
+      const { sessionId: resolvedSessionId } = resolveSessionContext(store, project_id);
+      const sessionId = session_id ?? resolvedSessionId;
       const response = {
         summary: `${breadcrumbs.length} breadcrumbs over the last ${sinceSeconds}s${lastError ? ` \u2014 last error: "${lastError.message.slice(0, 80)}"` : ""}`,
         data: breadcrumbs,
@@ -4964,6 +5036,7 @@ function registerBreadcrumbTools(server, store) {
           },
           eventCount: breadcrumbs.length,
           sessionId,
+          projectId: project_id ?? null,
           anchor: new Date(anchor).toISOString(),
           categoryCounts: countCategories(breadcrumbs)
         }
@@ -4983,7 +5056,7 @@ function countCategories(breadcrumbs) {
 }
 
 // src/tools/history.ts
-import { z as z28 } from "zod";
+import { z as z29 } from "zod";
 var EVENT_TYPES = [
   "network",
   "console",
@@ -5022,24 +5095,38 @@ function registerHistoryTools(server, collector, projectManager) {
     "get_historical_events",
     "Query past events from persistent SQLite storage. Use this to access events beyond the in-memory buffer (last 10K events). Events persist across Claude Code restarts. Filter by project, event type, time range, and session.",
     {
-      project: z28.string().describe("Project/app name (the appName used in SDK init)"),
-      event_types: z28.array(z28.enum(EVENT_TYPES)).optional().describe('Filter by event types (e.g., ["network", "console"])'),
-      since: z28.string().optional().describe('Start time \u2014 relative ("2h", "7d", "30m") or ISO date string'),
-      until: z28.string().optional().describe("End time \u2014 relative or ISO date string"),
-      session_id: z28.string().optional().describe("Filter by specific session ID"),
-      limit: z28.number().optional().default(200).describe("Max events to return (default 200, max 1000)"),
-      offset: z28.number().optional().default(0).describe("Pagination offset")
+      project: z29.string().optional().describe("Project/app name (the appName used in SDK init). Required unless project_id is provided."),
+      project_id: z29.string().optional().describe("Project ID (proj_xxx). Alternative to project name \u2014 resolves to the app name automatically."),
+      event_types: z29.array(z29.enum(EVENT_TYPES)).optional().describe('Filter by event types (e.g., ["network", "console"])'),
+      since: z29.string().optional().describe('Start time \u2014 relative ("2h", "7d", "30m") or ISO date string'),
+      until: z29.string().optional().describe("End time \u2014 relative or ISO date string"),
+      session_id: z29.string().optional().describe("Filter by specific session ID"),
+      limit: z29.number().optional().default(200).describe("Max events to return (default 200, max 1000)"),
+      offset: z29.number().optional().default(0).describe("Pagination offset")
     },
-    async ({ project, event_types, since, until, session_id, limit, offset }) => {
-      const sqliteStore = collector.getSqliteStore(project);
+    async ({ project, project_id, event_types, since, until, session_id, limit, offset }) => {
+      const resolvedProject = project ?? (project_id ? projectManager.getAppForProjectId(project_id) : void 0);
+      if (!resolvedProject) {
+        const projects = projectManager.listProjects();
+        const hint = projects.length > 0 ? ` Available projects: ${projects.join(", ")}` : " No projects have connected yet.";
+        return {
+          content: [{ type: "text", text: JSON.stringify({
+            summary: `No project specified or project_id "${project_id}" not found.${hint}`,
+            data: null,
+            issues: ["Provide either project (appName) or project_id (proj_xxx)."],
+            metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null }
+          }, null, 2) }]
+        };
+      }
+      const sqliteStore = collector.getSqliteStore(resolvedProject);
       if (!sqliteStore) {
         const projects = projectManager.listProjects();
         const hint = projects.length > 0 ? ` Available projects: ${projects.join(", ")}` : " No projects have connected yet.";
         return {
           content: [{ type: "text", text: JSON.stringify({
-            summary: `No historical data for project "${project}".${hint}`,
+            summary: `No historical data for project "${resolvedProject}".${hint}`,
             data: null,
-            issues: [`Project "${project}" has no SQLite store. Connect an SDK with appName: "${project}" first.`],
+            issues: [`Project "${resolvedProject}" has no SQLite store. Connect an SDK with appName: "${resolvedProject}" first.`],
             metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null }
           }, null, 2) }]
         };
@@ -5048,7 +5135,7 @@ function registerHistoryTools(server, collector, projectManager) {
       const untilMs = parseDateParam(until);
       const cappedLimit = Math.min(limit, 1e3);
       const events = sqliteStore.getEvents({
-        project,
+        project: resolvedProject,
         sessionId: session_id,
         eventTypes: event_types,
         since: sinceMs,
@@ -5057,7 +5144,7 @@ function registerHistoryTools(server, collector, projectManager) {
         offset
       });
       const totalCount = sqliteStore.getEventCount({
-        project,
+        project: resolvedProject,
         sessionId: session_id,
         eventTypes: event_types,
         since: sinceMs,
@@ -5113,8 +5200,10 @@ function registerHistoryTools(server, collector, projectManager) {
         const eventCount = sqliteStore.getEventCount({ project: name });
         const sessions = sqliteStore.getSessions(name, 100);
         const connectedSessions = sessions.filter((s) => s.isConnected);
+        const config = projectManager.getProjectConfig(name);
         return {
           name,
+          projectId: config?.projectId ?? null,
           eventCount,
           sessionCount: sessions.length,
           activeSessions: connectedSessions.length,
@@ -5148,16 +5237,14 @@ var HTTP_PORT2 = parseInt(process.env.RUNTIMESCOPE_HTTP_PORT ?? "9091", 10);
 var BUFFER_SIZE = parseInt(process.env.RUNTIMESCOPE_BUFFER_SIZE ?? "10000", 10);
 function killStaleProcess(port) {
   try {
-    const pids = execSync2(`lsof -ti :${port} 2>/dev/null`, { encoding: "utf-8" }).trim();
-    if (pids) {
-      const myPid = process.pid.toString();
-      for (const pid of pids.split("\n")) {
-        if (pid && pid !== myPid) {
-          console.error(`[RuntimeScope] Killing stale process ${pid} on port ${port}`);
-          try {
-            process.kill(parseInt(pid, 10), "SIGTERM");
-          } catch {
-          }
+    const pids = getPidsOnPort(port);
+    const myPid = process.pid;
+    for (const pid of pids) {
+      if (pid !== myPid) {
+        console.error(`[RuntimeScope] Killing stale process ${pid} on port ${port}`);
+        try {
+          process.kill(pid, "SIGTERM");
+        } catch {
         }
       }
     }
@@ -5272,6 +5359,7 @@ async function main() {
     rateLimiter: collector.getRateLimiter(),
     pmStore,
     discovery,
+    projectManager,
     getConnectedSessions: () => collector.getConnectedSessions()
   });
   try {
@@ -5279,8 +5367,14 @@ async function main() {
   } catch (err) {
     console.error("[RuntimeScope] HTTP API failed to start:", err.message);
   }
-  collector.onConnect((sessionId, projectName) => {
+  collector.onConnect((sessionId, projectName, projectId) => {
     httpServer.broadcastSessionChange("session_connected", sessionId, projectName);
+    if (pmStore) {
+      try {
+        pmStore.autoLinkApp(projectName, projectId);
+      } catch {
+      }
+    }
   });
   collector.onDisconnect((sessionId, projectName) => {
     httpServer.broadcastSessionChange("session_disconnected", sessionId, projectName);
@@ -5305,7 +5399,7 @@ async function main() {
   registerDatabaseTools(mcp, store, connectionManager, schemaIntrospector, dataBrowser);
   registerProcessMonitorTools(mcp, processMonitor);
   registerInfraTools(mcp, infraConnector);
-  registerSessionDiffTools(mcp, sessionManager, collector);
+  registerSessionDiffTools(mcp, sessionManager, collector, projectManager);
   registerReconMetadataTools(mcp, store, collector);
   registerReconDesignTokenTools(mcp, store, collector);
   registerReconFontTools(mcp, store);
@@ -5315,7 +5409,7 @@ async function main() {
   registerReconElementSnapshotTools(mcp, store, collector, scanner);
   registerReconAssetTools(mcp, store);
   registerReconStyleDiffTools(mcp, store);
-  registerScannerTools(mcp, store, scanner);
+  registerScannerTools(mcp, store, scanner, projectManager);
   registerCustomEventTools(mcp, store);
   registerBreadcrumbTools(mcp, store);
   registerHistoryTools(mcp, collector, projectManager);