@xiaolei.shawn/mcp-server 0.2.0

package/dist/event-envelope.js

@@ -0,0 +1 @@
+export const EVENT_SCHEMA_VERSION = 1;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { startDashboardServer } from "./dashboard.js";
+import { exportSessionJson, listSessionFiles } from "./store.js";
+import { handleGatewayAct, handleGatewayBeginRun, handleGatewayEndRun, handleRecordActivity, handleRecordAssumption, handleRecordDecision, handleRecordIntent, handleRecordSessionEnd, handleRecordSessionStart, handleRecordVerification, toolSchemas, } from "./tools.js";
+function registerTools(server) {
+    server.registerTool("gateway_begin_run", {
+        description: "Gateway start: starts/reuses session and can create initial intent.",
+        inputSchema: toolSchemas.gateway_begin_run.inputSchema,
+    }, handleGatewayBeginRun);
+    server.registerTool("gateway_act", {
+        description: "Gateway action router: maps operation to semantic recorder tools/events with validation.",
+        inputSchema: toolSchemas.gateway_act.inputSchema,
+    }, handleGatewayAct);
+    server.registerTool("gateway_end_run", {
+        description: "Gateway end: closes active session with outcome/summary.",
+        inputSchema: toolSchemas.gateway_end_run.inputSchema,
+    }, handleGatewayEndRun);
+    server.registerTool("record_session_start", {
+        description: "Start a session and persist a canonical session_start event.",
+        inputSchema: toolSchemas.record_session_start.inputSchema,
+    }, handleRecordSessionStart);
+    server.registerTool("record_intent", {
+        description: "Record intent for the active session and return intent_id.",
+        inputSchema: toolSchemas.record_intent.inputSchema,
+    }, handleRecordIntent);
+    server.registerTool("record_activity", {
+        description: "Record activity events (file_op or tool_call) for the active session.",
+        inputSchema: toolSchemas.record_activity.inputSchema,
+    }, handleRecordActivity);
+    server.registerTool("record_decision", {
+        description: "Record a decision event for the active session.",
+        inputSchema: toolSchemas.record_decision.inputSchema,
+    }, handleRecordDecision);
+    server.registerTool("record_assumption", {
+        description: "Record an assumption event for the active session.",
+        inputSchema: toolSchemas.record_assumption.inputSchema,
+    }, handleRecordAssumption);
+    server.registerTool("record_verification", {
+        description: "Record verification outcomes (test/lint/typecheck/manual).",
+        inputSchema: toolSchemas.record_verification.inputSchema,
+    }, handleRecordVerification);
+    server.registerTool("record_session_end", {
+        description: "End active session and persist a canonical session_end event.",
+        inputSchema: toolSchemas.record_session_end.inputSchema,
+    }, handleRecordSessionEnd);
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "darwin"
+        ? [url]
+        : platform === "win32"
+            ? ["/c", "start", "", url]
+            : [url];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.unref();
+}
+async function runMcpServer() {
+    const server = new McpServer({
+        name: "al-mcp-server",
+        version: "0.2.0",
+    });
+    registerTools(server);
+    startDashboardServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write("AL MCP server connected (stdio)\n");
+}
+function runStart(openFlag) {
+    const dashboard = startDashboardServer();
+    if (!dashboard) {
+        process.stderr.write("Dashboard is disabled via env.\n");
+        process.exitCode = 1;
+        return;
+    }
+    const url = `http://${dashboard.host}:${dashboard.port}`;
+    if (openFlag) {
+        try {
+            openBrowser(url);
+        }
+        catch (error) {
+            process.stderr.write(`Failed to open browser: ${error instanceof Error ? error.message : String(error)}\n`);
+        }
+    }
+    process.stderr.write(`AgentLens local gateway is running at ${url}\n` +
+        "Use MCP mode in your agent config with: `agentlens mcp`\n");
+}
+function parseFlag(flag) {
+    const index = process.argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    return process.argv[index + 1];
+}
+function runExport() {
+    const explicitSession = parseFlag("--session");
+    const out = parseFlag("--out");
+    const latest = process.argv.includes("--latest");
+    const sessions = listSessionFiles();
+    if (sessions.length === 0) {
+        throw new Error("No sessions found.");
+    }
+    const target = explicitSession
+        ? sessions.find((item) => item.session_id === explicitSession)
+        : latest || !explicitSession
+            ? sessions[0]
+            : undefined;
+    if (!target) {
+        throw new Error(`Session not found: ${explicitSession}`);
+    }
+    const exported = exportSessionJson(target.session_id);
+    if (out) {
+        const path = resolve(out);
+        writeFileSync(path, exported, "utf-8");
+        process.stdout.write(`Exported ${target.session_id} -> ${path}\n`);
+        return;
+    }
+    process.stdout.write(exported + "\n");
+}
+async function main() {
+    const command = process.argv[2] ?? "mcp";
+    if (command === "start") {
+        runStart(process.argv.includes("--open"));
+        return;
+    }
+    if (command === "export") {
+        runExport();
+        return;
+    }
+    if (command === "mcp") {
+        await runMcpServer();
+        return;
+    }
+    process.stderr.write("Usage:\n" +
+        "  agentlens start [--open]\n" +
+        "  agentlens mcp\n" +
+        "  agentlens export [--latest|--session <id>] [--out <path>]\n");
+    process.exitCode = 1;
+}
+main().catch((error) => {
+    process.stderr.write(`Fatal: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/store.d.ts

@@ -0,0 +1,70 @@
+import { type ActorType, type CanonicalEvent, type SessionLogFile } from "./event-envelope.js";
+export interface SessionState {
+    session_id: string;
+    goal: string;
+    user_prompt?: string;
+    repo?: string;
+    branch?: string;
+    started_at: string;
+    ended_at?: string;
+    next_seq: number;
+    active_intent_id?: string;
+}
+export interface SessionFileInfo {
+    session_id: string;
+    path: string;
+    size_bytes: number;
+    updated_at: string;
+}
+export interface NormalizedSessionSnapshot {
+    session_id: string;
+    goal: string;
+    started_at: string;
+    ended_at?: string;
+    outcome: "completed" | "partial" | "failed" | "aborted" | "unknown";
+    event_count: number;
+    intent_count: number;
+    verification: {
+        pass: number;
+        fail: number;
+        unknown: number;
+    };
+    files_touched: string[];
+    kinds: Record<string, number>;
+}
+export declare function createSession(input: {
+    goal: string;
+    user_prompt?: string;
+    repo?: string;
+    branch?: string;
+}): SessionState;
+export declare function getActiveSession(): SessionState | undefined;
+export declare function ensureActiveSession(): SessionState;
+export declare function setActiveIntent(intentId: string): void;
+export interface CreateEventInput {
+    session_id: string;
+    kind: string;
+    actor: {
+        type: ActorType;
+        id?: string;
+    };
+    payload: Record<string, unknown>;
+    ts?: string;
+    scope?: {
+        intent_id?: string;
+        file?: string;
+        module?: string;
+    };
+    derived?: boolean;
+    confidence?: number;
+    visibility?: "raw" | "review" | "debug";
+}
+export declare function createEvent(state: SessionState, input: CreateEventInput): CanonicalEvent;
+export declare function persistEvent(event: CanonicalEvent): Promise<void>;
+export declare function readSessionEvents(sessionId: string): CanonicalEvent[];
+export declare function persistNormalizedSnapshot(session: SessionState): Promise<NormalizedSessionSnapshot>;
+export declare function listSessionFiles(): SessionFileInfo[];
+export declare function exportSessionJson(sessionId: string): string;
+export declare function endActiveSession(endedAt?: string): Promise<SessionState>;
+export declare function buildSessionLog(state: SessionState, events: CanonicalEvent[]): SessionLogFile;
+export declare function initializeSessionLog(state: SessionState): void;

package/dist/store.js

@@ -0,0 +1,254 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getSessionsDir } from "./config.js";
+import { EVENT_SCHEMA_VERSION, } from "./event-envelope.js";
+const sessionStates = new Map();
+let activeSessionId;
+let writeQueue = Promise.resolve();
+function withWriteLock(fn) {
+    const run = writeQueue.then(fn, fn);
+    writeQueue = run.then(() => undefined, () => undefined);
+    return run;
+}
+function safeFilename(input) {
+    return input.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+function getSessionLogPath(sessionId) {
+    const outDir = getSessionsDir();
+    if (!existsSync(outDir))
+        mkdirSync(outDir, { recursive: true });
+    return join(outDir, `${safeFilename(sessionId)}.jsonl`);
+}
+function getSessionSnapshotPath(sessionId) {
+    const outDir = getSessionsDir();
+    if (!existsSync(outDir))
+        mkdirSync(outDir, { recursive: true });
+    return join(outDir, `${safeFilename(sessionId)}.session.json`);
+}
+function toCanonicalTs(rawTs) {
+    if (!rawTs)
+        return new Date().toISOString();
+    const parsed = new Date(rawTs);
+    if (Number.isNaN(parsed.getTime()))
+        throw new Error(`Invalid timestamp: ${rawTs}`);
+    return parsed.toISOString();
+}
+function assertConfidence(confidence) {
+    if (confidence === undefined)
+        return;
+    if (Number.isNaN(confidence) || confidence < 0 || confidence > 1) {
+        throw new Error("confidence must be a number between 0 and 1");
+    }
+}
+export function createSession(input) {
+    const startedAt = new Date().toISOString();
+    const sessionId = `sess_${Date.now()}_${randomUUID().slice(0, 8)}`;
+    const state = {
+        session_id: sessionId,
+        goal: input.goal,
+        user_prompt: input.user_prompt,
+        repo: input.repo,
+        branch: input.branch,
+        started_at: startedAt,
+        next_seq: 1,
+    };
+    sessionStates.set(sessionId, state);
+    activeSessionId = sessionId;
+    return state;
+}
+export function getActiveSession() {
+    if (!activeSessionId)
+        return undefined;
+    return sessionStates.get(activeSessionId);
+}
+export function ensureActiveSession() {
+    const active = getActiveSession();
+    if (!active) {
+        throw new Error("No active session. Call record_session_start first.");
+    }
+    if (active.ended_at) {
+        throw new Error("Active session has ended. Call record_session_start to begin a new one.");
+    }
+    return active;
+}
+export function setActiveIntent(intentId) {
+    const s = ensureActiveSession();
+    s.active_intent_id = intentId;
+}
+export function createEvent(state, input) {
+    const seq = state.next_seq;
+    state.next_seq += 1;
+    const ts = toCanonicalTs(input.ts);
+    assertConfidence(input.confidence);
+    return {
+        id: `${state.session_id}:${seq}:${randomUUID().slice(0, 8)}`,
+        session_id: input.session_id,
+        seq,
+        ts,
+        kind: input.kind,
+        actor: input.actor,
+        scope: input.scope,
+        payload: input.payload,
+        derived: input.derived,
+        confidence: input.confidence,
+        visibility: input.visibility,
+        schema_version: EVENT_SCHEMA_VERSION,
+    };
+}
+export async function persistEvent(event) {
+    await withWriteLock(() => {
+        const path = getSessionLogPath(event.session_id);
+        appendFileSync(path, JSON.stringify(event) + "\n", "utf-8");
+    });
+}
+export function readSessionEvents(sessionId) {
+    const path = getSessionLogPath(sessionId);
+    if (!existsSync(path))
+        return [];
+    const content = readFileSync(path, "utf-8").trim();
+    if (!content)
+        return [];
+    const lines = content
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const events = lines.map((line, index) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`Invalid JSONL in ${path} at line ${index + 1}`);
+        }
+        if (!parsed || typeof parsed !== "object") {
+            throw new Error(`Invalid event object in ${path} at line ${index + 1}`);
+        }
+        return parsed;
+    });
+    return events.sort((a, b) => (a.seq === b.seq ? a.ts.localeCompare(b.ts) : a.seq - b.seq));
+}
+function deriveSnapshot(session, events) {
+    const kinds = {};
+    let pass = 0;
+    let fail = 0;
+    let unknown = 0;
+    const files = new Set();
+    let intentCount = 0;
+    for (const event of events) {
+        kinds[event.kind] = (kinds[event.kind] ?? 0) + 1;
+        if (event.kind === "intent")
+            intentCount += 1;
+        if (event.kind === "file_op") {
+            const target = typeof event.payload.target === "string"
+                ? event.payload.target
+                : event.scope?.file;
+            if (target && target.trim() !== "")
+                files.add(target);
+        }
+        if (event.kind === "verification") {
+            const result = event.payload.result;
+            if (result === "pass")
+                pass += 1;
+            else if (result === "fail")
+                fail += 1;
+            else
+                unknown += 1;
+        }
+    }
+    const end = [...events].reverse().find((event) => event.kind === "session_end");
+    const outcomeRaw = end?.payload?.outcome;
+    const outcome = outcomeRaw === "completed" || outcomeRaw === "partial" || outcomeRaw === "failed" || outcomeRaw === "aborted"
+        ? outcomeRaw
+        : "unknown";
+    return {
+        session_id: session.session_id,
+        goal: session.goal,
+        started_at: session.started_at,
+        ended_at: session.ended_at,
+        outcome,
+        event_count: events.length,
+        intent_count: intentCount,
+        verification: { pass, fail, unknown },
+        files_touched: [...files].sort(),
+        kinds,
+    };
+}
+export async function persistNormalizedSnapshot(session) {
+    const events = readSessionEvents(session.session_id);
+    const snapshot = deriveSnapshot(session, events);
+    await withWriteLock(() => {
+        const path = getSessionSnapshotPath(session.session_id);
+        writeFileSync(path, JSON.stringify(snapshot, null, 2), "utf-8");
+    });
+    return snapshot;
+}
+export function listSessionFiles() {
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter((name) => name.endsWith(".jsonl"));
+    const out = files.map((name) => {
+        const path = join(dir, name);
+        const stats = statSync(path);
+        const session_id = name.replace(/\.jsonl$/, "");
+        return {
+            session_id,
+            path,
+            size_bytes: stats.size,
+            updated_at: stats.mtime.toISOString(),
+        };
+    });
+    out.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+    return out;
+}
+export function exportSessionJson(sessionId) {
+    const state = sessionStates.get(sessionId);
+    const events = readSessionEvents(sessionId);
+    if (events.length === 0)
+        throw new Error(`No events found for session: ${sessionId}`);
+    const firstStart = events.find((event) => event.kind === "session_start");
+    const startPayload = (firstStart?.payload ?? {});
+    const inferredState = state ?? {
+        session_id: sessionId,
+        goal: typeof startPayload.goal === "string" ? startPayload.goal : "Unknown goal",
+        user_prompt: typeof startPayload.user_prompt === "string" ? startPayload.user_prompt : undefined,
+        repo: typeof startPayload.repo === "string" ? startPayload.repo : undefined,
+        branch: typeof startPayload.branch === "string" ? startPayload.branch : undefined,
+        started_at: firstStart?.ts ?? events[0].ts,
+        ended_at: [...events].reverse().find((event) => event.kind === "session_end")?.ts,
+        next_seq: (events[events.length - 1]?.seq ?? 0) + 1,
+    };
+    const snapshot = deriveSnapshot(inferredState, events);
+    return JSON.stringify({
+        ...buildSessionLog(inferredState, events),
+        normalized: snapshot,
+    }, null, 2);
+}
+export async function endActiveSession(endedAt) {
+    const state = ensureActiveSession();
+    state.ended_at = toCanonicalTs(endedAt);
+    await withWriteLock(() => undefined);
+    if (activeSessionId === state.session_id) {
+        activeSessionId = undefined;
+    }
+    return state;
+}
+export function buildSessionLog(state, events) {
+    return {
+        session_id: state.session_id,
+        goal: state.goal,
+        user_prompt: state.user_prompt,
+        repo: state.repo,
+        branch: state.branch,
+        started_at: state.started_at,
+        ended_at: state.ended_at,
+        events,
+    };
+}
+export function initializeSessionLog(state) {
+    const path = getSessionLogPath(state.session_id);
+    if (existsSync(path))
+        return;
+    writeFileSync(path, "", "utf-8");
+}