@lumenflow/mcp 2.11.0

package/dist/tools.js

@@ -0,0 +1,314 @@
+/**
+ * @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';
+import { runCliCommand } from './cli-runner.js';
+// Import core functions for context operations only
+let coreModule = null;
+async function getCore() {
+    if (!coreModule) {
+        coreModule = await import('@lumenflow/core');
+    }
+    return coreModule;
+}
+/**
+ * Error codes used by tool implementations
+ */
+const ErrorCodes = {
+    MISSING_PARAMETER: 'MISSING_PARAMETER',
+    CONTEXT_ERROR: 'CONTEXT_ERROR',
+    WU_LIST_ERROR: 'WU_LIST_ERROR',
+    WU_STATUS_ERROR: 'WU_STATUS_ERROR',
+    WU_CREATE_ERROR: 'WU_CREATE_ERROR',
+    WU_CLAIM_ERROR: 'WU_CLAIM_ERROR',
+    WU_DONE_ERROR: 'WU_DONE_ERROR',
+    WRONG_LOCATION: 'WRONG_LOCATION',
+    GATES_ERROR: 'GATES_ERROR',
+};
+/**
+ * Error messages used by tool implementations
+ */
+const ErrorMessages = {
+    ID_REQUIRED: 'id is required',
+    LANE_REQUIRED: 'lane is required',
+    TITLE_REQUIRED: 'title is required',
+};
+/**
+ * Create a successful tool result
+ */
+function success(data) {
+    return { success: true, data };
+}
+/**
+ * Create an error tool result
+ */
+function error(message, code) {
+    return { success: false, error: { message, code } };
+}
+// ============================================================================
+// Read Operations (via @lumenflow/core)
+// ============================================================================
+/**
+ * context_get - Get current WU context (location, git state, WU state)
+ */
+export const contextGetTool = {
+    name: 'context_get',
+    description: 'Get current LumenFlow context including location, git state, and active WU',
+    inputSchema: z.object({}).optional(),
+    async execute(_input, options) {
+        try {
+            const core = await getCore();
+            const context = await core.computeWuContext({
+                cwd: options?.projectRoot,
+            });
+            return success(context);
+        }
+        catch (err) {
+            return error(err instanceof Error ? err.message : String(err), ErrorCodes.CONTEXT_ERROR);
+        }
+    },
+};
+/**
+ * wu_list - List all WUs with optional status filter
+ * Uses CLI shell-out for consistency with other tools
+ */
+export const wuListTool = {
+    name: 'wu_list',
+    description: 'List all Work Units (WUs) with optional status filter',
+    inputSchema: z.object({
+        status: z.enum(['ready', 'in_progress', 'blocked', 'waiting', 'done']).optional(),
+        lane: z.string().optional(),
+    }),
+    async execute(input, options) {
+        // Use spec:linter which validates and lists all WUs
+        const cliOptions = { projectRoot: options?.projectRoot };
+        // Shell out to get all WU YAMLs via validate --all
+        const result = await runCliCommand('wu:validate', ['--all', '--json'], cliOptions);
+        if (result.success) {
+            try {
+                const data = JSON.parse(result.stdout);
+                let wus = Array.isArray(data) ? data : data.wus || [];
+                // Apply filters
+                if (input.status) {
+                    wus = wus.filter((wu) => wu.status === input.status);
+                }
+                if (input.lane) {
+                    wus = wus.filter((wu) => wu.lane === input.lane);
+                }
+                return success(wus);
+            }
+            catch {
+                // If JSON parse fails, return raw output
+                return success({ message: result.stdout });
+            }
+        }
+        else {
+            return error(result.stderr || result.error?.message || 'wu_list failed', ErrorCodes.WU_LIST_ERROR);
+        }
+    },
+};
+/**
+ * wu_status - Get status of a specific WU
+ * Uses CLI shell-out for consistency
+ */
+export const wuStatusTool = {
+    name: 'wu_status',
+    description: 'Get detailed status of a specific Work Unit',
+    inputSchema: z.object({
+        id: z.string().describe('WU ID (e.g., WU-1412)'),
+    }),
+    async execute(input, options) {
+        if (!input.id) {
+            return error(ErrorMessages.ID_REQUIRED, ErrorCodes.MISSING_PARAMETER);
+        }
+        const args = ['--id', input.id, '--json'];
+        const cliOptions = { projectRoot: options?.projectRoot };
+        const result = await runCliCommand('wu:status', args, cliOptions);
+        if (result.success) {
+            try {
+                const data = JSON.parse(result.stdout);
+                return success(data);
+            }
+            catch {
+                return success({ message: result.stdout });
+            }
+        }
+        else {
+            return error(result.stderr || result.error?.message || 'wu:status failed', ErrorCodes.WU_STATUS_ERROR);
+        }
+    },
+};
+// ============================================================================
+// Write Operations (via CLI shell-out)
+// ============================================================================
+/**
+ * wu_create - Create a new WU
+ */
+export const wuCreateTool = {
+    name: 'wu_create',
+    description: 'Create a new Work Unit specification',
+    inputSchema: z.object({
+        id: z.string().optional().describe('WU ID (auto-generated if omitted)'),
+        lane: z.string().describe('Lane (e.g., "Framework: CLI")'),
+        title: z.string().describe('WU title'),
+        description: z.string().optional().describe('Context: ... Problem: ... Solution: ...'),
+        acceptance: z.array(z.string()).optional().describe('Acceptance criteria'),
+        code_paths: z.array(z.string()).optional().describe('Code paths'),
+        exposure: z.enum(['ui', 'api', 'backend-only', 'documentation']).optional(),
+    }),
+    async execute(input, options) {
+        if (!input.lane) {
+            return error(ErrorMessages.LANE_REQUIRED, ErrorCodes.MISSING_PARAMETER);
+        }
+        if (!input.title) {
+            return error(ErrorMessages.TITLE_REQUIRED, ErrorCodes.MISSING_PARAMETER);
+        }
+        const args = ['--lane', input.lane, '--title', input.title];
+        if (input.id)
+            args.push('--id', input.id);
+        if (input.description)
+            args.push('--description', input.description);
+        if (input.acceptance) {
+            for (const criterion of input.acceptance) {
+                args.push('--acceptance', criterion);
+            }
+        }
+        if (input.code_paths) {
+            for (const p of input.code_paths) {
+                args.push('--code-paths', p);
+            }
+        }
+        if (input.exposure)
+            args.push('--exposure', input.exposure);
+        const cliOptions = { projectRoot: options?.projectRoot };
+        const result = await runCliCommand('wu:create', args, cliOptions);
+        if (result.success) {
+            return success({ message: result.stdout || 'WU created successfully' });
+        }
+        else {
+            return error(result.stderr || result.error?.message || 'wu:create failed', ErrorCodes.WU_CREATE_ERROR);
+        }
+    },
+};
+/**
+ * wu_claim - Claim a WU and create worktree
+ */
+export const wuClaimTool = {
+    name: 'wu_claim',
+    description: 'Claim a Work Unit and create worktree for implementation',
+    inputSchema: z.object({
+        id: z.string().describe('WU ID to claim'),
+        lane: z.string().describe('Lane for the WU'),
+    }),
+    async execute(input, options) {
+        if (!input.id) {
+            return error(ErrorMessages.ID_REQUIRED, ErrorCodes.MISSING_PARAMETER);
+        }
+        if (!input.lane) {
+            return error(ErrorMessages.LANE_REQUIRED, ErrorCodes.MISSING_PARAMETER);
+        }
+        const args = ['--id', input.id, '--lane', input.lane];
+        const cliOptions = { projectRoot: options?.projectRoot };
+        const result = await runCliCommand('wu:claim', args, cliOptions);
+        if (result.success) {
+            return success({ message: result.stdout || 'WU claimed successfully' });
+        }
+        else {
+            return error(result.stderr || result.error?.message || 'wu:claim failed', ErrorCodes.WU_CLAIM_ERROR);
+        }
+    },
+};
+/**
+ * wu_done - Complete a WU (must be run from main checkout)
+ */
+export const wuDoneTool = {
+    name: 'wu_done',
+    description: 'Complete a Work Unit (merge, stamp, cleanup). MUST be run from main checkout.',
+    inputSchema: z.object({
+        id: z.string().describe('WU ID to complete'),
+        skip_gates: z.boolean().optional().describe('Skip gates (requires reason)'),
+        reason: z.string().optional().describe('Reason for skipping gates'),
+        fix_wu: z.string().optional().describe('WU ID that will fix the skipped issue'),
+    }),
+    async execute(input, options) {
+        if (!input.id) {
+            return error(ErrorMessages.ID_REQUIRED, ErrorCodes.MISSING_PARAMETER);
+        }
+        // Fail fast if not on main checkout (AC: wu_done fails fast if not on main checkout)
+        try {
+            const core = await getCore();
+            const context = await core.computeWuContext({
+                cwd: options?.projectRoot,
+            });
+            if (context.location.type === 'worktree') {
+                return error('wu_done must be run from main checkout, not from a worktree. ' +
+                    'Run "pnpm wu:prep" first from the worktree, then cd to main and run wu:done.', ErrorCodes.WRONG_LOCATION);
+            }
+        }
+        catch {
+            // If we can't determine context, proceed anyway - CLI will validate
+        }
+        const args = ['--id', input.id];
+        if (input.skip_gates) {
+            args.push('--skip-gates');
+            if (input.reason)
+                args.push('--reason', input.reason);
+            if (input.fix_wu)
+                args.push('--fix-wu', input.fix_wu);
+        }
+        const cliOptions = { projectRoot: options?.projectRoot };
+        const result = await runCliCommand('wu:done', args, cliOptions);
+        if (result.success) {
+            return success({ message: result.stdout || 'WU completed successfully' });
+        }
+        else {
+            return error(result.stderr || result.error?.message || 'wu:done failed', ErrorCodes.WU_DONE_ERROR);
+        }
+    },
+};
+/**
+ * gates_run - Run quality gates
+ */
+export const gatesRunTool = {
+    name: 'gates_run',
+    description: 'Run LumenFlow quality gates (lint, typecheck, tests)',
+    inputSchema: z.object({
+        docs_only: z.boolean().optional().describe('Run docs-only gates (skip lint/typecheck/tests)'),
+    }),
+    async execute(input, options) {
+        const args = [];
+        if (input.docs_only) {
+            args.push('--docs-only');
+        }
+        const cliOptions = {
+            projectRoot: options?.projectRoot,
+            timeout: 600000, // 10 minutes for gates
+        };
+        const result = await runCliCommand('gates', args, cliOptions);
+        if (result.success) {
+            return success({ message: result.stdout || 'All gates passed' });
+        }
+        else {
+            return error(result.stderr || result.error?.message || 'Gates failed', ErrorCodes.GATES_ERROR);
+        }
+    },
+};
+/**
+ * All available tools
+ */
+export const allTools = [
+    contextGetTool,
+    wuListTool,
+    wuStatusTool,
+    wuCreateTool,
+    wuClaimTool,
+    wuDoneTool,
+    gatesRunTool,
+];

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@lumenflow/mcp",
+  "version": "2.11.0",
+  "description": "MCP stdio server for LumenFlow workflow framework",
+  "keywords": [
+    "lumenflow",
+    "mcp",
+    "model-context-protocol",
+    "workflow",
+    "wu",
+    "work-unit"
+  ],
+  "homepage": "https://github.com/hellmai/os",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hellmai/os.git",
+    "directory": "packages/@lumenflow/mcp"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "HellmAI",
+    "url": "https://hellm.ai"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./tools": {
+      "types": "./dist/tools.d.ts",
+      "import": "./dist/tools.js"
+    },
+    "./cli-runner": {
+      "types": "./dist/cli-runner.d.ts",
+      "import": "./dist/cli-runner.js"
+    }
+  },
+  "bin": {
+    "lumenflow-mcp": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.5",
+    "@lumenflow/core": "2.11.0"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.17",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:dist": "tsc -p tsconfig.build.json",
+    "pack:dist": "pnpm pack",
+    "clean": "rm -rf dist *.tgz",
+    "test": "vitest run"
+  }
+}