@monocle.sh/studio 0.1.0

package/dist/db/connection.d.ts

@@ -0,0 +1,20 @@
+import { Database } from "./types.js";
+import { Kysely } from "kysely";
+
+//#region src/db/connection.d.ts
+/**
+ * Initializes a DuckDB connection at the given file path
+ * and returns a typed Kysely instance.
+ */
+declare function initConnection(dbPath: string): Promise<Kysely<Database>>;
+/**
+ * Returns the active DuckDB Kysely instance, or throws
+ * if the connection has not been initialized yet.
+ */
+declare function getDb(): Kysely<Database>;
+/**
+ * Gracefully destroys the DuckDB connection and resets the singleton.
+ */
+declare function closeConnection(): Promise<void>;
+//#endregion
+export { closeConnection, getDb, initConnection };

package/dist/db/connection.js

@@ -0,0 +1,38 @@
+import { Kysely } from "kysely";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DuckDBInstance } from "@duckdb/node-api";
+import { DuckDbDialect } from "kysely-duckdb";
+//#region src/db/connection.ts
+let db = null;
+/**
+* Initializes a DuckDB connection at the given file path
+* and returns a typed Kysely instance.
+*/
+async function initConnection(dbPath) {
+	mkdirSync(dirname(dbPath), { recursive: true });
+	db = new Kysely({ dialect: new DuckDbDialect({
+		database: await DuckDBInstance.create(dbPath),
+		tableMappings: {}
+	}) });
+	return db;
+}
+/**
+* Returns the active DuckDB Kysely instance, or throws
+* if the connection has not been initialized yet.
+*/
+function getDb() {
+	if (!db) throw new Error("DuckDB connection not initialized. Call initConnection() first.");
+	return db;
+}
+/**
+* Gracefully destroys the DuckDB connection and resets the singleton.
+*/
+async function closeConnection() {
+	if (db) {
+		await db.destroy();
+		db = null;
+	}
+}
+//#endregion
+export { closeConnection, getDb, initConnection };

package/dist/db/schema.d.ts

@@ -0,0 +1,10 @@
+import { Database } from "./types.js";
+import { Kysely } from "kysely";
+
+//#region src/db/schema.d.ts
+/**
+ * Creates the spans and logs tables if they don't already exist.
+ */
+declare function initializeSchema(db: Kysely<Database>): Promise<void>;
+//#endregion
+export { initializeSchema };

package/dist/db/schema.js

@@ -0,0 +1,45 @@
+import { sql } from "kysely";
+//#region src/db/schema.ts
+/**
+* Creates the spans and logs tables if they don't already exist.
+*/
+async function initializeSchema(db) {
+	await sql`
+    CREATE TABLE IF NOT EXISTS spans (
+      trace_id            VARCHAR NOT NULL,
+      span_id             VARCHAR NOT NULL,
+      parent_span_id      VARCHAR,
+      span_name           VARCHAR NOT NULL,
+      span_kind           VARCHAR,
+      service_name        VARCHAR,
+      status_code         VARCHAR DEFAULT 'UNSET',
+      status_message      VARCHAR,
+      start_time_unix     BIGINT NOT NULL,
+      end_time_unix       BIGINT NOT NULL,
+      duration_ns         BIGINT NOT NULL,
+      resource_attributes JSON,
+      span_attributes     JSON,
+      scope_name          VARCHAR,
+      scope_version       VARCHAR,
+      events              JSON,
+      PRIMARY KEY (trace_id, span_id)
+    )
+  `.execute(db);
+	await sql`
+    CREATE TABLE IF NOT EXISTS logs (
+      timestamp_unix      BIGINT NOT NULL,
+      trace_id            VARCHAR,
+      span_id             VARCHAR,
+      severity_text       VARCHAR,
+      severity_number     INTEGER,
+      service_name        VARCHAR,
+      body                VARCHAR,
+      resource_attributes JSON,
+      log_attributes      JSON,
+      scope_name          VARCHAR,
+      scope_version       VARCHAR
+    )
+  `.execute(db);
+}
+//#endregion
+export { initializeSchema };

package/dist/db/types.d.ts

@@ -0,0 +1,40 @@
+import { Generated } from "kysely";
+
+//#region src/db/types.d.ts
+interface SpansTable {
+  trace_id: string;
+  span_id: string;
+  parent_span_id: string | null;
+  span_name: string;
+  span_kind: string | null;
+  service_name: string | null;
+  status_code: Generated<string>;
+  status_message: string | null;
+  start_time_unix: bigint;
+  end_time_unix: bigint;
+  duration_ns: bigint;
+  resource_attributes: string | null;
+  span_attributes: string | null;
+  scope_name: string | null;
+  scope_version: string | null;
+  events: string | null;
+}
+interface LogsTable {
+  timestamp_unix: bigint;
+  trace_id: string | null;
+  span_id: string | null;
+  severity_text: string | null;
+  severity_number: number | null;
+  service_name: string | null;
+  body: string | null;
+  resource_attributes: string | null;
+  log_attributes: string | null;
+  scope_name: string | null;
+  scope_version: string | null;
+}
+interface Database {
+  spans: SpansTable;
+  logs: LogsTable;
+}
+//#endregion
+export { Database, LogsTable, SpansTable };

package/dist/db/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/define_tool.d.ts

@@ -0,0 +1,10 @@
+import { ToolDefinition } from "./types.js";
+import { ZodRawShape } from "zod";
+
+//#region src/mcp/define_tool.d.ts
+/**
+ * Type-safe factory for defining MCP tools with Zod schema validation.
+ */
+declare function defineTool<TSchema extends ZodRawShape>(options: ToolDefinition<TSchema>): ToolDefinition<TSchema>;
+//#endregion
+export { defineTool };

package/dist/mcp/define_tool.js

@@ -0,0 +1,9 @@
+//#region src/mcp/define_tool.ts
+/**
+* Type-safe factory for defining MCP tools with Zod schema validation.
+*/
+function defineTool(options) {
+	return options;
+}
+//#endregion
+export { defineTool };

package/dist/mcp/tools/clear_data.d.ts

@@ -0,0 +1,9 @@
+import { ToolDefinition } from "../types.js";
+
+//#region src/mcp/tools/clear_data.d.ts
+/**
+ * MCP tool: clears all collected traces and logs for a fresh session.
+ */
+declare const clearDataTool: ToolDefinition<{}>;
+//#endregion
+export { clearDataTool };

package/dist/mcp/tools/clear_data.js

@@ -0,0 +1,26 @@
+import { SpanRepository } from "../../repositories/span_repository.js";
+import { defineTool } from "../define_tool.js";
+import { LogRepository } from "../../repositories/log_repository.js";
+//#region src/mcp/tools/clear_data.ts
+/**
+* MCP tool: clears all collected traces and logs for a fresh session.
+*/
+const clearDataTool = defineTool({
+	name: "clear_data",
+	description: "Clear all collected traces, logs, and queries. Useful for starting a fresh debugging session.",
+	schema: {},
+	annotations: {
+		destructiveHint: true,
+		readOnlyHint: false,
+		idempotentHint: true
+	},
+	async execute() {
+		const spanRepo = new SpanRepository();
+		const logRepo = new LogRepository();
+		await spanRepo.clearAll();
+		await logRepo.clearAll();
+		return { message: "All telemetry data cleared." };
+	}
+});
+//#endregion
+export { clearDataTool };

package/dist/mcp/tools/get_trace.d.ts

@@ -0,0 +1,12 @@
+import { ToolDefinition } from "../types.js";
+import { z } from "zod";
+
+//#region src/mcp/tools/get_trace.d.ts
+/**
+ * MCP tool: retrieves the full span waterfall for a given trace ID.
+ */
+declare const getTraceTool: ToolDefinition<{
+  traceId: z.ZodString;
+}>;
+//#endregion
+export { getTraceTool };

package/dist/mcp/tools/get_trace.js

@@ -0,0 +1,25 @@
+import { SpanRepository } from "../../repositories/span_repository.js";
+import { defineTool } from "../define_tool.js";
+import SpanTransformer from "../../transformers/span_transformer.js";
+import { z } from "zod";
+//#region src/mcp/tools/get_trace.ts
+/**
+* MCP tool: retrieves the full span waterfall for a given trace ID.
+*/
+const getTraceTool = defineTool({
+	name: "get_trace",
+	description: "Get all spans for a specific trace. Returns the complete waterfall with parent/child relationships, durations, and attributes.",
+	schema: { traceId: z.string().describe("The trace ID to look up") },
+	async execute(params) {
+		const rows = await new SpanRepository().getTraceSpans(params.traceId);
+		if (!rows.length) return { error: "Trace not found" };
+		const spans = rows.map((row) => new SpanTransformer(row).toObject());
+		return {
+			traceId: params.traceId,
+			spanCount: spans.length,
+			spans
+		};
+	}
+});
+//#endregion
+export { getTraceTool };

package/dist/mcp/tools/index.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/mcp/tools/index.d.ts
+/**
+ * Registers all devtools MCP tools on the given server instance,
+ * wrapping each tool's result as a JSON text content block.
+ */
+declare function registerAllTools(server: McpServer): void;
+//#endregion
+export { registerAllTools };

package/dist/mcp/tools/index.js

@@ -0,0 +1,37 @@
+import { listTracesTool } from "./list_traces.js";
+import { getTraceTool } from "./get_trace.js";
+import { listLogsTool } from "./list_logs.js";
+import { listErrorsTool } from "./list_errors.js";
+import { listQueriesTool } from "./list_queries.js";
+import { clearDataTool } from "./clear_data.js";
+//#region src/mcp/tools/index.ts
+const tools = [
+	listTracesTool,
+	getTraceTool,
+	listLogsTool,
+	listErrorsTool,
+	listQueriesTool,
+	clearDataTool
+];
+/**
+* Registers all devtools MCP tools on the given server instance,
+* wrapping each tool's result as a JSON text content block.
+*/
+function registerAllTools(server) {
+	for (const tool of tools) server.registerTool(tool.name, {
+		description: tool.description,
+		inputSchema: tool.schema,
+		annotations: tool.annotations ?? {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, async (params) => {
+		const result = await tool.execute(params);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+}
+//#endregion
+export { registerAllTools };

package/dist/mcp/tools/list_errors.d.ts

@@ -0,0 +1,14 @@
+import { ToolDefinition } from "../types.js";
+import { z } from "zod";
+
+//#region src/mcp/tools/list_errors.d.ts
+/**
+ * MCP tool: lists captured exceptions with type, message, and stacktrace.
+ */
+declare const listErrorsTool: ToolDefinition<{
+  limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  traceId: z.ZodOptional<z.ZodString>;
+}>;
+//#endregion
+export { listErrorsTool };

package/dist/mcp/tools/list_errors.js

@@ -0,0 +1,25 @@
+import { SpanRepository } from "../../repositories/span_repository.js";
+import { defineTool } from "../define_tool.js";
+import { z } from "zod";
+//#region src/mcp/tools/list_errors.ts
+/**
+* MCP tool: lists captured exceptions with type, message, and stacktrace.
+*/
+const listErrorsTool = defineTool({
+	name: "list_errors",
+	description: "List exceptions and errors captured during request processing. Returns exception type, message, stacktrace, and associated trace for debugging.",
+	schema: {
+		limit: z.number().optional().default(50).describe("Number of results (max 100)"),
+		offset: z.number().optional().default(0).describe("Offset for pagination"),
+		traceId: z.string().optional().describe("Filter errors for a specific trace")
+	},
+	async execute(params) {
+		return new SpanRepository().listExceptions({
+			limit: Math.min(params.limit, 100),
+			offset: params.offset,
+			traceId: params.traceId
+		});
+	}
+});
+//#endregion
+export { listErrorsTool };

package/dist/mcp/tools/list_logs.d.ts

@@ -0,0 +1,16 @@
+import { ToolDefinition } from "../types.js";
+import { z } from "zod";
+
+//#region src/mcp/tools/list_logs.d.ts
+/**
+ * MCP tool: lists application logs with severity/search/trace filters.
+ */
+declare const listLogsTool: ToolDefinition<{
+  limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  severity: z.ZodOptional<z.ZodString>;
+  search: z.ZodOptional<z.ZodString>;
+  traceId: z.ZodOptional<z.ZodString>;
+}>;
+//#endregion
+export { listLogsTool };

package/dist/mcp/tools/list_logs.js

@@ -0,0 +1,30 @@
+import { defineTool } from "../define_tool.js";
+import { LogRepository } from "../../repositories/log_repository.js";
+import LogTransformer from "../../transformers/log_transformer.js";
+import { z } from "zod";
+//#region src/mcp/tools/list_logs.ts
+/**
+* MCP tool: lists application logs with severity/search/trace filters.
+*/
+const listLogsTool = defineTool({
+	name: "list_logs",
+	description: "List application logs with filtering by severity, search text, or trace ID. Useful for debugging and understanding application behavior.",
+	schema: {
+		limit: z.number().optional().default(50).describe("Number of results (max 500)"),
+		offset: z.number().optional().default(0).describe("Offset for pagination"),
+		severity: z.string().optional().describe("Filter by severity: trace, debug, info, warn, error, fatal"),
+		search: z.string().optional().describe("Search in log messages and attributes"),
+		traceId: z.string().optional().describe("Filter by trace ID to see logs for a specific request")
+	},
+	async execute(params) {
+		return (await new LogRepository().listLogs({
+			limit: Math.min(params.limit, 500),
+			offset: params.offset,
+			severity: params.severity,
+			search: params.search,
+			traceId: params.traceId
+		})).map((row) => new LogTransformer(row).toObject());
+	}
+});
+//#endregion
+export { listLogsTool };

package/dist/mcp/tools/list_queries.d.ts

@@ -0,0 +1,15 @@
+import { ToolDefinition } from "../types.js";
+import { z } from "zod";
+
+//#region src/mcp/tools/list_queries.d.ts
+/**
+ * MCP tool: lists database queries with SQL, duration, and DB system.
+ */
+declare const listQueriesTool: ToolDefinition<{
+  limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  traceId: z.ZodOptional<z.ZodString>;
+  dbSystem: z.ZodOptional<z.ZodString>;
+}>;
+//#endregion
+export { listQueriesTool };

package/dist/mcp/tools/list_queries.js

@@ -0,0 +1,27 @@
+import { SpanRepository } from "../../repositories/span_repository.js";
+import { defineTool } from "../define_tool.js";
+import { z } from "zod";
+//#region src/mcp/tools/list_queries.ts
+/**
+* MCP tool: lists database queries with SQL, duration, and DB system.
+*/
+const listQueriesTool = defineTool({
+	name: "list_queries",
+	description: "List database queries with performance data. Returns SQL statements, operations, database system, duration, and associated trace. Use dbSystem filter to narrow by database (postgresql, mysql, sqlite, etc.).",
+	schema: {
+		limit: z.number().optional().default(50).describe("Number of results (max 100)"),
+		offset: z.number().optional().default(0).describe("Offset for pagination"),
+		traceId: z.string().optional().describe("Filter queries for a specific trace"),
+		dbSystem: z.string().optional().describe("Filter by database system (e.g., postgresql, mysql, sqlite)")
+	},
+	async execute(params) {
+		return new SpanRepository().listQueries({
+			limit: Math.min(params.limit, 100),
+			offset: params.offset,
+			traceId: params.traceId,
+			dbSystem: params.dbSystem
+		});
+	}
+});
+//#endregion
+export { listQueriesTool };

package/dist/mcp/tools/list_traces.d.ts

@@ -0,0 +1,14 @@
+import { ToolDefinition } from "../types.js";
+import { z } from "zod";
+
+//#region src/mcp/tools/list_traces.d.ts
+/**
+ * MCP tool: lists recent HTTP request traces with pagination.
+ */
+declare const listTracesTool: ToolDefinition<{
+  limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  traceId: z.ZodOptional<z.ZodString>;
+}>;
+//#endregion
+export { listTracesTool };

package/dist/mcp/tools/list_traces.js

@@ -0,0 +1,25 @@
+import { SpanRepository } from "../../repositories/span_repository.js";
+import { defineTool } from "../define_tool.js";
+import { z } from "zod";
+//#region src/mcp/tools/list_traces.ts
+/**
+* MCP tool: lists recent HTTP request traces with pagination.
+*/
+const listTracesTool = defineTool({
+	name: "list_traces",
+	description: "List recent traces with summary data. Use this to explore request flows, filter by status to surface errors, or find slow requests.",
+	schema: {
+		limit: z.number().optional().default(25).describe("Number of results (max 100)"),
+		offset: z.number().optional().default(0).describe("Offset for pagination"),
+		traceId: z.string().optional().describe("Filter by trace ID")
+	},
+	async execute(params) {
+		return await new SpanRepository().listTraces({
+			limit: Math.min(params.limit, 100),
+			offset: params.offset,
+			traceId: params.traceId
+		});
+	}
+});
+//#endregion
+export { listTracesTool };

package/dist/mcp/types.d.ts

@@ -0,0 +1,21 @@
+import { ZodObject, ZodRawShape, z } from "zod";
+
+//#region src/mcp/types.d.ts
+/**
+ * Describes an MCP tool: its name, human-readable description,
+ * Zod input schema, and async execute handler.
+ */
+interface ToolAnnotations {
+  readOnlyHint?: boolean;
+  idempotentHint?: boolean;
+  destructiveHint?: boolean;
+}
+interface ToolDefinition<TSchema extends ZodRawShape = ZodRawShape> {
+  name: string;
+  description: string;
+  schema: TSchema;
+  annotations?: ToolAnnotations;
+  execute: (params: z.infer<ZodObject<TSchema>>) => Promise<unknown>;
+}
+//#endregion
+export { ToolAnnotations, ToolDefinition };

package/dist/mcp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+import { registerAllTools } from "./mcp/tools/index.js";
+export { registerAllTools };

package/dist/mcp.js

@@ -0,0 +1,2 @@
+import { registerAllTools } from "./mcp/tools/index.js";
+export { registerAllTools };

package/dist/providers/api_provider.d.ts

@@ -0,0 +1,14 @@
+import { BaseSerializer } from "@adonisjs/core/transformers";
+
+//#region src/providers/api_provider.d.ts
+declare class ApiSerializer extends BaseSerializer<{
+  Wrap: undefined;
+}> {
+  wrap: undefined;
+  definePaginationMetaData(metaData: unknown): unknown;
+}
+declare module '@adonisjs/core/http' {
+  interface HttpContext {
+    serialize: ApiSerializer['serialize'];
+  }
+}

package/dist/providers/api_provider.js

@@ -0,0 +1,13 @@
+import { BaseSerializer } from "@adonisjs/core/transformers";
+import { HttpContext } from "@adonisjs/core/http";
+//#region src/providers/api_provider.ts
+var ApiSerializer = class extends BaseSerializer {
+	wrap = void 0;
+	definePaginationMetaData(metaData) {
+		return metaData;
+	}
+};
+const serializer = new ApiSerializer();
+HttpContext.instanceProperty("serialize", serializer.serialize.bind(serializer));
+//#endregion
+export {};

package/dist/repositories/log_repository.d.ts

@@ -0,0 +1,43 @@
+import { FlatLog } from "../types/logs.js";
+
+//#region src/repositories/log_repository.d.ts
+/**
+ * Data-access layer for application logs stored in DuckDB.
+ * Supports inserting, listing with filters, and clearing log data.
+ */
+declare class LogRepository {
+  #private;
+  /**
+   * Inserts a batch of flat log entries into the logs table.
+   */
+  insertLogs(logs: FlatLog[]): Promise<void>;
+  /**
+   * Deletes all rows from the logs table.
+   */
+  clearAll(): Promise<void>;
+  /**
+   * Lists logs with optional filtering by severity, full-text
+   * search (body + attributes), and trace ID correlation.
+   */
+  listLogs(options?: {
+    limit?: number;
+    offset?: number;
+    severity?: string;
+    search?: string;
+    traceId?: string;
+  }): Promise<{
+    trace_id: string | null;
+    span_id: string | null;
+    service_name: string | null;
+    timestamp_unix: bigint;
+    severity_text: string | null;
+    severity_number: number | null;
+    body: string | null;
+    resource_attributes: string | null;
+    log_attributes: string | null;
+    scope_name: string | null;
+    scope_version: string | null;
+  }[]>;
+}
+//#endregion
+export { LogRepository };

package/dist/repositories/log_repository.js

@@ -0,0 +1,58 @@
+import { getDb } from "../db/connection.js";
+import { sql } from "kysely";
+//#region src/repositories/log_repository.ts
+/**
+* Data-access layer for application logs stored in DuckDB.
+* Supports inserting, listing with filters, and clearing log data.
+*/
+var LogRepository = class {
+	/**
+	* Serializes a value to JSON, returning null for falsy values.
+	*/
+	#jsonOrNull(value) {
+		if (!value) return null;
+		return JSON.stringify(value);
+	}
+	/**
+	* Inserts a batch of flat log entries into the logs table.
+	*/
+	async insertLogs(logs) {
+		const db = getDb();
+		for (const log of logs) await db.insertInto("logs").values({
+			timestamp_unix: log.timestampUnix,
+			trace_id: log.traceId,
+			span_id: log.spanId,
+			severity_text: log.severityText,
+			severity_number: log.severityNumber,
+			service_name: log.serviceName,
+			body: log.body,
+			resource_attributes: this.#jsonOrNull(log.resourceAttributes),
+			log_attributes: this.#jsonOrNull(log.logAttributes),
+			scope_name: log.scopeName,
+			scope_version: log.scopeVersion
+		}).execute();
+	}
+	/**
+	* Deletes all rows from the logs table.
+	*/
+	async clearAll() {
+		const db = getDb();
+		await sql`DELETE FROM logs`.execute(db);
+	}
+	/**
+	* Lists logs with optional filtering by severity, full-text
+	* search (body + attributes), and trace ID correlation.
+	*/
+	async listLogs(options = {}) {
+		const db = getDb();
+		const limit = options.limit ?? 100;
+		const offset = options.offset ?? 0;
+		let query = db.selectFrom("logs").selectAll().orderBy("timestamp_unix", "desc").limit(limit).offset(offset);
+		if (options.traceId) query = query.where("trace_id", "=", options.traceId);
+		if (options.severity) query = query.where(sql`UPPER(severity_text)`, "=", sql`UPPER(${options.severity})`);
+		if (options.search) query = query.where((eb) => eb.or([eb("body", "ilike", `%${options.search}%`), eb(sql`log_attributes`, "ilike", sql`${"%" + options.search + "%"}`)]));
+		return query.execute();
+	}
+};
+//#endregion
+export { LogRepository };