al-sem 0.0.1

package/src/mcp/server.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+// src/mcp/server.ts
+//
+// MCP server for al-sem. Exposes progressive-disclosure tools (list_findings, get_finding,
+// list_hotspots, get_routine_summary, explain_path, get_analysis_health) over stdio.
+//
+// All tools sit on top of the projection layer — they never return the full SemanticModel
+// or raw evidencePath unless explicitly requested via the get_finding / explain_path tools.
+
+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 { explainPathTool } from "./tools/explain-path.ts";
+import { getAnalysisHealthTool } from "./tools/get-analysis-health.ts";
+import { getFindingTool } from "./tools/get-finding.ts";
+import { getRoutineSummaryTool } from "./tools/get-routine-summary.ts";
+import { listFindingsTool } from "./tools/list-findings.ts";
+import { listHotspotsTool } from "./tools/list-hotspots.ts";
+import { listRollupsTool } from "./tools/list-rollups.ts";
+
+export interface McpTool {
+	definition: {
+		name: string;
+		description: string;
+		inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] };
+	};
+	handle(
+		args: Record<string, unknown>,
+	): Promise<{ content: Array<{ type: "text"; text: string }> }>;
+}
+
+/** Build the server, register the given tools. Returns the un-connected Server instance. */
+export function buildServer(tools: McpTool[]): Server {
+	const server = new Server({ name: "al-sem", version: "0.0.1" }, { capabilities: { tools: {} } });
+
+	server.setRequestHandler(ListToolsRequestSchema, async () => ({
+		tools: tools.map((t) => t.definition),
+	}));
+
+	server.setRequestHandler(CallToolRequestSchema, async (req) => {
+		const tool = tools.find((t) => t.definition.name === req.params.name);
+		if (tool === undefined) {
+			return {
+				content: [{ type: "text" as const, text: `unknown tool: ${req.params.name}` }],
+				isError: true,
+			};
+		}
+		return tool.handle((req.params.arguments as Record<string, unknown>) ?? {});
+	});
+
+	return server;
+}
+
+/** Main entrypoint: build a server with registered tools, connect over stdio. */
+async function main(): Promise<void> {
+	const server = buildServer([
+		listFindingsTool,
+		listRollupsTool,
+		getFindingTool,
+		listHotspotsTool,
+		getRoutineSummaryTool,
+		explainPathTool,
+		getAnalysisHealthTool,
+	]);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+// Run only when invoked directly (not when imported in tests).
+if (import.meta.main) {
+	void main();
+}

package/src/mcp/session.ts

@@ -0,0 +1,49 @@
+// src/mcp/session.ts
+//
+// Per-session analyzeWorkspace cache + pre-projected findings.
+// One cache entry per (workspaceRoot, alpackagesDir) tuple, keyed by their concatenation.
+// The server holds these for the lifetime of the MCP session; analyze is run lazily on
+// the first request that touches a given workspace.
+
+import { type AnalyzeWorkspaceResult, analyzeWorkspace } from "../index.ts";
+import { type FindingSummary, projectFinding } from "../projection/finding-summary.ts";
+
+export interface SessionEntry {
+	key: string;
+	workspaceRoot: string;
+	alpackagesDir?: string;
+	result: AnalyzeWorkspaceResult;
+	/** Pre-projected (compact) findings for fast list_findings / filter / group queries. */
+	findings: FindingSummary[];
+	/** Index by Finding.id for get_finding. */
+	findingsById: Map<string, FindingSummary>;
+}
+
+const sessions = new Map<string, SessionEntry>();
+
+/** Look up a cached session entry or analyze + cache. Deterministic by construction. */
+export async function getSession(
+	workspaceRoot: string,
+	alpackagesDir?: string,
+): Promise<SessionEntry> {
+	const key = `${workspaceRoot}|${alpackagesDir ?? ""}`;
+	const cached = sessions.get(key);
+	if (cached) return cached;
+	const result = await analyzeWorkspace({ workspaceRoot, alpackagesDir, deterministic: true });
+	const findings = result.findings.map((f) => projectFinding(f, result.model));
+	const entry: SessionEntry = {
+		key,
+		workspaceRoot,
+		alpackagesDir,
+		result,
+		findings,
+		findingsById: new Map(findings.map((f) => [f.id, f])),
+	};
+	sessions.set(key, entry);
+	return entry;
+}
+
+/** Clear all cached sessions. Test-only helper. */
+export function clearSessions(): void {
+	sessions.clear();
+}

package/src/mcp/tools/explain-path.ts

@@ -0,0 +1,75 @@
+// src/mcp/tools/explain-path.ts
+
+import type { EvidenceStep } from "../../model/finding.ts";
+import type { McpTool } from "../server.ts";
+import { getSession } from "../session.ts";
+
+/**
+ * explain_path — enrich a finding's evidencePath with object/routine names and file:line:col.
+ * Designed for agent "why was this flagged?" walkthroughs.
+ */
+export const explainPathTool: McpTool = {
+	definition: {
+		name: "explain_path",
+		description:
+			"For a finding id, return its evidencePath where every step is enriched with object/routine name and file:line:col. Use to walk an agent through 'why this was flagged'.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				workspaceRoot: { type: "string" },
+				alpackagesDir: { type: "string" },
+				findingId: { type: "string" },
+			},
+			required: ["workspaceRoot", "findingId"],
+		},
+	},
+	async handle(args) {
+		const workspaceRoot = args.workspaceRoot;
+		const findingId = args.findingId;
+		if (typeof workspaceRoot !== "string") {
+			return { content: [{ type: "text", text: "explain_path: workspaceRoot is required" }] };
+		}
+		if (typeof findingId !== "string") {
+			return { content: [{ type: "text", text: "explain_path: findingId is required" }] };
+		}
+		const session = await getSession(
+			workspaceRoot,
+			typeof args.alpackagesDir === "string" ? args.alpackagesDir : undefined,
+		);
+		const finding = session.result.findings.find((f) => f.id === findingId);
+		if (finding === undefined) {
+			return {
+				content: [{ type: "text", text: `explain_path: no finding with id '${findingId}'` }],
+			};
+		}
+
+		const routinesById = new Map(session.result.model.routines.map((r) => [r.id, r]));
+		const objectsById = new Map(session.result.model.objects.map((o) => [o.id, o]));
+
+		const enrich = (step: EvidenceStep): Record<string, unknown> => {
+			const routine = routinesById.get(step.routineId);
+			const object = routine ? objectsById.get(routine.objectId) : undefined;
+			return {
+				routineId: step.routineId,
+				routineName: routine?.name,
+				objectId: routine?.objectId,
+				objectName: object?.name,
+				operationId: step.operationId,
+				callsiteId: step.callsiteId,
+				loopId: step.loopId,
+				file: step.sourceAnchor.sourceUnitId,
+				line: step.sourceAnchor.range.startLine + 1,
+				column: step.sourceAnchor.range.startColumn + 1,
+				note: step.note,
+			};
+		};
+
+		const payload = {
+			findingId: finding.id,
+			detector: finding.detector,
+			title: finding.title,
+			steps: finding.evidencePath.map(enrich),
+		};
+		return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+	},
+};

package/src/mcp/tools/get-analysis-health.ts

@@ -0,0 +1,62 @@
+// src/mcp/tools/get-analysis-health.ts
+
+import type { McpTool } from "../server.ts";
+import { getSession } from "../session.ts";
+
+export const getAnalysisHealthTool: McpTool = {
+	definition: {
+		name: "get_analysis_health",
+		description:
+			"Return coverage stats, diagnostic categories, and per-detector stats. Use to decide how trustworthy the analysis is before relying on findings.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				workspaceRoot: { type: "string" },
+				alpackagesDir: { type: "string" },
+			},
+			required: ["workspaceRoot"],
+		},
+	},
+	async handle(args) {
+		const workspaceRoot = args.workspaceRoot;
+		if (typeof workspaceRoot !== "string") {
+			return {
+				content: [{ type: "text", text: "get_analysis_health: workspaceRoot is required" }],
+			};
+		}
+		const session = await getSession(
+			workspaceRoot,
+			typeof args.alpackagesDir === "string" ? args.alpackagesDir : undefined,
+		);
+		const cov = session.result.model.coverage;
+
+		// diagnostic categories — bucket by severity + stage
+		const byStage: Record<string, number> = {};
+		const bySeverity: Record<string, number> = {};
+		for (const d of session.result.diagnostics) {
+			byStage[d.stage] = (byStage[d.stage] ?? 0) + 1;
+			bySeverity[d.severity] = (bySeverity[d.severity] ?? 0) + 1;
+		}
+
+		const health = {
+			coverage: {
+				sourceUnitsTotal: cov.sourceUnitsTotal,
+				sourceUnitsParsed: cov.sourceUnitsParsed,
+				routinesTotal: cov.routinesTotal,
+				routinesBodyAvailable: cov.routinesBodyAvailable,
+				routinesParseIncompleteCount: cov.routinesParseIncomplete.length,
+				opaqueApps: cov.opaqueApps,
+				unresolvedCallsiteCount: cov.unresolvedCallsites.length,
+				dynamicDispatchSiteCount: cov.dynamicDispatchSites.length,
+			},
+			diagnostics: {
+				total: session.result.diagnostics.length,
+				byStage,
+				bySeverity,
+			},
+			detectorStats: session.result.detectorStats,
+			findingsTotal: session.findings.length,
+		};
+		return { content: [{ type: "text", text: JSON.stringify(health, null, 2) }] };
+	},
+};

package/src/mcp/tools/get-finding.ts

@@ -0,0 +1,47 @@
+// src/mcp/tools/get-finding.ts
+
+import type { McpTool } from "../server.ts";
+import { getSession } from "../session.ts";
+
+/**
+ * get_finding — return the full Finding for a single id, including evidencePath,
+ * primaryLocation, actionableAnchor, fingerprint, and provenance.
+ * Use list_findings first to discover ids.
+ */
+export const getFindingTool: McpTool = {
+	definition: {
+		name: "get_finding",
+		description:
+			"Return the full Finding for a single id, including evidencePath, primaryLocation, actionableAnchor, fingerprint, and provenance. Use list_findings first to discover ids.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				workspaceRoot: { type: "string", description: "Absolute path to the AL workspace root." },
+				alpackagesDir: { type: "string", description: "Optional explicit .alpackages path." },
+				findingId: { type: "string", description: "The Finding.id returned by list_findings." },
+			},
+			required: ["workspaceRoot", "findingId"],
+		},
+	},
+	async handle(args) {
+		const workspaceRoot = args.workspaceRoot;
+		const findingId = args.findingId;
+		if (typeof workspaceRoot !== "string") {
+			return { content: [{ type: "text", text: "get_finding: workspaceRoot is required" }] };
+		}
+		if (typeof findingId !== "string") {
+			return { content: [{ type: "text", text: "get_finding: findingId is required" }] };
+		}
+		const session = await getSession(
+			workspaceRoot,
+			typeof args.alpackagesDir === "string" ? args.alpackagesDir : undefined,
+		);
+		const finding = session.result.findings.find((f) => f.id === findingId);
+		if (finding === undefined) {
+			return {
+				content: [{ type: "text", text: `get_finding: no finding with id '${findingId}'` }],
+			};
+		}
+		return { content: [{ type: "text", text: JSON.stringify(finding, null, 2) }] };
+	},
+};

package/src/mcp/tools/get-routine-summary.ts

@@ -0,0 +1,126 @@
+// src/mcp/tools/get-routine-summary.ts
+
+import {
+	mayCommit,
+	publishesEventsOf,
+	reachableCoverage,
+	touchesDbOf,
+	writesTablesOf,
+} from "../../detectors/capability-query.ts";
+import { roleOf } from "../../model/entities.ts";
+import type { Routine } from "../../model/entities.ts";
+import type { McpTool } from "../server.ts";
+import { getSession } from "../session.ts";
+
+function project(routine: Routine, objectName: string | undefined) {
+	return {
+		id: routine.id,
+		name: routine.name,
+		objectId: routine.objectId,
+		objectName,
+		analysisRole: roleOf(routine),
+		kind: routine.kind,
+		bodyAvailable: routine.bodyAvailable,
+		parseIncomplete: routine.parseIncomplete,
+		loops: {
+			count: routine.features.loops.length,
+			types: routine.features.loops.map((l) => l.type),
+		},
+		recordOperations: routine.features.recordOperations.map((op) => ({
+			op: op.op,
+			tableId: op.tableId,
+			inLoop: op.loopStack.length > 0,
+			loopDepth: op.loopStack.length,
+			tempState: op.tempState,
+		})),
+		callSites: routine.features.callSites.map((cs) => ({
+			calleeText: cs.calleeText,
+			inLoop: cs.loopStack.length > 0,
+		})),
+		summary: routine.summary
+			? {
+					touchesDb: touchesDbOf(routine.summary),
+					commits: mayCommit(routine.summary),
+					writesTables: writesTablesOf(routine.summary),
+					publishesEvents: publishesEventsOf(routine.summary),
+					coverage: reachableCoverage(routine.summary),
+					dbEffects: routine.summary.dbEffects,
+					parameterRoles: routine.summary.parameterRoles,
+				}
+			: undefined,
+	};
+}
+
+export const getRoutineSummaryTool: McpTool = {
+	definition: {
+		name: "get_routine_summary",
+		description:
+			"Project a single routine into a compact view: role, loops, recordOperations, callSites, and the L4 summary (touchesDb, commits, writesTables, publishesEvents, coverage, dbEffects, parameterRoles). Specify by routineId, by objectId+routineName, or by sourceLocation { file, line }.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				workspaceRoot: { type: "string" },
+				alpackagesDir: { type: "string" },
+				routineId: { type: "string" },
+				objectId: { type: "string" },
+				routineName: { type: "string" },
+				sourceLocation: {
+					type: "object",
+					properties: { file: { type: "string" }, line: { type: "integer" } },
+				},
+			},
+			required: ["workspaceRoot"],
+		},
+	},
+	async handle(args) {
+		const workspaceRoot = args.workspaceRoot;
+		if (typeof workspaceRoot !== "string") {
+			return {
+				content: [{ type: "text", text: "get_routine_summary: workspaceRoot is required" }],
+			};
+		}
+		const session = await getSession(
+			workspaceRoot,
+			typeof args.alpackagesDir === "string" ? args.alpackagesDir : undefined,
+		);
+		const objectsById = new Map(session.result.model.objects.map((o) => [o.id, o]));
+
+		let routine: Routine | undefined;
+		if (typeof args.routineId === "string") {
+			routine = session.result.model.routines.find((r) => r.id === args.routineId);
+		} else if (typeof args.objectId === "string" && typeof args.routineName === "string") {
+			const objId = args.objectId;
+			const rname = args.routineName;
+			routine = session.result.model.routines.find((r) => r.objectId === objId && r.name === rname);
+		} else if (args.sourceLocation !== undefined && typeof args.sourceLocation === "object") {
+			const loc = args.sourceLocation as { file?: unknown; line?: unknown };
+			if (typeof loc.file === "string" && typeof loc.line === "number") {
+				const wantFile = loc.file;
+				const wantLine = loc.line - 1; // input is 1-based; SourceAnchor is 0-based
+				routine = session.result.model.routines.find(
+					(r) =>
+						r.sourceAnchor.sourceUnitId === wantFile &&
+						r.sourceAnchor.range.startLine <= wantLine &&
+						wantLine <= r.sourceAnchor.range.endLine,
+				);
+			}
+		} else {
+			return {
+				content: [
+					{
+						type: "text",
+						text: "get_routine_summary: specify routineId, objectId+routineName, or sourceLocation",
+					},
+				],
+			};
+		}
+
+		if (routine === undefined) {
+			return { content: [{ type: "text", text: "get_routine_summary: routine not found" }] };
+		}
+		const obj = objectsById.get(routine.objectId);
+		return {
+			content: [{ type: "text", text: JSON.stringify(project(routine, obj?.name), null, 2) }],
+		};
+	},
+};

package/src/mcp/tools/list-findings.ts

@@ -0,0 +1,85 @@
+// src/mcp/tools/list-findings.ts
+
+import { filterFindings } from "../../projection/finding-filters.ts";
+import type { McpTool } from "../server.ts";
+import { getSession } from "../session.ts";
+import { validateMinSeverity } from "./validators.ts";
+
+/**
+ * list_findings — paged, filtered list of compact FindingSummary[] for a workspace.
+ * Designed for agent progressive disclosure: agents call this first, then get_finding
+ * for evidence on a specific id.
+ */
+export const listFindingsTool: McpTool = {
+	definition: {
+		name: "list_findings",
+		description:
+			"List analysis findings for an AL workspace, filtered and paged. Returns compact FindingSummary[]. Call get_finding(findingId) for the evidence path of a specific finding.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				workspaceRoot: { type: "string", description: "Absolute path to the AL workspace root." },
+				alpackagesDir: { type: "string", description: "Optional explicit .alpackages path." },
+				minSeverity: {
+					type: "string",
+					enum: ["critical", "high", "medium", "low", "info"],
+					description: "Drop findings below this severity.",
+				},
+				detectors: {
+					type: "array",
+					items: { type: "string" },
+					description: "Allow-list of detector ids.",
+				},
+				objectIds: { type: "array", items: { type: "string" } },
+				tableIds: { type: "array", items: { type: "string" } },
+				files: {
+					type: "array",
+					items: { type: "string" },
+					description: "Match by file path suffix.",
+				},
+				limit: { type: "integer", minimum: 1 },
+			},
+			required: ["workspaceRoot"],
+		},
+	},
+	async handle(args) {
+		const workspaceRoot = args.workspaceRoot;
+		if (typeof workspaceRoot !== "string") {
+			return {
+				content: [
+					{ type: "text", text: "list_findings: workspaceRoot is required and must be a string" },
+				],
+			};
+		}
+		const sev = validateMinSeverity(args.minSeverity, "list_findings");
+		if (!sev.ok) return { content: [{ type: "text", text: sev.error }] };
+		const session = await getSession(
+			workspaceRoot,
+			typeof args.alpackagesDir === "string" ? args.alpackagesDir : undefined,
+		);
+		const filtered = filterFindings(session.findings, {
+			minSeverity: sev.value,
+			detectors: Array.isArray(args.detectors) ? (args.detectors as string[]) : undefined,
+			objectIds: Array.isArray(args.objectIds) ? (args.objectIds as string[]) : undefined,
+			tableIds: Array.isArray(args.tableIds) ? (args.tableIds as string[]) : undefined,
+			files: Array.isArray(args.files) ? (args.files as string[]) : undefined,
+			limit: typeof args.limit === "number" ? args.limit : undefined,
+		});
+		return {
+			content: [
+				{
+					type: "text",
+					text: JSON.stringify(
+						{
+							findings: filtered,
+							total: filtered.length,
+							totalUnfiltered: session.findings.length,
+						},
+						null,
+						2,
+					),
+				},
+			],
+		};
+	},
+};

package/src/mcp/tools/list-hotspots.ts

@@ -0,0 +1,78 @@
+// src/mcp/tools/list-hotspots.ts
+
+import { filterFindings } from "../../projection/finding-filters.ts";
+import { type GroupBy, groupFindings } from "../../projection/finding-groups.ts";
+import type { McpTool } from "../server.ts";
+import { getSession } from "../session.ts";
+import { validateMinSeverity } from "./validators.ts";
+
+const VALID_GROUP_BY: ReadonlyArray<GroupBy> = ["object", "routine", "table", "detector", "file"];
+
+export const listHotspotsTool: McpTool = {
+	definition: {
+		name: "list_hotspots",
+		description:
+			"Group findings (object / routine / table / detector / file) and return the top-N groups with counts. Use to surface the highest-leverage places to look first.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				workspaceRoot: { type: "string" },
+				alpackagesDir: { type: "string" },
+				groupBy: {
+					type: "string",
+					enum: ["object", "routine", "table", "detector", "file"],
+					description: "Which dimension to group by.",
+				},
+				minSeverity: {
+					type: "string",
+					enum: ["critical", "high", "medium", "low", "info"],
+					description: "Drop findings below this severity before grouping.",
+				},
+				limit: { type: "integer", minimum: 1, description: "Top-N group cap." },
+			},
+			required: ["workspaceRoot", "groupBy"],
+		},
+	},
+	async handle(args) {
+		const workspaceRoot = args.workspaceRoot;
+		const groupByArg = args.groupBy;
+		if (typeof workspaceRoot !== "string") {
+			return { content: [{ type: "text", text: "list_hotspots: workspaceRoot is required" }] };
+		}
+		if (typeof groupByArg !== "string" || !VALID_GROUP_BY.includes(groupByArg as GroupBy)) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `list_hotspots: groupBy must be one of: ${VALID_GROUP_BY.join(", ")}`,
+					},
+				],
+			};
+		}
+		const groupBy = groupByArg as GroupBy;
+		const sev = validateMinSeverity(args.minSeverity, "list_hotspots");
+		if (!sev.ok) return { content: [{ type: "text", text: sev.error }] };
+
+		const session = await getSession(
+			workspaceRoot,
+			typeof args.alpackagesDir === "string" ? args.alpackagesDir : undefined,
+		);
+		const filtered = filterFindings(session.findings, {
+			minSeverity: sev.value,
+		});
+		const groups = groupFindings(filtered, groupBy);
+		const limit = typeof args.limit === "number" ? args.limit : groups.length;
+		const top = groups.slice(0, limit);
+		const result = {
+			groupBy,
+			total: groups.length,
+			returned: top.length,
+			groups: top.map((g) => ({
+				key: g.key,
+				count: g.findings.length,
+				findingIds: g.findings.map((f) => f.id),
+			})),
+		};
+		return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+	},
+};