@lumenflow/mcp 2.11.0

package/dist/resources.js

@@ -0,0 +1,128 @@
+/**
+ * @file resources.ts
+ * @description MCP resource implementations for LumenFlow
+ *
+ * WU-1412: Resources available: context, wu/{id}, backlog
+ *
+ * Resources provide read access to LumenFlow data via URI patterns.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { runCliCommand } from './cli-runner.js';
+// Lazy load core module for context
+let coreModule = null;
+async function getCore() {
+    if (!coreModule) {
+        coreModule = await import('@lumenflow/core');
+    }
+    return coreModule;
+}
+/**
+ * context - Current LumenFlow context
+ */
+export const contextResource = {
+    uri: 'lumenflow://context',
+    name: 'LumenFlow Context',
+    description: 'Current LumenFlow context including location, git state, and active WU',
+    mimeType: 'application/json',
+    async fetch(_uri, options) {
+        try {
+            const core = await getCore();
+            const context = await core.computeWuContext({
+                cwd: options?.projectRoot,
+            });
+            return {
+                success: true,
+                content: JSON.stringify(context, null, 2),
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    },
+};
+/**
+ * wu/{id} - WU specification by ID
+ */
+export const wuResource = {
+    uriTemplate: 'lumenflow://wu/{id}',
+    name: 'Work Unit',
+    description: 'Work Unit specification by ID',
+    mimeType: 'application/json',
+    async fetch(uri, options) {
+        try {
+            // Extract ID from URI: lumenflow://wu/WU-1412 -> WU-1412
+            const match = /^lumenflow:\/\/wu\/(.+)$/.exec(uri);
+            if (!match) {
+                return { success: false, error: 'Invalid WU URI format' };
+            }
+            const id = match[1];
+            // Use CLI to get WU status (includes full WU context)
+            const result = await runCliCommand('wu:status', ['--id', id, '--json'], {
+                projectRoot: options?.projectRoot,
+            });
+            if (result.success) {
+                return {
+                    success: true,
+                    content: result.stdout,
+                };
+            }
+            else {
+                return {
+                    success: false,
+                    error: result.stderr || result.error?.message || 'Failed to get WU',
+                };
+            }
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    },
+};
+/**
+ * backlog - Current backlog state
+ * Reads the backlog.md file directly (generated by LumenFlow CLI)
+ */
+export const backlogResource = {
+    uri: 'lumenflow://backlog',
+    name: 'Backlog',
+    description: 'Current LumenFlow backlog with all WUs grouped by status',
+    mimeType: 'text/markdown',
+    async fetch(_uri, options) {
+        try {
+            const projectRoot = options?.projectRoot || process.cwd();
+            // Security: path is constructed from known static segments, not user input
+            const backlogPath = path.join(projectRoot, 'docs', '04-operations', 'tasks', 'backlog.md');
+            // eslint-disable-next-line security/detect-non-literal-fs-filename
+            const content = await fs.readFile(backlogPath, 'utf-8');
+            return {
+                success: true,
+                content,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    },
+};
+/**
+ * All static resources (fixed URIs)
+ */
+export const staticResources = [contextResource, backlogResource];
+/**
+ * All resource templates (parameterized URIs)
+ */
+export const resourceTemplates = [wuResource];
+/**
+ * All resources
+ */
+export const allResources = [...staticResources, ...resourceTemplates];

package/dist/server.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @file server.ts
+ * @description MCP server factory and configuration
+ *
+ * WU-1412: MCP server runs via npx @lumenflow/mcp over stdio
+ *
+ * Creates an MCP server that exposes LumenFlow tools and resources.
+ * Supports configuration via environment variables:
+ * - LUMENFLOW_PROJECT_ROOT: Project root directory
+ * - LUMENFLOW_MCP_LOG_LEVEL: Log level (debug, info, warn, error)
+ */
+/**
+ * Log levels supported by the MCP server
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * MCP server configuration
+ */
+export interface McpServerConfig {
+    /** Project root directory (default: process.cwd()) */
+    projectRoot?: string;
+    /** Log level (default: 'info') */
+    logLevel?: LogLevel;
+}
+/**
+ * MCP server instance with LumenFlow tools and resources
+ */
+export interface McpServer {
+    /** Server name */
+    name: string;
+    /** Server configuration */
+    config: Required<McpServerConfig>;
+    /** List available tools */
+    listTools: () => Array<{
+        name: string;
+        description: string;
+    }>;
+    /** List available static resources */
+    listResources: () => Array<{
+        uri: string;
+        name: string;
+        description: string;
+    }>;
+    /** List available resource templates */
+    listResourceTemplates: () => Array<{
+        uriTemplate: string;
+        name: string;
+        description: string;
+    }>;
+    /** Start the server (connects stdio transport) */
+    start: () => Promise<void>;
+    /** Stop the server */
+    stop: () => Promise<void>;
+}
+/**
+ * Create an MCP server with LumenFlow tools and resources
+ *
+ * @param config - Server configuration
+ * @returns MCP server instance
+ *
+ * @example
+ * const server = createMcpServer({
+ *   projectRoot: process.env.LUMENFLOW_PROJECT_ROOT,
+ *   logLevel: process.env.LUMENFLOW_MCP_LOG_LEVEL as LogLevel,
+ * });
+ * await server.start();
+ */
+export declare function createMcpServer(config?: McpServerConfig): McpServer;

package/dist/server.js

@@ -0,0 +1,190 @@
+/**
+ * @file server.ts
+ * @description MCP server factory and configuration
+ *
+ * WU-1412: MCP server runs via npx @lumenflow/mcp over stdio
+ *
+ * Creates an MCP server that exposes LumenFlow tools and resources.
+ * Supports configuration via environment variables:
+ * - LUMENFLOW_PROJECT_ROOT: Project root directory
+ * - LUMENFLOW_MCP_LOG_LEVEL: Log level (debug, info, warn, error)
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListResourceTemplatesRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { allTools } from './tools.js';
+import { staticResources, resourceTemplates } from './resources.js';
+/**
+ * Convert a Zod schema to JSON Schema format for MCP
+ */
+function zodToJsonSchema(schema) {
+    return z.toJSONSchema(schema);
+}
+/**
+ * Create an MCP server with LumenFlow tools and resources
+ *
+ * @param config - Server configuration
+ * @returns MCP server instance
+ *
+ * @example
+ * const server = createMcpServer({
+ *   projectRoot: process.env.LUMENFLOW_PROJECT_ROOT,
+ *   logLevel: process.env.LUMENFLOW_MCP_LOG_LEVEL as LogLevel,
+ * });
+ * await server.start();
+ */
+export function createMcpServer(config = {}) {
+    const resolvedConfig = {
+        projectRoot: config.projectRoot || process.env.LUMENFLOW_PROJECT_ROOT || process.cwd(),
+        logLevel: config.logLevel || process.env.LUMENFLOW_MCP_LOG_LEVEL || 'info',
+    };
+    // Create the MCP SDK server
+    const server = new Server({
+        name: '@lumenflow/mcp',
+        version: '2.10.0',
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+        },
+    });
+    // Register tool handlers
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: allTools.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: zodToJsonSchema(tool.inputSchema),
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const tool = allTools.find((t) => t.name === name);
+        if (!tool) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }) }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await tool.execute(args || {}, { projectRoot: resolvedConfig.projectRoot });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result) }],
+                isError: !result.success,
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Register resource handlers
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: staticResources
+                .filter((r) => r.uri !== undefined)
+                .map((r) => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+        };
+    });
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
+        return {
+            resourceTemplates: resourceTemplates
+                .filter((r) => r.uriTemplate !== undefined)
+                .map((r) => ({
+                uriTemplate: r.uriTemplate,
+                name: r.name,
+                description: r.description,
+                mimeType: r.mimeType,
+            })),
+        };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        // Find matching resource
+        let resource;
+        // Check static resources first
+        resource = staticResources.find((r) => r.uri === uri);
+        // Check resource templates
+        if (!resource) {
+            for (const template of resourceTemplates) {
+                if (template.uriTemplate) {
+                    // Simple template matching for lumenflow://wu/{id} pattern
+                    // Security: pattern is derived from our own static uriTemplate, not user input
+                    const pattern = template.uriTemplate.replace(/\{[^}]+\}/g, '([^/]+)');
+                    // eslint-disable-next-line security/detect-non-literal-regexp
+                    const regex = new RegExp(`^${pattern}$`);
+                    if (regex.test(uri)) {
+                        resource = template;
+                        break;
+                    }
+                }
+            }
+        }
+        if (!resource) {
+            return {
+                contents: [{ uri, text: `Resource not found: ${uri}`, mimeType: 'text/plain' }],
+            };
+        }
+        const result = await resource.fetch(uri, { projectRoot: resolvedConfig.projectRoot });
+        return {
+            contents: [
+                {
+                    uri,
+                    text: result.success ? (result.content ?? '') : `Error: ${result.error}`,
+                    mimeType: resource.mimeType,
+                },
+            ],
+        };
+    });
+    // Build the McpServer wrapper
+    let transport = null;
+    return {
+        name: '@lumenflow/mcp',
+        config: resolvedConfig,
+        listTools() {
+            return allTools.map((t) => ({ name: t.name, description: t.description }));
+        },
+        listResources() {
+            return staticResources
+                .filter((r) => r.uri !== undefined)
+                .map((r) => ({
+                uri: r.uri,
+                name: r.name,
+                description: r.description,
+            }));
+        },
+        listResourceTemplates() {
+            return resourceTemplates
+                .filter((r) => r.uriTemplate !== undefined)
+                .map((r) => ({
+                uriTemplate: r.uriTemplate,
+                name: r.name,
+                description: r.description,
+            }));
+        },
+        async start() {
+            transport = new StdioServerTransport();
+            await server.connect(transport);
+        },
+        async stop() {
+            if (transport) {
+                await server.close();
+                transport = null;
+            }
+        },
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file tools.ts
+ * @description MCP tool implementations for LumenFlow operations
+ *
+ * WU-1412: Tools available: context_get, wu_list, wu_status, wu_create, wu_claim, wu_done, gates_run
+ *
+ * Architecture:
+ * - Read operations (context_get) use @lumenflow/core directly for context
+ * - All other operations shell out to CLI for consistency and safety
+ */
+import { z } from 'zod';
+/**
+ * Tool result structure matching MCP SDK expectations
+ */
+export interface ToolResult {
+    success: boolean;
+    data?: unknown;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * Base tool definition
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType;
+    execute: (input: Record<string, unknown>, options?: {
+        projectRoot?: string;
+    }) => Promise<ToolResult>;
+}
+/**
+ * context_get - Get current WU context (location, git state, WU state)
+ */
+export declare const contextGetTool: ToolDefinition;
+/**
+ * wu_list - List all WUs with optional status filter
+ * Uses CLI shell-out for consistency with other tools
+ */
+export declare const wuListTool: ToolDefinition;
+/**
+ * wu_status - Get status of a specific WU
+ * Uses CLI shell-out for consistency
+ */
+export declare const wuStatusTool: ToolDefinition;
+/**
+ * wu_create - Create a new WU
+ */
+export declare const wuCreateTool: ToolDefinition;
+/**
+ * wu_claim - Claim a WU and create worktree
+ */
+export declare const wuClaimTool: ToolDefinition;
+/**
+ * wu_done - Complete a WU (must be run from main checkout)
+ */
+export declare const wuDoneTool: ToolDefinition;
+/**
+ * gates_run - Run quality gates
+ */
+export declare const gatesRunTool: ToolDefinition;
+/**
+ * All available tools
+ */
+export declare const allTools: ToolDefinition[];