@ai-sdlc/mcp-advisor 0.1.0

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createMcpServer } from './server.js';
+const { server } = await createMcpServer();
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=bin.js.map

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { createMcpServer, type CreateServerOptions } from './server.js';
+export { SessionManager, type SessionState, type IssueLinkMethod, type UsageEntry, type AccumulatedCost, type CreateSessionOpts, } from './session.js';
+export { resolveIssue, type IssueResolution } from './issue-linker.js';
+export type { ServerDeps } from './types.js';
+export type { McpAdvisorPlugin } from './plugin.js';
+export { handleSessionStart } from './tools/session-start.js';
+export { handleGetContext } from './tools/get-context.js';
+export { handleCheckTask } from './tools/check-task.js';
+export { handleTrackUsage } from './tools/track-usage.js';
+export { handleCheckFile } from './tools/check-file.js';
+export { handleSessionEnd } from './tools/session-end.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,14 @@
+// Server factory
+export { createMcpServer } from './server.js';
+// Session management
+export { SessionManager, } from './session.js';
+// Issue linker
+export { resolveIssue } from './issue-linker.js';
+// Tool handlers (for direct testing / programmatic use)
+export { handleSessionStart } from './tools/session-start.js';
+export { handleGetContext } from './tools/get-context.js';
+export { handleCheckTask } from './tools/check-task.js';
+export { handleTrackUsage } from './tools/track-usage.js';
+export { handleCheckFile } from './tools/check-file.js';
+export { handleSessionEnd } from './tools/session-end.js';
+//# sourceMappingURL=index.js.map

package/dist/issue-linker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 4-tier issue resolution chain.
+ * Attempts to link a session to an issue number via:
+ *   1. Branch name pattern
+ *   2. Explicit declaration
+ *   3. Git log context
+ *   4. Unattributed fallback
+ */
+import type { IssueLinkMethod } from './session.js';
+export interface IssueResolution {
+    issueNumber: number | null;
+    method: IssueLinkMethod;
+    confidence: number;
+}
+/**
+ * Resolve issue number through the 4-tier chain.
+ */
+export declare function resolveIssue(repoPath: string, explicitIssue?: number): Promise<IssueResolution>;
+//# sourceMappingURL=issue-linker.d.ts.map

package/dist/issue-linker.js

@@ -0,0 +1,93 @@
+/**
+ * 4-tier issue resolution chain.
+ * Attempts to link a session to an issue number via:
+ *   1. Branch name pattern
+ *   2. Explicit declaration
+ *   3. Git log context
+ *   4. Unattributed fallback
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { extractIssueNumber } from '@ai-sdlc/orchestrator';
+const execFileAsync = promisify(execFile);
+/** Loose pattern for branch names like `issue-42`, `issue_42`, `issue#42`. */
+const LOOSE_BRANCH_PATTERN = /issue[- _]?#?(\d+)/i;
+/** Pattern for `#N` or `fixes #N` in commit messages. */
+const COMMIT_ISSUE_PATTERN = /(?:fix(?:es|ed)?|close[sd]?|resolve[sd]?)\s+#(\d+)|#(\d+)/gi;
+/**
+ * Resolve the current git branch name.
+ */
+async function getCurrentBranch(repoPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd: repoPath,
+        });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse recent git log for issue references.
+ */
+async function getIssueFromGitLog(repoPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['log', '--oneline', '-20'], { cwd: repoPath });
+        const counts = new Map();
+        for (const line of stdout.split('\n')) {
+            let match;
+            COMMIT_ISSUE_PATTERN.lastIndex = 0;
+            while ((match = COMMIT_ISSUE_PATTERN.exec(line)) !== null) {
+                const num = parseInt(match[1] ?? match[2], 10);
+                if (!isNaN(num)) {
+                    counts.set(num, (counts.get(num) ?? 0) + 1);
+                }
+            }
+        }
+        if (counts.size === 0)
+            return null;
+        // Return the most frequently referenced issue
+        let best = null;
+        let bestCount = 0;
+        for (const [num, count] of counts) {
+            if (count > bestCount) {
+                best = num;
+                bestCount = count;
+            }
+        }
+        return best;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve issue number through the 4-tier chain.
+ */
+export async function resolveIssue(repoPath, explicitIssue) {
+    // Tier 1: Branch name
+    const branch = await getCurrentBranch(repoPath);
+    if (branch) {
+        const strict = extractIssueNumber(branch);
+        if (strict !== null) {
+            return { issueNumber: strict, method: 'branch', confidence: 1.0 };
+        }
+        const loose = branch.match(LOOSE_BRANCH_PATTERN);
+        if (loose) {
+            return { issueNumber: parseInt(loose[1], 10), method: 'branch', confidence: 0.8 };
+        }
+    }
+    // Tier 2: Explicit declaration
+    if (explicitIssue != null) {
+        return { issueNumber: explicitIssue, method: 'explicit', confidence: 1.0 };
+    }
+    // Tier 3: Git context
+    const gitIssue = await getIssueFromGitLog(repoPath);
+    if (gitIssue !== null) {
+        return { issueNumber: gitIssue, method: 'git-context', confidence: 0.6 };
+    }
+    // Tier 4: Unattributed
+    return { issueNumber: null, method: 'unattributed', confidence: 0 };
+}
+//# sourceMappingURL=issue-linker.js.map

package/dist/plugin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP advisor plugin interface — extension point for custom tools/resources.
+ *
+ * Plugins register additional tools and resources on the MCP server,
+ * following the same (server, deps) pattern used by built-in registrations.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from './types.js';
+export interface McpAdvisorPlugin {
+    name: string;
+    register(server: McpServer, deps: ServerDeps): void | Promise<void>;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.js

@@ -0,0 +1,8 @@
+/**
+ * MCP advisor plugin interface — extension point for custom tools/resources.
+ *
+ * Plugins register additional tools and resources on the MCP server,
+ * following the same (server, deps) pattern used by built-in registrations.
+ */
+export {};
+//# sourceMappingURL=plugin.js.map

package/dist/resources/budget.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export declare function registerBudgetResource(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=budget.d.ts.map

package/dist/resources/budget.js

@@ -0,0 +1,17 @@
+export function registerBudgetResource(server, deps) {
+    server.resource('budget', 'ai-sdlc://context/budget', { description: 'Current cost budget status and per-agent breakdown' }, async () => {
+        const budgetStatus = deps.costTracker.getBudgetStatus();
+        const costByAgent = deps.costTracker.getCostByAgent();
+        const data = { budgetStatus, costByAgent };
+        return {
+            contents: [
+                {
+                    uri: 'ai-sdlc://context/budget',
+                    text: JSON.stringify(data, null, 2),
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=budget.js.map

package/dist/resources/codebase-profile.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export declare function registerCodebaseProfileResource(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=codebase-profile.d.ts.map

package/dist/resources/codebase-profile.js

@@ -0,0 +1,18 @@
+export function registerCodebaseProfileResource(server, deps) {
+    server.resource('codebase-profile', 'ai-sdlc://context/codebase-profile', {
+        description: 'Latest codebase complexity profile including score, modules, patterns, and hotspots',
+    }, async () => {
+        const profile = deps.store.getLatestComplexityProfile(deps.repoPath);
+        const data = profile ?? { message: 'No codebase profile available. Run analysis first.' };
+        return {
+            contents: [
+                {
+                    uri: 'ai-sdlc://context/codebase-profile',
+                    text: JSON.stringify(data, null, 2),
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=codebase-profile.js.map

package/dist/resources/conventions.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export declare function registerConventionsResource(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=conventions.d.ts.map

package/dist/resources/conventions.js

@@ -0,0 +1,15 @@
+export function registerConventionsResource(server, deps) {
+    server.resource('conventions', 'ai-sdlc://context/conventions', { description: 'Detected coding conventions: naming, testing, imports, structure, formatting' }, async () => {
+        const conventions = deps.store.getConventions();
+        return {
+            contents: [
+                {
+                    uri: 'ai-sdlc://context/conventions',
+                    text: JSON.stringify(conventions, null, 2),
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=conventions.js.map

package/dist/resources/history.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export declare function registerHistoryResource(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=history.d.ts.map

package/dist/resources/history.js

@@ -0,0 +1,18 @@
+import { findRelevantEpisodes } from '@ai-sdlc/orchestrator';
+export function registerHistoryResource(server, deps) {
+    server.resource('history', 'ai-sdlc://context/history', { description: 'Episodic memory relevant to the active session or recent work' }, async () => {
+        const activeSession = deps.sessions.getActive();
+        const issueNumber = activeSession?.linkedIssue ?? undefined;
+        const episodes = findRelevantEpisodes(deps.store, { issueNumber });
+        return {
+            contents: [
+                {
+                    uri: 'ai-sdlc://context/history',
+                    text: JSON.stringify(episodes, null, 2),
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=history.js.map

package/dist/resources/hotspots.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export declare function registerHotspotsResource(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=hotspots.d.ts.map

package/dist/resources/hotspots.js

@@ -0,0 +1,15 @@
+export function registerHotspotsResource(server, deps) {
+    server.resource('hotspots', 'ai-sdlc://context/hotspots', { description: 'Top file hotspots by churn rate and complexity — files that need extra care' }, async () => {
+        const hotspots = deps.store.getHotspots(deps.repoPath, 20);
+        return {
+            contents: [
+                {
+                    uri: 'ai-sdlc://context/hotspots',
+                    text: JSON.stringify(hotspots, null, 2),
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=hotspots.js.map

package/dist/resources/index.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export declare function registerAllResources(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/resources/index.js

@@ -0,0 +1,15 @@
+import { registerCodebaseProfileResource } from './codebase-profile.js';
+import { registerConventionsResource } from './conventions.js';
+import { registerHotspotsResource } from './hotspots.js';
+import { registerMyTasksResource } from './my-tasks.js';
+import { registerBudgetResource } from './budget.js';
+import { registerHistoryResource } from './history.js';
+export function registerAllResources(server, deps) {
+    registerCodebaseProfileResource(server, deps);
+    registerConventionsResource(server, deps);
+    registerHotspotsResource(server, deps);
+    registerMyTasksResource(server, deps);
+    registerBudgetResource(server, deps);
+    registerHistoryResource(server, deps);
+}
+//# sourceMappingURL=index.js.map

package/dist/resources/my-tasks.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export declare function registerMyTasksResource(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=my-tasks.d.ts.map

package/dist/resources/my-tasks.js

@@ -0,0 +1,15 @@
+export function registerMyTasksResource(server, deps) {
+    server.resource('my-tasks', 'ai-sdlc://context/my-tasks', { description: 'Recent pipeline runs and task history' }, async () => {
+        const runs = deps.store.getPipelineRuns(undefined, 50);
+        return {
+            contents: [
+                {
+                    uri: 'ai-sdlc://context/my-tasks',
+                    text: JSON.stringify(runs, null, 2),
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=my-tasks.js.map

package/dist/server.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP server factory — creates and wires the advisor server.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import Database from 'better-sqlite3';
+import type { ServerDeps } from './types.js';
+import type { McpAdvisorPlugin } from './plugin.js';
+export interface CreateServerOptions {
+    /** Path to SQLite database. Defaults to AI_SDLC_DB env var or '.ai-sdlc/state.db'. */
+    dbPath?: string;
+    /** Override database instance (for testing with :memory:). */
+    db?: InstanceType<typeof Database>;
+    /** Repository path. Defaults to cwd. */
+    repoPath?: string;
+    /** Plugins to register additional tools/resources. */
+    plugins?: McpAdvisorPlugin[];
+}
+export declare function createMcpServer(opts?: CreateServerOptions): Promise<{
+    server: McpServer;
+    deps: ServerDeps;
+}>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,32 @@
+/**
+ * MCP server factory — creates and wires the advisor server.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import Database from 'better-sqlite3';
+import { StateStore } from '@ai-sdlc/orchestrator/state';
+import { CostTracker } from '@ai-sdlc/orchestrator';
+import { SessionManager } from './session.js';
+import { registerAllTools } from './tools/index.js';
+import { registerAllResources } from './resources/index.js';
+export async function createMcpServer(opts) {
+    const db = opts?.db ?? new Database(opts?.dbPath ?? process.env['AI_SDLC_DB'] ?? '.ai-sdlc/state.db');
+    const store = StateStore.open(db);
+    const costTracker = new CostTracker(store);
+    const sessions = new SessionManager();
+    const repoPath = opts?.repoPath ?? process.cwd();
+    const deps = { store, costTracker, sessions, repoPath };
+    const server = new McpServer({
+        name: 'ai-sdlc-advisor',
+        version: '0.1.0',
+    });
+    registerAllTools(server, deps);
+    registerAllResources(server, deps);
+    // Register plugins
+    if (opts?.plugins) {
+        for (const plugin of opts.plugins) {
+            await plugin.register(server, deps);
+        }
+    }
+    return { server, deps };
+}
+//# sourceMappingURL=server.js.map

package/dist/session.d.ts

@@ -0,0 +1,49 @@
+/**
+ * In-memory session state manager.
+ * Sessions are ephemeral — one per MCP server / IDE window.
+ */
+export type IssueLinkMethod = 'branch' | 'explicit' | 'git-context' | 'unattributed';
+export interface UsageEntry {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+export interface AccumulatedCost {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCostUsd: number;
+    byModel: Record<string, {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+    }>;
+}
+export interface SessionState {
+    sessionId: string;
+    startedAt: string;
+    developer: string;
+    tool: string;
+    repoPath: string;
+    project: string;
+    linkedIssue: number | null;
+    linkMethod: IssueLinkMethod | null;
+    accumulatedCost: AccumulatedCost;
+    active: boolean;
+}
+export interface CreateSessionOpts {
+    developer: string;
+    tool: string;
+    repoPath?: string;
+    project?: string;
+}
+export declare class SessionManager {
+    private sessions;
+    create(opts: CreateSessionOpts): SessionState;
+    get(sessionId: string): SessionState | undefined;
+    getActive(): SessionState | undefined;
+    addUsage(sessionId: string, entry: UsageEntry): void;
+    linkIssue(sessionId: string, issueNumber: number | null, method: IssueLinkMethod): void;
+    end(sessionId: string): SessionState | undefined;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.js

@@ -0,0 +1,67 @@
+/**
+ * In-memory session state manager.
+ * Sessions are ephemeral — one per MCP server / IDE window.
+ */
+import { randomUUID } from 'node:crypto';
+function emptyAccumulatedCost() {
+    return { totalInputTokens: 0, totalOutputTokens: 0, totalCostUsd: 0, byModel: {} };
+}
+export class SessionManager {
+    sessions = new Map();
+    create(opts) {
+        const sessionId = randomUUID();
+        const session = {
+            sessionId,
+            startedAt: new Date().toISOString(),
+            developer: opts.developer,
+            tool: opts.tool,
+            repoPath: opts.repoPath ?? process.cwd(),
+            project: opts.project ?? process.env['AI_SDLC_PROJECT'] ?? '',
+            linkedIssue: null,
+            linkMethod: null,
+            accumulatedCost: emptyAccumulatedCost(),
+            active: true,
+        };
+        this.sessions.set(sessionId, session);
+        return session;
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    getActive() {
+        for (const s of this.sessions.values()) {
+            if (s.active)
+                return s;
+        }
+        return undefined;
+    }
+    addUsage(sessionId, entry) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        const cost = session.accumulatedCost;
+        cost.totalInputTokens += entry.inputTokens;
+        cost.totalOutputTokens += entry.outputTokens;
+        cost.totalCostUsd += entry.costUsd;
+        const model = cost.byModel[entry.model] ?? { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+        model.inputTokens += entry.inputTokens;
+        model.outputTokens += entry.outputTokens;
+        model.costUsd += entry.costUsd;
+        cost.byModel[entry.model] = model;
+    }
+    linkIssue(sessionId, issueNumber, method) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return;
+        session.linkedIssue = issueNumber;
+        session.linkMethod = method;
+    }
+    end(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return undefined;
+        session.active = false;
+        return session;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/tools/check-file.d.ts

@@ -0,0 +1,15 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export interface CheckFileResult {
+    filePath: string;
+    isHotspot: boolean;
+    isBlocked: boolean;
+    crossesModuleBoundary: boolean;
+    warnings: string[];
+}
+export declare function handleCheckFile(deps: ServerDeps, input: {
+    sessionId?: string;
+    filePath: string;
+}): CheckFileResult;
+export declare function registerCheckFile(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=check-file.d.ts.map

package/dist/tools/check-file.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+export function handleCheckFile(deps, input) {
+    const warnings = [];
+    let isHotspot = false;
+    let isBlocked = false;
+    const crossesModuleBoundary = false;
+    // Check hotspots
+    const hotspots = deps.store.getHotspots(deps.repoPath, 100);
+    const matchingHotspot = hotspots.find((h) => h.filePath === input.filePath || input.filePath.endsWith(h.filePath));
+    if (matchingHotspot) {
+        isHotspot = true;
+        warnings.push(`This file is a hotspot (churn: ${matchingHotspot.churnRate}, complexity: ${matchingHotspot.complexity}). Extra care recommended.`);
+    }
+    // Check blocked paths from complexity profile raw data
+    const profile = deps.store.getLatestComplexityProfile(deps.repoPath);
+    if (profile?.rawData) {
+        try {
+            const raw = JSON.parse(profile.rawData);
+            const blockedPaths = raw.blockedPaths ?? [];
+            if (blockedPaths.some((bp) => input.filePath.startsWith(bp) || input.filePath.includes(bp))) {
+                isBlocked = true;
+                warnings.push('This file is in a blocked path. Modifications may be restricted by policy.');
+            }
+        }
+        catch {
+            // raw data not parseable
+        }
+    }
+    return {
+        filePath: input.filePath,
+        isHotspot,
+        isBlocked,
+        crossesModuleBoundary,
+        warnings,
+    };
+}
+export function registerCheckFile(server, deps) {
+    server.tool('check_file', 'Check if a file is a hotspot, blocked, or crosses module boundaries. Advisory only.', {
+        sessionId: z.string().optional().describe('Session ID (defaults to active session)'),
+        filePath: z.string().describe('File path to check'),
+    }, async ({ sessionId, filePath }) => {
+        const result = handleCheckFile(deps, { sessionId, filePath });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}
+//# sourceMappingURL=check-file.js.map

package/dist/tools/check-task.d.ts

@@ -0,0 +1,15 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export interface CheckTaskResult {
+    issueNumber: number | null;
+    autonomyLevel: number | null;
+    pipelineRuns: number;
+    constraints: string[];
+    advisoryNotes: string[];
+}
+export declare function handleCheckTask(deps: ServerDeps, input: {
+    sessionId?: string;
+    issueNumber?: number;
+}): CheckTaskResult;
+export declare function registerCheckTask(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=check-task.d.ts.map

package/dist/tools/check-task.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+export function handleCheckTask(deps, input) {
+    const session = input.sessionId ? deps.sessions.get(input.sessionId) : deps.sessions.getActive();
+    const issueNumber = input.issueNumber ?? session?.linkedIssue ?? null;
+    const advisoryNotes = [];
+    const constraints = [];
+    // Look up pipeline runs for the issue
+    const runs = issueNumber != null ? deps.store.getPipelineRuns(issueNumber, 10) : [];
+    if (runs.length > 0) {
+        const latest = runs[0];
+        if (latest.status === 'running') {
+            advisoryNotes.push(`Pipeline run ${latest.runId} is currently running (stage: ${latest.currentStage ?? 'unknown'})`);
+        }
+        if (latest.status === 'failed') {
+            advisoryNotes.push(`Last pipeline run failed: ${latest.result ?? 'no details'}`);
+        }
+    }
+    // Autonomy level from ledger (use 'interactive' as the agent name for IDE sessions)
+    let autonomyLevel = null;
+    const ledger = deps.store.getAutonomyLedger('interactive');
+    if (ledger) {
+        autonomyLevel = ledger.currentLevel;
+        if (ledger.currentLevel <= 1) {
+            advisoryNotes.push('Low autonomy level — consider requesting human review for significant changes.');
+        }
+    }
+    if (issueNumber == null) {
+        advisoryNotes.push('No issue linked to this session — work will be unattributed.');
+    }
+    return {
+        issueNumber,
+        autonomyLevel,
+        pipelineRuns: runs.length,
+        constraints,
+        advisoryNotes,
+    };
+}
+export function registerCheckTask(server, deps) {
+    server.tool('check_task', 'Check task status, constraints, and autonomy level for the current session or issue.', {
+        sessionId: z.string().optional().describe('Session ID (defaults to active session)'),
+        issueNumber: z.number().int().optional().describe('Override issue number'),
+    }, async ({ sessionId, issueNumber }) => {
+        const result = handleCheckTask(deps, { sessionId, issueNumber });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}
+//# sourceMappingURL=check-task.js.map

package/dist/tools/get-context.d.ts

@@ -0,0 +1,15 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+declare const SECTION_NAMES: readonly ["profile", "conventions", "hotspots", "patterns", "history"];
+type Section = (typeof SECTION_NAMES)[number];
+export interface GetContextResult {
+    markdown: string;
+    sections: string[];
+}
+export declare function handleGetContext(deps: ServerDeps, input: {
+    sessionId?: string;
+    sections?: Section[];
+}): GetContextResult;
+export declare function registerGetContext(server: McpServer, deps: ServerDeps): void;
+export {};
+//# sourceMappingURL=get-context.d.ts.map

package/dist/tools/get-context.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { buildCodebaseContext, formatContextForPrompt, findRelevantEpisodes, formatEpisodicContext, } from '@ai-sdlc/orchestrator';
+const SECTION_NAMES = ['profile', 'conventions', 'hotspots', 'patterns', 'history'];
+export function handleGetContext(deps, input) {
+    const session = input.sessionId ? deps.sessions.get(input.sessionId) : deps.sessions.getActive();
+    const requestedSections = input.sections ?? [...SECTION_NAMES];
+    const parts = [];
+    // Profile + patterns (derived from complexity profile)
+    if (requestedSections.includes('profile') || requestedSections.includes('patterns')) {
+        const profile = deps.store.getLatestComplexityProfile(deps.repoPath);
+        if (profile) {
+            // Parse raw data if available to reconstruct CodebaseProfile
+            const rawData = (profile.rawData ? safeJsonParse(profile.rawData) : undefined);
+            const hotspots = (profile.hotspots ? safeJsonParse(profile.hotspots) : []);
+            const patterns = (profile.architecturalPatterns ? safeJsonParse(profile.architecturalPatterns) : []);
+            const conventions = (profile.conventionsData ? safeJsonParse(profile.conventionsData) : []);
+            const codebaseProfile = {
+                repoPath: profile.repoPath,
+                score: profile.score,
+                filesCount: profile.filesCount ?? 0,
+                modulesCount: profile.modulesCount ?? 0,
+                dependencyCount: profile.dependencyCount ?? 0,
+                modules: (rawData?.modules ?? []),
+                moduleGraph: (rawData?.moduleGraph ?? {
+                    modules: [],
+                    edges: [],
+                    externalDependencies: [],
+                    cycles: [],
+                }),
+                architecturalPatterns: patterns,
+                hotspots,
+                conventions,
+                analyzedAt: profile.analyzedAt ?? new Date().toISOString(),
+            };
+            const ctx = buildCodebaseContext(codebaseProfile);
+            parts.push(formatContextForPrompt(ctx));
+        }
+    }
+    // Conventions from store
+    if (requestedSections.includes('conventions')) {
+        const conventions = deps.store.getConventions();
+        if (conventions.length > 0) {
+            const lines = ['## Project Conventions', ''];
+            for (const c of conventions) {
+                lines.push(`- **${c.category}**: ${c.pattern}`);
+            }
+            parts.push(lines.join('\n'));
+        }
+    }
+    // Hotspots
+    if (requestedSections.includes('hotspots')) {
+        const hotspots = deps.store.getHotspots(deps.repoPath, 20);
+        if (hotspots.length > 0) {
+            const lines = ['## File Hotspots', ''];
+            for (const h of hotspots.slice(0, 10)) {
+                lines.push(`- \`${h.filePath}\` — churn: ${h.churnRate}, complexity: ${h.complexity}`);
+            }
+            parts.push(lines.join('\n'));
+        }
+    }
+    // History (episodic memory)
+    if (requestedSections.includes('history')) {
+        const issueNumber = session?.linkedIssue ?? undefined;
+        const episodes = findRelevantEpisodes(deps.store, { issueNumber });
+        const formatted = formatEpisodicContext(episodes);
+        if (formatted) {
+            parts.push(formatted);
+        }
+    }
+    return {
+        markdown: parts.join('\n\n'),
+        sections: requestedSections,
+    };
+}
+export function registerGetContext(server, deps) {
+    server.tool('get_context', 'Get rich codebase context: architecture, conventions, hotspots, and history.', {
+        sessionId: z.string().optional().describe('Session ID (defaults to active session)'),
+        sections: z.array(z.enum(SECTION_NAMES)).optional().describe('Sections to include'),
+    }, async ({ sessionId, sections }) => {
+        const result = handleGetContext(deps, { sessionId, sections });
+        return {
+            content: [{ type: 'text', text: result.markdown || 'No context available.' }],
+        };
+    });
+}
+function safeJsonParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=get-context.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export declare function registerAllTools(server: McpServer, deps: ServerDeps): void;
+export { handleSessionStart } from './session-start.js';
+export { handleGetContext } from './get-context.js';
+export { handleCheckTask } from './check-task.js';
+export { handleTrackUsage } from './track-usage.js';
+export { handleCheckFile } from './check-file.js';
+export { handleSessionEnd } from './session-end.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,21 @@
+import { registerSessionStart } from './session-start.js';
+import { registerGetContext } from './get-context.js';
+import { registerCheckTask } from './check-task.js';
+import { registerTrackUsage } from './track-usage.js';
+import { registerCheckFile } from './check-file.js';
+import { registerSessionEnd } from './session-end.js';
+export function registerAllTools(server, deps) {
+    registerSessionStart(server, deps);
+    registerGetContext(server, deps);
+    registerCheckTask(server, deps);
+    registerTrackUsage(server, deps);
+    registerCheckFile(server, deps);
+    registerSessionEnd(server, deps);
+}
+export { handleSessionStart } from './session-start.js';
+export { handleGetContext } from './get-context.js';
+export { handleCheckTask } from './check-task.js';
+export { handleTrackUsage } from './track-usage.js';
+export { handleCheckFile } from './check-file.js';
+export { handleSessionEnd } from './session-end.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/session-end.d.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export interface SessionEndResult {
+    sessionId: string;
+    durationMs: number;
+    linkedIssue: number | null;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    byModel: Record<string, {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+    }>;
+}
+export declare function handleSessionEnd(deps: ServerDeps, input: {
+    sessionId?: string;
+    summary?: string;
+}): SessionEndResult | null;
+export declare function registerSessionEnd(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=session-end.d.ts.map

package/dist/tools/session-end.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+export function handleSessionEnd(deps, input) {
+    const sessionId = input.sessionId ?? deps.sessions.getActive()?.sessionId;
+    if (!sessionId)
+        return null;
+    const session = deps.sessions.end(sessionId);
+    if (!session)
+        return null;
+    const durationMs = Date.now() - new Date(session.startedAt).getTime();
+    // Save episodic record
+    deps.store.saveEpisodicRecord({
+        issueNumber: session.linkedIssue ?? undefined,
+        pipelineType: 'interactive',
+        outcome: 'completed',
+        durationMs,
+        agentName: session.developer,
+        costUsd: session.accumulatedCost.totalCostUsd,
+        metadata: JSON.stringify({
+            tool: session.tool,
+            summary: input.summary,
+            linkMethod: session.linkMethod,
+            byModel: session.accumulatedCost.byModel,
+        }),
+    });
+    // Save audit entry
+    deps.store.saveAuditEntry({
+        entryId: randomUUID(),
+        actor: session.developer,
+        action: 'session.end',
+        resourceType: 'session',
+        resourceId: session.sessionId,
+        detail: JSON.stringify({
+            durationMs,
+            totalCostUsd: session.accumulatedCost.totalCostUsd,
+            linkedIssue: session.linkedIssue,
+            summary: input.summary,
+        }),
+    });
+    return {
+        sessionId: session.sessionId,
+        durationMs,
+        linkedIssue: session.linkedIssue,
+        totalCostUsd: session.accumulatedCost.totalCostUsd,
+        totalInputTokens: session.accumulatedCost.totalInputTokens,
+        totalOutputTokens: session.accumulatedCost.totalOutputTokens,
+        byModel: session.accumulatedCost.byModel,
+    };
+}
+export function registerSessionEnd(server, deps) {
+    server.tool('session_end', 'End the current session and get a cost receipt with full breakdown.', {
+        sessionId: z.string().optional().describe('Session ID (defaults to active session)'),
+        summary: z.string().optional().describe('Brief summary of what was accomplished'),
+    }, async ({ sessionId, summary }) => {
+        const result = handleSessionEnd(deps, { sessionId, summary });
+        if (!result) {
+            return { content: [{ type: 'text', text: 'No active session to end.' }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}
+//# sourceMappingURL=session-end.js.map

package/dist/tools/session-start.d.ts

@@ -0,0 +1,15 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export interface SessionStartResult {
+    sessionId: string;
+    linkedIssue: number | null;
+    linkMethod: string | null;
+    project: string;
+}
+export declare function handleSessionStart(deps: ServerDeps, input: {
+    developer: string;
+    tool: string;
+    issueNumber?: number;
+}): Promise<SessionStartResult>;
+export declare function registerSessionStart(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=session-start.d.ts.map

package/dist/tools/session-start.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import { resolveIssue } from '../issue-linker.js';
+import { randomUUID } from 'node:crypto';
+export async function handleSessionStart(deps, input) {
+    const session = deps.sessions.create({
+        developer: input.developer,
+        tool: input.tool,
+        repoPath: deps.repoPath,
+    });
+    const resolution = await resolveIssue(deps.repoPath, input.issueNumber);
+    deps.sessions.linkIssue(session.sessionId, resolution.issueNumber, resolution.method);
+    // Save audit entry
+    deps.store.saveAuditEntry({
+        entryId: randomUUID(),
+        actor: input.developer,
+        action: 'session.start',
+        resourceType: 'session',
+        resourceId: session.sessionId,
+        detail: JSON.stringify({
+            tool: input.tool,
+            linkedIssue: resolution.issueNumber,
+            linkMethod: resolution.method,
+        }),
+    });
+    return {
+        sessionId: session.sessionId,
+        linkedIssue: resolution.issueNumber,
+        linkMethod: resolution.method,
+        project: session.project,
+    };
+}
+export function registerSessionStart(server, deps) {
+    server.tool('session_start', 'Start a governed AI session. Returns session ID, linked issue, and project context.', {
+        developer: z.string().describe('Developer name or identifier'),
+        tool: z.enum(['claude-code', 'copilot', 'cursor', 'other']).describe('AI tool in use'),
+        issueNumber: z.number().int().optional().describe('Explicit issue number to link'),
+    }, async ({ developer, tool, issueNumber }) => {
+        const result = await handleSessionStart(deps, { developer, tool, issueNumber });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}
+//# sourceMappingURL=session-start.js.map

package/dist/tools/track-usage.d.ts

@@ -0,0 +1,16 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ServerDeps } from '../types.js';
+export interface TrackUsageResult {
+    entryCostUsd: number;
+    cumulativeCostUsd: number;
+    cumulativeInputTokens: number;
+    cumulativeOutputTokens: number;
+}
+export declare function handleTrackUsage(deps: ServerDeps, input: {
+    sessionId?: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+}): TrackUsageResult;
+export declare function registerTrackUsage(server: McpServer, deps: ServerDeps): void;
+//# sourceMappingURL=track-usage.d.ts.map

package/dist/tools/track-usage.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import { CostTracker } from '@ai-sdlc/orchestrator';
+export function handleTrackUsage(deps, input) {
+    const session = input.sessionId ? deps.sessions.get(input.sessionId) : deps.sessions.getActive();
+    const costUsd = CostTracker.computeCost(input.inputTokens, input.outputTokens, input.model);
+    // Record in the cost ledger
+    deps.costTracker.recordCost({
+        runId: session?.sessionId ?? 'unattributed',
+        agentName: session?.developer ?? 'unknown',
+        pipelineType: 'interactive',
+        model: input.model,
+        inputTokens: input.inputTokens,
+        outputTokens: input.outputTokens,
+        issueNumber: session?.linkedIssue ?? undefined,
+    });
+    // Accumulate in the session
+    if (session) {
+        deps.sessions.addUsage(session.sessionId, {
+            model: input.model,
+            inputTokens: input.inputTokens,
+            outputTokens: input.outputTokens,
+            costUsd,
+        });
+    }
+    return {
+        entryCostUsd: costUsd,
+        cumulativeCostUsd: session?.accumulatedCost.totalCostUsd ?? costUsd,
+        cumulativeInputTokens: session?.accumulatedCost.totalInputTokens ?? input.inputTokens,
+        cumulativeOutputTokens: session?.accumulatedCost.totalOutputTokens ?? input.outputTokens,
+    };
+}
+export function registerTrackUsage(server, deps) {
+    server.tool('track_usage', 'Record token usage for cost tracking and budget monitoring.', {
+        sessionId: z.string().optional().describe('Session ID (defaults to active session)'),
+        model: z.string().describe('Model name (e.g. claude-opus-4-6)'),
+        inputTokens: z.number().int().min(0).describe('Number of input tokens'),
+        outputTokens: z.number().int().min(0).describe('Number of output tokens'),
+    }, async ({ sessionId, model, inputTokens, outputTokens }) => {
+        const result = handleTrackUsage(deps, { sessionId, model, inputTokens, outputTokens });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+}
+//# sourceMappingURL=track-usage.js.map

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared dependency injection types for tools and resources.
+ */
+import type { StateStore } from '@ai-sdlc/orchestrator/state';
+import type { CostTracker } from '@ai-sdlc/orchestrator';
+import type { SessionManager } from './session.js';
+export interface ServerDeps {
+    store: StateStore;
+    costTracker: CostTracker;
+    sessions: SessionManager;
+    repoPath: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared dependency injection types for tools and resources.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ai-sdlc/mcp-advisor",
+  "version": "0.1.0",
+  "description": "MCP server bridging human-directed AI sessions with the AI-SDLC orchestrator",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ai-sdlc-framework/ai-sdlc.git",
+    "directory": "mcp-advisor"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": ["dist", "!dist/**/*.test.*", "!dist/**/*.map"],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ai-sdlc-mcp-advisor": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ai-sdlc/orchestrator": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^11.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}