@arvoretech/runtime-lens-mcp 1.0.0

package/src/runtime-interceptor.ts

@@ -0,0 +1,152 @@
+import { LogCollector } from "./log-collector.js";
+import type { Framework, LogLevel } from "./types.js";
+
+type ConsoleMethod = "log" | "info" | "warn" | "error" | "debug";
+
+const LEVEL_MAP: Record<ConsoleMethod, LogLevel> = {
+  log: "info",
+  info: "info",
+  warn: "warn",
+  error: "error",
+  debug: "debug",
+};
+
+export class RuntimeInterceptor {
+  private originalConsole: Record<ConsoleMethod, (...args: unknown[]) => void> = {} as any;
+  private intercepting = false;
+  private readonly collector: LogCollector;
+  private readonly framework: Framework;
+
+  constructor(collector: LogCollector, framework: Framework = "unknown") {
+    this.collector = collector;
+    this.framework = framework;
+  }
+
+  startIntercepting(): void {
+    if (this.intercepting) return;
+
+    const methods: ConsoleMethod[] = ["log", "info", "warn", "error", "debug"];
+
+    for (const method of methods) {
+      this.originalConsole[method] = console[method].bind(console);
+
+      console[method] = (...args: unknown[]) => {
+        this.collector.addLog({
+          level: LEVEL_MAP[method],
+          message: args.map((a) => this.serialize(a)).join(" "),
+          source: "console",
+          framework: this.framework,
+          stackTrace: method === "error" ? this.captureStack() : undefined,
+          metadata: args.length === 1 && typeof args[0] === "object" ? args[0] as Record<string, unknown> : undefined,
+        });
+
+        this.originalConsole[method](...args);
+      };
+    }
+
+    this.interceptStderr();
+    this.interceptUncaughtErrors();
+
+    this.intercepting = true;
+  }
+
+  stopIntercepting(): void {
+    if (!this.intercepting) return;
+
+    const methods: ConsoleMethod[] = ["log", "info", "warn", "error", "debug"];
+    for (const method of methods) {
+      if (this.originalConsole[method]) {
+        console[method] = this.originalConsole[method];
+      }
+    }
+
+    this.intercepting = false;
+  }
+
+  isActive(): boolean {
+    return this.intercepting;
+  }
+
+  private interceptStderr(): void {
+    const originalWrite = process.stderr.write.bind(process.stderr);
+
+    process.stderr.write = ((
+      chunk: string | Uint8Array,
+      encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+      callback?: (error?: Error | null) => void
+    ): boolean => {
+      const text = typeof chunk === "string" ? chunk : chunk.toString();
+
+      if (text.trim() && !text.includes("MCP Server")) {
+        this.collector.addLog({
+          level: this.inferLevel(text),
+          message: text.trim(),
+          source: "stderr",
+          framework: this.framework,
+          stackTrace: text.includes("Error") ? text : undefined,
+        });
+      }
+
+      if (typeof encodingOrCallback === "function") {
+        return originalWrite(chunk, encodingOrCallback);
+      }
+      return originalWrite(chunk, encodingOrCallback, callback);
+    }) as typeof process.stderr.write;
+  }
+
+  private interceptUncaughtErrors(): void {
+    process.on("uncaughtException", (error) => {
+      this.collector.addLog({
+        level: "fatal",
+        message: error.message,
+        source: "uncaughtException",
+        framework: this.framework,
+        stackTrace: error.stack,
+        metadata: { name: error.name },
+      });
+    });
+
+    process.on("unhandledRejection", (reason) => {
+      this.collector.addLog({
+        level: "error",
+        message: reason instanceof Error ? reason.message : String(reason),
+        source: "unhandledRejection",
+        framework: this.framework,
+        stackTrace: reason instanceof Error ? reason.stack : undefined,
+      });
+    });
+  }
+
+  private serialize(value: unknown): string {
+    if (value === null) return "null";
+    if (value === undefined) return "undefined";
+    if (typeof value === "string") return value;
+    if (value instanceof Error) return `${value.name}: ${value.message}\n${value.stack}`;
+    if (typeof value === "object") {
+      try {
+        return JSON.stringify(value, null, 2);
+      } catch {
+        return Object.prototype.toString.call(value);
+      }
+    }
+    return String(value);
+  }
+
+  private captureStack(): string {
+    const stack = new Error().stack || "";
+    return stack
+      .split("\n")
+      .slice(3)
+      .filter((line) => !line.includes("runtime-interceptor"))
+      .join("\n");
+  }
+
+  private inferLevel(text: string): LogLevel {
+    const lower = text.toLowerCase();
+    if (lower.includes("fatal") || lower.includes("critical")) return "fatal";
+    if (lower.includes("error")) return "error";
+    if (lower.includes("warn")) return "warn";
+    if (lower.includes("debug") || lower.includes("verbose")) return "debug";
+    return "info";
+  }
+}

package/src/server.ts

@@ -0,0 +1,387 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { LogCollector } from "./log-collector.js";
+import { ProcessInspector } from "./process-inspector.js";
+import { RuntimeInterceptor } from "./runtime-interceptor.js";
+import {
+  TailLogsParamsSchema,
+  SearchLogsParamsSchema,
+  GetErrorsParamsSchema,
+  InspectRequestParamsSchema,
+  GetPerformanceParamsSchema,
+} from "./types.js";
+
+export class RuntimeLensMCPServer {
+  private readonly server: McpServer;
+  private readonly collector: LogCollector;
+  private readonly inspector: ProcessInspector;
+  private readonly interceptor: RuntimeInterceptor;
+
+  constructor(projectRoot?: string, logPaths?: string[]) {
+    this.server = new McpServer({
+      name: "runtime-lens-mcp",
+      version: "1.0.0",
+    });
+
+    this.collector = new LogCollector(projectRoot, logPaths);
+    this.inspector = new ProcessInspector(projectRoot);
+    this.interceptor = new RuntimeInterceptor(this.collector);
+
+    this.setupTools();
+  }
+
+  static fromEnvironment(): RuntimeLensMCPServer {
+    const projectRoot = process.env.RUNTIME_LENS_PROJECT_ROOT || process.cwd();
+    const logPaths = process.env.RUNTIME_LENS_LOG_PATHS?.split(",").filter(Boolean) || [];
+    return new RuntimeLensMCPServer(projectRoot, logPaths);
+  }
+
+  private setupTools(): void {
+    this.registerTailLogs();
+    this.registerSearchLogs();
+    this.registerGetErrors();
+    this.registerInspectRequests();
+    this.registerGetPerformance();
+    this.registerGetEnvInfo();
+    this.registerClearLogs();
+    this.registerGetStats();
+    this.registerStartInterceptor();
+    this.registerStopInterceptor();
+    this.registerCollectLogs();
+    this.registerScanProject();
+    this.registerFindProcesses();
+    this.registerGetPorts();
+  }
+
+  private registerTailLogs(): void {
+    this.server.registerTool(
+      "tail_logs",
+      {
+        title: "Tail Logs",
+        description: "Retrieve recent log entries from the application buffer. Supports filtering by level, framework, and source.",
+        inputSchema: {
+          lines: TailLogsParamsSchema.shape.lines,
+          level: TailLogsParamsSchema.shape.level,
+          framework: TailLogsParamsSchema.shape.framework,
+          source: TailLogsParamsSchema.shape.source,
+        },
+      },
+      async (params) => {
+        const logs = this.collector.getLogs(params);
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(logs, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerSearchLogs(): void {
+    this.server.registerTool(
+      "search_logs",
+      {
+        title: "Search Logs",
+        description: "Search through collected logs using regex patterns. Filter by level, framework, and time range.",
+        inputSchema: {
+          query: SearchLogsParamsSchema.shape.query,
+          level: SearchLogsParamsSchema.shape.level,
+          framework: SearchLogsParamsSchema.shape.framework,
+          limit: SearchLogsParamsSchema.shape.limit,
+          since: SearchLogsParamsSchema.shape.since,
+        },
+      },
+      async (params) => {
+        const logs = this.collector.searchLogs(params as any);
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(logs, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerGetErrors(): void {
+    this.server.registerTool(
+      "get_errors",
+      {
+        title: "Get Errors",
+        description: "Retrieve recent errors with stack traces. Optionally group similar errors together to identify patterns.",
+        inputSchema: {
+          limit: GetErrorsParamsSchema.shape.limit,
+          framework: GetErrorsParamsSchema.shape.framework,
+          grouped: GetErrorsParamsSchema.shape.grouped,
+        },
+      },
+      async (params) => {
+        const errors = this.collector.getErrors(params);
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(errors, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerInspectRequests(): void {
+    this.server.registerTool(
+      "inspect_requests",
+      {
+        title: "Inspect HTTP Requests",
+        description: "Inspect captured HTTP requests and responses. Filter by method, URL pattern, status code, or specific request ID.",
+        inputSchema: {
+          id: InspectRequestParamsSchema.shape.id,
+          method: InspectRequestParamsSchema.shape.method,
+          urlPattern: InspectRequestParamsSchema.shape.urlPattern,
+          statusCode: InspectRequestParamsSchema.shape.statusCode,
+          limit: InspectRequestParamsSchema.shape.limit,
+        },
+      },
+      async (params) => {
+        const requests = this.collector.getRequests(params);
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(requests, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerGetPerformance(): void {
+    this.server.registerTool(
+      "get_performance",
+      {
+        title: "Get Performance Metrics",
+        description: "Retrieve performance metrics including memory usage, CPU, and custom metrics from the application.",
+        inputSchema: {
+          metric: GetPerformanceParamsSchema.shape.metric,
+          since: GetPerformanceParamsSchema.shape.since,
+          limit: GetPerformanceParamsSchema.shape.limit,
+        },
+      },
+      async (params) => {
+        await this.collector.collectFromProcess();
+        const metrics = this.collector.getMetrics(params);
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(metrics, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerGetEnvInfo(): void {
+    this.server.registerTool(
+      "get_env_info",
+      {
+        title: "Get Environment Info",
+        description: "Get comprehensive environment information including running Node.js processes, listening ports, project framework detection, and system resources.",
+        inputSchema: {},
+      },
+      async () => {
+        const info = await this.inspector.getEnvironmentInfo();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(info, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerClearLogs(): void {
+    this.server.registerTool(
+      "clear_logs",
+      {
+        title: "Clear Log Buffer",
+        description: "Clear all collected logs, requests, and metrics from the buffer.",
+        inputSchema: {},
+      },
+      async () => {
+        const result = this.collector.clearLogs();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ message: `Cleared ${result.cleared} entries` }),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerGetStats(): void {
+    this.server.registerTool(
+      "get_stats",
+      {
+        title: "Get Log Statistics",
+        description: "Get statistics about collected logs including counts by level and framework.",
+        inputSchema: {},
+      },
+      async () => {
+        const stats = this.collector.getStats();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(stats, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerStartInterceptor(): void {
+    this.server.registerTool(
+      "start_interceptor",
+      {
+        title: "Start Console Interceptor",
+        description: "Start intercepting console.log/warn/error/debug calls and stderr output in real-time. Captured output is stored in the log buffer.",
+        inputSchema: {},
+      },
+      async () => {
+        this.interceptor.startIntercepting();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ message: "Console interceptor started", active: true }),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerStopInterceptor(): void {
+    this.server.registerTool(
+      "stop_interceptor",
+      {
+        title: "Stop Console Interceptor",
+        description: "Stop intercepting console output. Previously captured logs remain in the buffer.",
+        inputSchema: {},
+      },
+      async () => {
+        this.interceptor.stopIntercepting();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ message: "Console interceptor stopped", active: false }),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerCollectLogs(): void {
+    this.server.registerTool(
+      "collect_from_files",
+      {
+        title: "Collect Logs from Files",
+        description: "Scan and collect logs from log files in the project directory. Automatically discovers .log and .json files in common log directories.",
+        inputSchema: {},
+      },
+      async () => {
+        await this.collector.collectFromFiles();
+        const stats = this.collector.getStats();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ message: "Log collection complete", stats }),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerScanProject(): void {
+    this.server.registerTool(
+      "scan_project",
+      {
+        title: "Scan Project Structure",
+        description: "Analyze the project to detect framework (React/Next.js/NestJS), find log files, and list configuration files.",
+        inputSchema: {},
+      },
+      async () => {
+        const structure = await this.collector.scanProjectStructure();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(structure, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerFindProcesses(): void {
+    this.server.registerTool(
+      "find_processes",
+      {
+        title: "Find Running Node Processes",
+        description: "Find running Node.js processes related to React, Next.js, or NestJS applications.",
+        inputSchema: {},
+      },
+      async () => {
+        const processes = await this.inspector.findRunningProcesses();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(processes, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  private registerGetPorts(): void {
+    this.server.registerTool(
+      "get_listening_ports",
+      {
+        title: "Get Listening Ports",
+        description: "List all TCP ports currently being listened on by Node.js processes.",
+        inputSchema: {},
+      },
+      async () => {
+        const ports = await this.inspector.getPortListeners();
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify(ports, null, 2),
+          }],
+        };
+      }
+    );
+  }
+
+  async start(): Promise<void> {
+    try {
+      const transport = new StdioServerTransport();
+      await this.server.connect(transport);
+      console.error("Runtime Lens MCP Server started successfully");
+    } catch (error) {
+      console.error(
+        "Failed to start Runtime Lens MCP Server:",
+        error instanceof Error ? error.message : error
+      );
+      process.exit(1);
+    }
+  }
+
+  setupGracefulShutdown(): void {
+    const shutdown = async (signal: string): Promise<void> => {
+      console.error(`Received ${signal}, shutting down gracefully...`);
+      this.interceptor.stopIntercepting();
+      process.exit(0);
+    };
+
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+  }
+}

package/src/types.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+
+export const LogLevel = z.enum(["debug", "info", "warn", "error", "fatal"]);
+export type LogLevel = z.infer<typeof LogLevel>;
+
+export const Framework = z.enum(["react", "nextjs", "nestjs", "unknown"]);
+export type Framework = z.infer<typeof Framework>;
+
+export const LogEntrySchema = z.object({
+  id: z.string(),
+  timestamp: z.string(),
+  level: LogLevel,
+  message: z.string(),
+  source: z.string().optional(),
+  framework: Framework.optional(),
+  metadata: z.record(z.unknown()).optional(),
+  stackTrace: z.string().optional(),
+});
+export type LogEntry = z.infer<typeof LogEntrySchema>;
+
+export const HttpRequestSchema = z.object({
+  id: z.string(),
+  timestamp: z.string(),
+  method: z.string(),
+  url: z.string(),
+  statusCode: z.number().optional(),
+  duration: z.number().optional(),
+  requestHeaders: z.record(z.string()).optional(),
+  responseHeaders: z.record(z.string()).optional(),
+  requestBody: z.unknown().optional(),
+  responseBody: z.unknown().optional(),
+  framework: Framework.optional(),
+  error: z.string().optional(),
+});
+export type HttpRequest = z.infer<typeof HttpRequestSchema>;
+
+export const PerformanceMetricSchema = z.object({
+  name: z.string(),
+  value: z.number(),
+  unit: z.string(),
+  timestamp: z.string(),
+  tags: z.record(z.string()).optional(),
+});
+export type PerformanceMetric = z.infer<typeof PerformanceMetricSchema>;
+
+export const ProcessInfoSchema = z.object({
+  pid: z.number(),
+  uptime: z.number(),
+  memoryUsage: z.object({
+    rss: z.number(),
+    heapTotal: z.number(),
+    heapUsed: z.number(),
+    external: z.number(),
+  }),
+  cpuUsage: z.object({
+    user: z.number(),
+    system: z.number(),
+  }),
+  nodeVersion: z.string(),
+  platform: z.string(),
+  arch: z.string(),
+  cwd: z.string(),
+  env: z.record(z.string()).optional(),
+});
+export type ProcessInfo = z.infer<typeof ProcessInfoSchema>;
+
+export const TailLogsParamsSchema = z.object({
+  lines: z.number().min(1).max(1000).default(50).describe("Number of recent log lines to retrieve"),
+  level: LogLevel.optional().describe("Filter by log level"),
+  framework: Framework.optional().describe("Filter by framework"),
+  source: z.string().optional().describe("Filter by source file or module"),
+});
+export type TailLogsParams = z.infer<typeof TailLogsParamsSchema>;
+
+export const SearchLogsParamsSchema = z.object({
+  query: z.string().min(1).describe("Search pattern (supports regex)"),
+  level: LogLevel.optional().describe("Filter by log level"),
+  framework: Framework.optional().describe("Filter by framework"),
+  limit: z.number().min(1).max(500).default(50).describe("Maximum results to return"),
+  since: z.string().optional().describe("ISO timestamp to search from"),
+});
+export type SearchLogsParams = z.infer<typeof SearchLogsParamsSchema>;
+
+export const GetErrorsParamsSchema = z.object({
+  limit: z.number().min(1).max(100).default(20).describe("Maximum errors to return"),
+  framework: Framework.optional().describe("Filter by framework"),
+  grouped: z.boolean().default(false).describe("Group similar errors together"),
+});
+export type GetErrorsParams = z.infer<typeof GetErrorsParamsSchema>;
+
+export const InspectRequestParamsSchema = z.object({
+  id: z.string().optional().describe("Specific request ID to inspect"),
+  method: z.string().optional().describe("Filter by HTTP method"),
+  urlPattern: z.string().optional().describe("Filter by URL pattern (supports regex)"),
+  statusCode: z.number().optional().describe("Filter by status code"),
+  limit: z.number().min(1).max(100).default(20).describe("Maximum requests to return"),
+});
+export type InspectRequestParams = z.infer<typeof InspectRequestParamsSchema>;
+
+export const GetPerformanceParamsSchema = z.object({
+  metric: z.string().optional().describe("Specific metric name to retrieve"),
+  since: z.string().optional().describe("ISO timestamp to get metrics from"),
+  limit: z.number().min(1).max(100).default(20).describe("Maximum metrics to return"),
+});
+export type GetPerformanceParams = z.infer<typeof GetPerformanceParamsSchema>;
+
+export const ExecuteInContextParamsSchema = z.object({
+  expression: z.string().min(1).describe("JavaScript expression to evaluate"),
+  framework: Framework.optional().describe("Target framework context"),
+});
+export type ExecuteInContextParams = z.infer<typeof ExecuteInContextParamsSchema>;
+
+export const WatchParamsSchema = z.object({
+  pattern: z.string().min(1).describe("File glob pattern or log pattern to watch"),
+  duration: z.number().min(1).max(300).default(30).describe("Watch duration in seconds"),
+});
+export type WatchParams = z.infer<typeof WatchParamsSchema>;
+
+export class RuntimeLensError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = "RuntimeLensError";
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    passWithNoTests: true,
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+    },
+  },
+});