@guckdev/mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { startMcpServer } from "./server.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { startMcpServer } from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export declare const startMcpServer: () => Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAgHA,eAAO,MAAM,cAAc,QAAa,QAAQ,IAAI,CA4GnD,CAAC"}

package/dist/server.js

@@ -0,0 +1,183 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig, readCheckpoint, readSearch, readSessions, readStats, readTail, redactEvent, resolveStoreDir, } from "@guckdev/core";
+const SEARCH_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        service: { type: "string" },
+        session_id: { type: "string" },
+        run_id: { type: "string" },
+        types: { type: "array", items: { type: "string" } },
+        levels: { type: "array", items: { type: "string" } },
+        contains: { type: "string" },
+        since: { type: "string" },
+        until: { type: "string" },
+        limit: { type: "number" },
+        backends: { type: "array", items: { type: "string" } },
+        config_path: { type: "string" },
+    },
+};
+const STATS_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        service: { type: "string" },
+        session_id: { type: "string" },
+        since: { type: "string" },
+        until: { type: "string" },
+        group_by: { type: "string", enum: ["type", "level", "stage"] },
+        limit: { type: "number" },
+        backends: { type: "array", items: { type: "string" } },
+        config_path: { type: "string" },
+    },
+    required: ["group_by"],
+};
+const SESSIONS_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        service: { type: "string" },
+        since: { type: "string" },
+        limit: { type: "number" },
+        backends: { type: "array", items: { type: "string" } },
+        config_path: { type: "string" },
+    },
+};
+const TAIL_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        service: { type: "string" },
+        session_id: { type: "string" },
+        run_id: { type: "string" },
+        limit: { type: "number" },
+        backends: { type: "array", items: { type: "string" } },
+        config_path: { type: "string" },
+    },
+};
+const buildText = (payload) => {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+};
+const resolveSince = (input, config, storeDir) => {
+    const checkpointMs = readCheckpoint(storeDir);
+    if (input) {
+        if (input === "checkpoint") {
+            if (checkpointMs !== undefined) {
+                return new Date(checkpointMs).toISOString();
+            }
+            return `${config.mcp.default_lookback_ms}ms`;
+        }
+        return input;
+    }
+    if (checkpointMs !== undefined) {
+        return new Date(checkpointMs).toISOString();
+    }
+    return `${config.mcp.default_lookback_ms}ms`;
+};
+export const startMcpServer = async () => {
+    const server = new Server({
+        name: "guck",
+        version: "0.1.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [
+                {
+                    name: "guck.search",
+                    description: "Search telemetry events with filters.",
+                    inputSchema: SEARCH_SCHEMA,
+                },
+                {
+                    name: "guck.stats",
+                    description: "Aggregate telemetry counts by type/level/stage.",
+                    inputSchema: STATS_SCHEMA,
+                },
+                {
+                    name: "guck.sessions",
+                    description: "List recent sessions and error counts.",
+                    inputSchema: SESSIONS_SCHEMA,
+                },
+                {
+                    name: "guck.tail",
+                    description: "Return the most recent events (non-streaming).",
+                    inputSchema: TAIL_SCHEMA,
+                },
+            ],
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const args = (request.params.arguments ?? {});
+        const { config_path: configPath } = args;
+        const { config, rootDir } = loadConfig({ configPath });
+        if (!config.enabled) {
+            return buildText({
+                error: "Guck is disabled. Create .guck.json or set GUCK_ENABLED=true/GUCK_CONFIG_PATH.",
+            });
+        }
+        const storeDir = resolveStoreDir(config, rootDir);
+        if (request.params.name === "guck.search") {
+            const input = (request.params.arguments ?? {});
+            const { config_path: _configPath, ...filters } = input;
+            const withDefaults = {
+                ...filters,
+                since: resolveSince(filters.since, config, storeDir),
+            };
+            const result = await readSearch(config, rootDir, withDefaults);
+            const redacted = result.events.map((event) => redactEvent(config, event));
+            return buildText({ ...result, events: redacted });
+        }
+        if (request.params.name === "guck.stats") {
+            const input = (request.params.arguments ?? {});
+            const { config_path: _configPath, ...filters } = input;
+            const withDefaults = {
+                ...filters,
+                since: resolveSince(filters.since, config, storeDir),
+            };
+            const result = await readStats(config, rootDir, withDefaults);
+            return buildText(result);
+        }
+        if (request.params.name === "guck.sessions") {
+            const input = (request.params.arguments ?? {});
+            const { config_path: _configPath, ...filters } = input;
+            const withDefaults = {
+                ...filters,
+                since: resolveSince(filters.since, config, storeDir),
+            };
+            const result = await readSessions(config, rootDir, withDefaults);
+            return buildText(result);
+        }
+        if (request.params.name === "guck.tail") {
+            const input = (request.params.arguments ?? {});
+            const { config_path: _configPath, ...filters } = input;
+            const limit = input.limit ?? Math.min(config.mcp.max_results, 50);
+            const since = resolveSince(undefined, config, storeDir);
+            const result = await readTail(config, rootDir, {
+                service: filters.service,
+                session_id: filters.session_id,
+                run_id: filters.run_id,
+                limit,
+                backends: filters.backends,
+                since,
+            });
+            const redacted = result.events.map((event) => redactEvent(config, event));
+            return buildText({ ...result, events: redacted });
+        }
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@guckdev/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Guck telemetry",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts",
+    "src",
+    "tsconfig.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/ensure-deps.mjs && tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "prepare": "pnpm run build",
+    "test": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "@guckdev/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "25.2.2"
+  }
+}

package/scripts/ensure-deps.mjs

@@ -0,0 +1,23 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const dep = { name: "@guckdev/core", entry: "dist/index.js" };
+
+const npmExecPath = process.env.npm_execpath;
+const run = (cwd, args) => {
+  const cmd = npmExecPath ? process.execPath : "pnpm";
+  const cmdArgs = npmExecPath ? [npmExecPath, ...args] : args;
+  const result = spawnSync(cmd, cmdArgs, { cwd, stdio: "inherit" });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+};
+
+const depDir = path.join(process.cwd(), "node_modules", dep.name);
+if (existsSync(depDir)) {
+  const entryPath = path.join(depDir, dep.entry);
+  if (!existsSync(entryPath)) {
+    run(depDir, ["run", "build"]);
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { startMcpServer } from "./server.js";

package/src/server.ts

@@ -0,0 +1,221 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  GuckConfig,
+  GuckSearchParams,
+  GuckSessionsParams,
+  GuckStatsParams,
+  GuckTailParams,
+  loadConfig,
+  readCheckpoint,
+  readSearch,
+  readSessions,
+  readStats,
+  readTail,
+  redactEvent,
+  resolveStoreDir,
+} from "@guckdev/core";
+const SEARCH_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    service: { type: "string" },
+    session_id: { type: "string" },
+    run_id: { type: "string" },
+    types: { type: "array", items: { type: "string" } },
+    levels: { type: "array", items: { type: "string" } },
+    contains: { type: "string" },
+    since: { type: "string" },
+    until: { type: "string" },
+    limit: { type: "number" },
+    backends: { type: "array", items: { type: "string" } },
+    config_path: { type: "string" },
+  },
+} as const;
+
+const STATS_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    service: { type: "string" },
+    session_id: { type: "string" },
+    since: { type: "string" },
+    until: { type: "string" },
+    group_by: { type: "string", enum: ["type", "level", "stage"] },
+    limit: { type: "number" },
+    backends: { type: "array", items: { type: "string" } },
+    config_path: { type: "string" },
+  },
+  required: ["group_by"],
+} as const;
+
+const SESSIONS_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    service: { type: "string" },
+    since: { type: "string" },
+    limit: { type: "number" },
+    backends: { type: "array", items: { type: "string" } },
+    config_path: { type: "string" },
+  },
+} as const;
+
+const TAIL_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    service: { type: "string" },
+    session_id: { type: "string" },
+    run_id: { type: "string" },
+    limit: { type: "number" },
+    backends: { type: "array", items: { type: "string" } },
+    config_path: { type: "string" },
+  },
+} as const;
+
+const buildText = (payload: unknown) => {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+};
+
+const resolveSince = (
+  input: string | undefined,
+  config: GuckConfig,
+  storeDir: string,
+): string => {
+  const checkpointMs = readCheckpoint(storeDir);
+  if (input) {
+    if (input === "checkpoint") {
+      if (checkpointMs !== undefined) {
+        return new Date(checkpointMs).toISOString();
+      }
+      return `${config.mcp.default_lookback_ms}ms`;
+    }
+    return input;
+  }
+  if (checkpointMs !== undefined) {
+    return new Date(checkpointMs).toISOString();
+  }
+  return `${config.mcp.default_lookback_ms}ms`;
+};
+
+export const startMcpServer = async (): Promise<void> => {
+  const server = new Server(
+    {
+      name: "guck",
+      version: "0.1.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        {
+          name: "guck.search",
+          description: "Search telemetry events with filters.",
+          inputSchema: SEARCH_SCHEMA,
+        },
+        {
+          name: "guck.stats",
+          description: "Aggregate telemetry counts by type/level/stage.",
+          inputSchema: STATS_SCHEMA,
+        },
+        {
+          name: "guck.sessions",
+          description: "List recent sessions and error counts.",
+          inputSchema: SESSIONS_SCHEMA,
+        },
+        {
+          name: "guck.tail",
+          description: "Return the most recent events (non-streaming).",
+          inputSchema: TAIL_SCHEMA,
+        },
+      ],
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const args = (request.params.arguments ?? {}) as { config_path?: string };
+    const { config_path: configPath } = args;
+    const { config, rootDir } = loadConfig({ configPath });
+    if (!config.enabled) {
+      return buildText({
+        error:
+          "Guck is disabled. Create .guck.json or set GUCK_ENABLED=true/GUCK_CONFIG_PATH.",
+      });
+    }
+    const storeDir = resolveStoreDir(config, rootDir);
+
+    if (request.params.name === "guck.search") {
+      const input = (request.params.arguments ?? {}) as GuckSearchParams;
+      const { config_path: _configPath, ...filters } = input;
+      const withDefaults: GuckSearchParams = {
+        ...filters,
+        since: resolveSince(filters.since, config, storeDir),
+      };
+      const result = await readSearch(config, rootDir, withDefaults);
+      const redacted = result.events.map((event) => redactEvent(config, event));
+      return buildText({ ...result, events: redacted });
+    }
+
+    if (request.params.name === "guck.stats") {
+      const input = (request.params.arguments ?? {}) as GuckStatsParams;
+      const { config_path: _configPath, ...filters } = input;
+      const withDefaults: GuckStatsParams = {
+        ...filters,
+        since: resolveSince(filters.since, config, storeDir),
+      };
+      const result = await readStats(config, rootDir, withDefaults);
+      return buildText(result);
+    }
+
+    if (request.params.name === "guck.sessions") {
+      const input = (request.params.arguments ?? {}) as GuckSessionsParams;
+      const { config_path: _configPath, ...filters } = input;
+      const withDefaults: GuckSessionsParams = {
+        ...filters,
+        since: resolveSince(filters.since, config, storeDir),
+      };
+      const result = await readSessions(config, rootDir, withDefaults);
+      return buildText(result);
+    }
+
+    if (request.params.name === "guck.tail") {
+      const input = (request.params.arguments ?? {}) as GuckTailParams;
+      const { config_path: _configPath, ...filters } = input;
+      const limit = input.limit ?? Math.min(config.mcp.max_results, 50);
+      const since = resolveSince(undefined, config, storeDir);
+      const result = await readTail(config, rootDir, {
+        service: filters.service,
+        session_id: filters.session_id,
+        run_id: filters.run_id,
+        limit,
+        backends: filters.backends,
+        since,
+      });
+      const redacted = result.events.map((event) => redactEvent(config, event));
+      return buildText({ ...result, events: redacted });
+    }
+
+    throw new Error(`Unknown tool: ${request.params.name}`);
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+};

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}