@lightpath-dev/mcp 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lightpath contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @lightpath-dev/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MCP server of [Lightpath](https://github.com/Unknown-333/Lightpath#readme), so coding agents can ask which code ran for an action you just did in your app.
+
+Run it with `npx -y @lightpath-dev/cli mcp`. Setup for Claude Code, Cursor, VS Code, and Kiro: [Ask your coding agent](https://github.com/Unknown-333/Lightpath#ask-your-coding-agent).

package/dist/format.d.ts

@@ -0,0 +1,9 @@
+import type { LineHit, Trace, TraceSummary } from '@lightpath-dev/protocol';
+/** Compresses sorted line numbers into ranges: [1,2,3,7,9,10] → "1-3, 7, 9-10". */
+export declare function lineRanges(lines: readonly LineHit[]): string;
+/** A compact, agent-readable description of one trace. */
+export declare function describeTrace(trace: Trace): string;
+export declare function describeSummaries(traces: readonly TraceSummary[]): string;
+/** Lines that ran in only one of two traces, per file. */
+export declare function diffTraces(a: Trace, b: Trace): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -0,0 +1,63 @@
+/** Compresses sorted line numbers into ranges: [1,2,3,7,9,10] → "1-3, 7, 9-10". */
+export function lineRanges(lines) {
+    const parts = [];
+    let start;
+    let prev;
+    for (const { line } of lines) {
+        if (start === undefined)
+            start = line;
+        else if (prev !== undefined && line !== prev + 1) {
+            parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+            start = line;
+        }
+        prev = line;
+    }
+    if (start !== undefined && prev !== undefined)
+        parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+    return parts.join(', ');
+}
+/** A compact, agent-readable description of one trace. */
+export function describeTrace(trace) {
+    const out = [`Trace ${trace.id}: ${trace.label}`];
+    for (const r of trace.requests) {
+        out.push(`  request: ${r.method} ${r.path}${r.status ? ` → ${r.status}` : ''} (${r.collector}, ${Math.round(r.durationMs)} ms${r.overlapped ? ', overlapped with another request' : ''})`);
+    }
+    if (trace.files.length === 0)
+        out.push('  no workspace code ran');
+    for (const f of trace.files) {
+        const hottest = Math.max(...f.lines.map((l) => l.count));
+        const bg = f.background ? ' (background: only code that also runs while idle, likely unrelated)' : '';
+        out.push(`  ${f.path} [${f.collector}] lines ${lineRanges(f.lines)}${hottest > 1 ? ` (max ${hottest} hits)` : ''}${bg}`);
+    }
+    const dropped = trace.dropped.filter((d) => d.count > 0);
+    if (dropped.length > 0)
+        out.push(`  not shown: ${dropped.map((d) => `${d.count} ${d.reason}`).join(', ')}`);
+    return out.join('\n');
+}
+export function describeSummaries(traces) {
+    if (traces.length === 0)
+        return 'No traces yet. Click something in the app opened by `lightpath dev`.';
+    return traces
+        .map((t) => `${t.id}  ${new Date(t.startedAt).toISOString()}  ${t.label}  (${t.fileCount} files)`)
+        .join('\n');
+}
+/** Lines that ran in only one of two traces, per file. */
+export function diffTraces(a, b) {
+    const index = (t) => new Map(t.files.map((f) => [f.path, new Set(f.lines.map((l) => l.line))]));
+    const ia = index(a);
+    const ib = index(b);
+    const out = [`Lines that ran in only one of ${a.id} (${a.label}) and ${b.id} (${b.label}):`];
+    for (const path of [...new Set([...ia.keys(), ...ib.keys()])].sort()) {
+        const la = ia.get(path) ?? new Set();
+        const lb = ib.get(path) ?? new Set();
+        const onlyA = [...la].filter((l) => !lb.has(l)).sort((x, y) => x - y);
+        const onlyB = [...lb].filter((l) => !la.has(l)).sort((x, y) => x - y);
+        const fmt = (ls) => lineRanges(ls.map((line) => ({ line, count: 1 })));
+        if (onlyA.length)
+            out.push(`  ${path}: only in A: ${fmt(onlyA)}`);
+        if (onlyB.length)
+            out.push(`  ${path}: only in B: ${fmt(onlyB)}`);
+    }
+    return out.length === 1 ? `${out[0]}\n  none, both traces ran the same lines` : out.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { describeSummaries, describeTrace, diffTraces, lineRanges } from './format.js';
+export { createMcpServer, type McpOptions, runMcpServer } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+export { describeSummaries, describeTrace, diffTraces, lineRanges } from './format.js';
+export { createMcpServer, runMcpServer } from './server.js';
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export interface McpOptions {
+    workspaceRoot: string;
+}
+/**
+ * Builds the MCP server (docs/ARCHITECTURE.md section 9.3). Every call reads the discovery file
+ * and connects fresh, so the server works whether `lightpath dev` started before or after it.
+ */
+export declare function createMcpServer(options: McpOptions): McpServer;
+/** Runs the MCP server over stdio. stdout belongs to the protocol, so nothing else may print to it. */
+export declare function runMcpServer(options: McpOptions): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { DaemonClient, DaemonDiscovery, DISCOVERY_FILE } from '@lightpath-dev/protocol';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { describeSummaries, describeTrace, diffTraces } from './format.js';
+/** This package's version, read from package.json next to dist/ so it can't drift. */
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const text = (t) => ({ content: [{ type: 'text', text: t }] });
+const traceIdSchema = z
+    .string()
+    .regex(/^t_[a-z0-9]{12}$/)
+    .describe('Trace id, like t_k3x9q0m2a7bz');
+/**
+ * Builds the MCP server (docs/ARCHITECTURE.md section 9.3). Every call reads the discovery file
+ * and connects fresh, so the server works whether `lightpath dev` started before or after it.
+ */
+export function createMcpServer(options) {
+    const server = new McpServer({ name: 'lightpath', version: VERSION });
+    const withClient = async (fn) => {
+        const client = await connect(options.workspaceRoot);
+        try {
+            return await fn(client);
+        }
+        finally {
+            client.close();
+        }
+    };
+    server.registerTool('list_traces', {
+        description: 'List recent user actions (clicks and requests) recorded by Lightpath, newest first.',
+        inputSchema: {
+            label: z.string().optional().describe('Only actions whose label contains this text, e.g. "Checkout"'),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+    }, async ({ label, limit }) => text(describeSummaries(await withClient((c) => c.listTraces({ limit: limit ?? 20, ...(label ? { label } : {}) })))));
+    server.registerTool('get_trace', {
+        description: 'Show every source file and line that ran for one recorded action, frontend and backend.',
+        inputSchema: { traceId: traceIdSchema },
+    }, async ({ traceId }) => {
+        const trace = await withClient((c) => c.getTrace(traceId));
+        return text(trace ? describeTrace(trace) : `No trace ${traceId}; it may have been evicted.`);
+    });
+    server.registerTool('find_code_for_action', {
+        description: 'Find the code that runs when the user does something in the app, e.g. "Checkout" or "Add to cart". ' +
+            'Uses real runtime data from the most recent matching action, not static analysis.',
+        inputSchema: { action: z.string().min(1).describe('Words from the button or link label') },
+    }, async ({ action }) => {
+        const trace = await withClient(async (c) => {
+            const [match] = await c.listTraces({ label: action, limit: 1 });
+            return match ? c.getTrace(match.id) : null;
+        });
+        return text(trace
+            ? describeTrace(trace)
+            : `No recorded action matches "${action}". Ask the user to click it in the app opened by \`lightpath dev\`, then try again.`);
+    });
+    server.registerTool('diff_traces', {
+        description: 'Compare two recorded actions and list the lines that ran in only one of them.',
+        inputSchema: { a: traceIdSchema, b: traceIdSchema },
+    }, async ({ a, b }) => {
+        const [ta, tb] = await withClient((c) => Promise.all([c.getTrace(a), c.getTrace(b)]));
+        if (!ta || !tb)
+            return text(`Trace not found: ${[!ta && a, !tb && b].filter(Boolean).join(', ')}`);
+        return text(diffTraces(ta, tb));
+    });
+    return server;
+}
+/** Runs the MCP server over stdio. stdout belongs to the protocol, so nothing else may print to it. */
+export async function runMcpServer(options) {
+    await createMcpServer(options).connect(new StdioServerTransport());
+}
+async function connect(workspaceRoot) {
+    // The nearest folder at or above the root with a discovery file: editors don't always start
+    // MCP servers in the project folder itself.
+    let raw;
+    for (let dir = resolve(workspaceRoot);;) {
+        raw = await readFile(join(dir, DISCOVERY_FILE), 'utf8').catch(() => undefined);
+        const parent = dirname(dir);
+        if (raw !== undefined || parent === dir)
+            break;
+        dir = parent;
+    }
+    if (raw === undefined) {
+        throw new Error(`Lightpath isn't running in ${workspaceRoot}. Start it with: lightpath dev -- <your dev command>`);
+    }
+    const info = DaemonDiscovery.parse(JSON.parse(raw));
+    return DaemonClient.connect(info.port, info.token);
+}
+//# sourceMappingURL=server.js.map

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@lightpath-dev/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "MCP server that lets coding agents ask which code ran for an action in your app",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "coverage",
+    "trace",
+    "agent"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/Unknown-333/Lightpath#readme",
+  "bugs": "https://github.com/Unknown-333/Lightpath/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Unknown-333/Lightpath.git",
+    "directory": "packages/mcp"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lightpath-dev/protocol": "0.0.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "zod": "4.6.7"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p test"
+  }
 }