@leclabs/agent-flow-navigator-mcp 1.0.0

package/index.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+/**
+ * Navigator MCP Server (Stateless) v2
+ *
+ * Provides stateless workflow navigation for the flow plugin.
+ * All task state is stored in Claude Code native /tasks via metadata.navigator.
+ *
+ * Tools:
+ * - Navigate: Unified navigation - start, get current, or advance
+ * - ListWorkflows: List available workflows
+ * - Diagram: Generate mermaid diagram for workflow
+ * - CopyWorkflows: Copy workflows from catalog to project
+ * - ListCatalog: List workflows available in catalog
+ */
+
+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 { WorkflowEngine } from "./engine.js";
+import { generateDiagram } from "./diagram.js";
+import { WorkflowStore, validateWorkflow } from "./store.js";
+import { buildWorkflowSelectionDialog } from "./dialog.js";
+import {
+  generateFlowReadme,
+  generateWorkflowsReadme,
+  isValidWorkflowForCopy,
+  computeWorkflowsToCopy,
+} from "./copier.js";
+import { buildWorkflowSummary, buildCatalogResponse, buildEmptyCatalogResponse } from "./catalog.js";
+import { readFileSync, existsSync, readdirSync, mkdirSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CATALOG_PATH = join(__dirname, "catalog");
+
+// Project root: from CLI arg (ignore flags starting with -), or current working directory
+const cliArg = process.argv[2];
+const PROJECT_ROOT = cliArg && !cliArg.startsWith("-") ? resolve(cliArg) : process.cwd();
+const FLOW_PATH = join(PROJECT_ROOT, ".flow");
+const WORKFLOWS_PATH = join(FLOW_PATH, "workflows");
+const DIAGRAMS_PATH = join(FLOW_PATH, "diagrams");
+
+const store = new WorkflowStore();
+const engine = new WorkflowEngine(store);
+
+/**
+ * Load workflows from project directory structure: {id}/workflow.json
+ */
+function loadProjectWorkflows(dirPath) {
+  if (!existsSync(dirPath)) return [];
+
+  const loaded = [];
+  const entries = readdirSync(dirPath, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const id = entry.name;
+    const workflowFile = join(dirPath, id, "workflow.json");
+
+    if (!existsSync(workflowFile)) continue;
+
+    try {
+      const content = JSON.parse(readFileSync(workflowFile, "utf-8"));
+      if (validateWorkflow(id, content)) {
+        store.loadDefinition(id, content);
+        loaded.push(id);
+      }
+    } catch (e) {
+      console.error(`Error loading workflow ${id}: ${e.message}`);
+    }
+  }
+
+  return loaded;
+}
+
+/**
+ * Load workflows from catalog: flat {id}.json files
+ */
+function loadCatalogWorkflows(dirPath) {
+  if (!existsSync(dirPath)) return [];
+
+  const loaded = [];
+  const files = readdirSync(dirPath).filter((f) => f.endsWith(".json"));
+
+  for (const file of files) {
+    const id = file.replace(".json", "");
+
+    try {
+      const content = JSON.parse(readFileSync(join(dirPath, file), "utf-8"));
+      if (validateWorkflow(id, content)) {
+        store.loadDefinition(id, content);
+        loaded.push(id);
+      }
+    } catch (e) {
+      console.error(`Error loading catalog workflow ${id}: ${e.message}`);
+    }
+  }
+
+  return loaded;
+}
+
+/**
+ * Load workflows: catalog first, then project overwrites (project takes precedence)
+ */
+function loadWorkflows() {
+  const catalogPath = join(CATALOG_PATH, "workflows");
+  const catalogLoaded = loadCatalogWorkflows(catalogPath);
+
+  const projectLoaded = existsSync(WORKFLOWS_PATH) ? loadProjectWorkflows(WORKFLOWS_PATH) : [];
+
+  // Determine which IDs came from where (project overwrites catalog)
+  const fromCatalog = catalogLoaded.filter((id) => !projectLoaded.includes(id));
+  const fromProject = projectLoaded;
+
+  return {
+    catalog: fromCatalog,
+    project: fromProject,
+    loaded: [...new Set([...catalogLoaded, ...projectLoaded])],
+  };
+}
+
+// Initialize server
+const server = new Server({ name: "navigator", version: "2.0.0" }, { capabilities: { tools: {} } });
+
+/**
+ * Minimal JSON response
+ */
+function jsonResponse(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+
+// Define tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "Navigate",
+        description: "Unified workflow navigation. Start a workflow, get current state, or advance to next step.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            taskFilePath: {
+              type: "string",
+              description: "Path to task file (for advance/current). Reads workflow state from task metadata.",
+            },
+            workflowType: { type: "string", description: "Workflow ID (for start only, e.g., 'feature-development')" },
+            result: {
+              type: "string",
+              enum: ["passed", "failed"],
+              description: "Step result (for advance). Omit to just get current state.",
+            },
+            description: { type: "string", description: "User's task description (for start)" },
+          },
+        },
+      },
+      {
+        name: "ListWorkflows",
+        description: "List all available workflows. Returns data only, no dialog.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "SelectWorkflow",
+        description:
+          "Get workflow selection dialog for user interaction. Returns workflows with multi-pane dialog for AskUserQuestion.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+      {
+        name: "Diagram",
+        description: "Generate a mermaid flowchart diagram for a workflow.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            workflowType: { type: "string", description: "Workflow ID to visualize" },
+            currentStep: { type: "string", description: "Optional: highlight this step" },
+          },
+          required: ["workflowType"],
+        },
+      },
+      {
+        name: "CopyWorkflows",
+        description:
+          "Copy workflows from catalog to project. Creates workflow directory with workflow.json, README.md, and step instruction files.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            workflowIds: {
+              type: "array",
+              items: { type: "string" },
+              description: "Workflow IDs to copy. Empty = all.",
+            },
+          },
+        },
+      },
+      {
+        name: "ListCatalog",
+        description: "List workflows available in the catalog.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "Navigate": {
+        const result = engine.navigate({
+          taskFilePath: args.taskFilePath,
+          workflowType: args.workflowType,
+          result: args.result,
+          description: args.description,
+        });
+        return jsonResponse(result);
+      }
+
+      case "ListWorkflows": {
+        return jsonResponse({
+          schemaVersion: 2,
+          workflows: store.listWorkflows(),
+        });
+      }
+
+      case "SelectWorkflow": {
+        const workflows = store.listWorkflows();
+        return jsonResponse(buildWorkflowSelectionDialog(workflows));
+      }
+
+      case "Diagram": {
+        const wfDef = store.getDefinition(args.workflowType);
+        if (!wfDef) {
+          throw new Error(`Workflow '${args.workflowType}' not found`);
+        }
+
+        const markdown = generateDiagram(wfDef, args.currentStep);
+
+        // Save diagram to file
+        if (!existsSync(DIAGRAMS_PATH)) {
+          mkdirSync(DIAGRAMS_PATH, { recursive: true });
+        }
+        const filePath = join(DIAGRAMS_PATH, `${args.workflowType}.md`);
+        writeFileSync(filePath, markdown);
+
+        return jsonResponse({ savedTo: filePath });
+      }
+
+      case "CopyWorkflows": {
+        const catalogPath = join(CATALOG_PATH, "workflows");
+        if (!existsSync(catalogPath)) {
+          throw new Error("Catalog workflows directory not found");
+        }
+
+        if (!existsSync(WORKFLOWS_PATH)) {
+          mkdirSync(WORKFLOWS_PATH, { recursive: true });
+        }
+
+        // Write README files
+        writeFileSync(join(FLOW_PATH, "README.md"), generateFlowReadme());
+        writeFileSync(join(WORKFLOWS_PATH, "README.md"), generateWorkflowsReadme());
+
+        const catalogFiles = readdirSync(catalogPath).filter((f) => f.endsWith(".json"));
+        const availableIds = catalogFiles.map((f) => f.replace(".json", ""));
+        const workflowIds = computeWorkflowsToCopy(args.workflowIds, availableIds);
+
+        const copied = [];
+        const errors = [];
+
+        for (const id of workflowIds) {
+          const srcFile = join(catalogPath, `${id}.json`);
+
+          if (!existsSync(srcFile)) {
+            errors.push({ id, error: "not found in catalog" });
+            continue;
+          }
+
+          try {
+            const content = JSON.parse(readFileSync(srcFile, "utf-8"));
+            if (!isValidWorkflowForCopy(content)) {
+              errors.push({ id, error: "invalid schema" });
+              continue;
+            }
+
+            // Create workflow directory and write workflow.json
+            const workflowDir = join(WORKFLOWS_PATH, id);
+            mkdirSync(workflowDir, { recursive: true });
+            writeFileSync(join(workflowDir, "workflow.json"), JSON.stringify(content, null, 2));
+
+            // Load into memory
+            store.loadDefinition(id, content);
+            copied.push(id);
+          } catch (e) {
+            errors.push({ id, error: e.message });
+          }
+        }
+
+        return jsonResponse({
+          schemaVersion: 2,
+          copied,
+          errors: errors.length > 0 ? errors : undefined,
+          path: WORKFLOWS_PATH,
+        });
+      }
+
+      case "ListCatalog": {
+        const catalogPath = join(CATALOG_PATH, "workflows");
+        if (!existsSync(catalogPath)) {
+          return jsonResponse(buildEmptyCatalogResponse());
+        }
+
+        const workflows = [];
+        const files = readdirSync(catalogPath).filter((f) => f.endsWith(".json"));
+
+        for (const file of files) {
+          try {
+            const content = JSON.parse(readFileSync(join(catalogPath, file), "utf-8"));
+            workflows.push(buildWorkflowSummary(file.replace(".json", ""), content));
+          } catch {
+            // Skip invalid files
+          }
+        }
+
+        return jsonResponse(buildCatalogResponse(workflows));
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return jsonResponse({
+      schemaVersion: 2,
+      error: error.message,
+      tool: name,
+      args,
+    });
+  }
+});
+
+/**
+ * Ensure .flow/README.md exists (created on MCP server connect)
+ */
+function ensureFlowReadme() {
+  const readmePath = join(FLOW_PATH, "README.md");
+  if (!existsSync(readmePath)) {
+    mkdirSync(FLOW_PATH, { recursive: true });
+    writeFileSync(readmePath, generateFlowReadme());
+    console.error(`  Created: ${readmePath}`);
+  }
+}
+
+// Load workflows and start server
+const workflowInfo = loadWorkflows();
+ensureFlowReadme();
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+console.error(`Navigator MCP Server v2 running (stateless)`);
+console.error(`  Project: ${PROJECT_ROOT}`);
+console.error(`  Workflows: ${workflowInfo.loaded.length} total`);
+if (workflowInfo.catalog.length > 0) {
+  console.error(`    Catalog: ${workflowInfo.catalog.join(", ")}`);
+}
+if (workflowInfo.project.length > 0) {
+  console.error(`    Project: ${workflowInfo.project.join(", ")}`);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@leclabs/agent-flow-navigator-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that navigates agents through DAG-based workflows",
+  "license": "MIT",
+  "author": "leclabs",
+  "homepage": "https://github.com/leclabs/agent-toolkit",
+  "bugs": {
+    "url": "https://github.com/leclabs/agent-toolkit/issues"
+  },
+  "bin": {
+    "agent-flow-navigator": "./index.js"
+  },
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test engine.test.js diagram.test.js store.test.js dialog.test.js copier.test.js catalog.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "workflow",
+    "flow",
+    "navigator",
+    "state-machine",
+    "claude",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leclabs/agent-toolkit.git",
+    "directory": "packages/agent-flow-navigator-mcp"
+  },
+  "files": [
+    "index.js",
+    "engine.js",
+    "diagram.js",
+    "store.js",
+    "dialog.js",
+    "copier.js",
+    "catalog.js",
+    "catalog/**/*.json",
+    "types.d.ts"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "zod": "^3.22.4"
+  }
+}

package/store.js

@@ -0,0 +1,90 @@
+/**
+ * store.js - Pure workflow store module
+ *
+ * Manages workflow definitions in memory. Pure data structure with no I/O.
+ * File loading handled by MCP server initialization.
+ */
+
+/**
+ * Validate workflow schema
+ * @param {string} id - Workflow identifier
+ * @param {Object} content - Workflow definition
+ * @returns {boolean} True if valid
+ */
+export function validateWorkflow(id, content) {
+  if (!content.nodes || typeof content.nodes !== "object") {
+    console.error(`Invalid workflow ${id}: missing 'nodes' object`);
+    return false;
+  }
+  if (!content.edges || !Array.isArray(content.edges)) {
+    console.error(`Invalid workflow ${id}: missing 'edges' array`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * In-memory workflow store (stateless - no task storage)
+ */
+export class WorkflowStore {
+  constructor() {
+    this.workflows = new Map();
+  }
+
+  /**
+   * Load a workflow definition into the store
+   * @param {string} id - Workflow identifier
+   * @param {Object} workflow - Workflow definition
+   * @returns {string} The workflow id
+   */
+  loadDefinition(id, workflow) {
+    this.workflows.set(id, workflow);
+    return id;
+  }
+
+  /**
+   * Get a workflow definition by id
+   * @param {string} id - Workflow identifier
+   * @returns {Object|undefined} Workflow definition or undefined
+   */
+  getDefinition(id) {
+    return this.workflows.get(id);
+  }
+
+  /**
+   * List all loaded workflows with metadata
+   * @returns {Array} Array of workflow summaries
+   */
+  listWorkflows() {
+    return Array.from(this.workflows.entries()).map(([id, wf]) => ({
+      id,
+      name: wf.name || id,
+      description: wf.description || "",
+      stepCount: Object.keys(wf.nodes || {}).length,
+    }));
+  }
+
+  /**
+   * Check if a workflow exists
+   * @param {string} id - Workflow identifier
+   * @returns {boolean} True if workflow exists
+   */
+  has(id) {
+    return this.workflows.has(id);
+  }
+
+  /**
+   * Clear all workflows from the store
+   */
+  clear() {
+    this.workflows.clear();
+  }
+
+  /**
+   * Get the number of loaded workflows
+   * @returns {number} Workflow count
+   */
+  get size() {
+    return this.workflows.size;
+  }
+}

package/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Flow Workflow Type Definitions
+ *
+ * Normalized schema following standard flowchart conventions:
+ * - start: Entry point (exactly one)
+ * - end: Exit point with result classification
+ * - task: Work performed by agent
+ * - gate: Review/approval checkpoint
+ * - subflow: Connector to another workflow
+ */
+
+// =============================================================================
+// Node Types (Discriminated Union)
+// =============================================================================
+
+export type Node = StartNode | EndNode | TaskNode | GateNode | SubflowNode;
+
+export interface StartNode {
+  type: "start";
+  name?: string;
+  description?: string;
+}
+
+/**
+ * End node with result classification.
+ * - result: How the workflow concluded (success, failure, blocked, cancelled)
+ * - escalation: What action follows (hitl, alert, ticket) - optional
+ */
+export interface EndNode {
+  type: "end";
+  result: EndResult;
+  escalation?: Escalation;
+  name?: string;
+  description?: string;
+}
+
+export type EndResult = "success" | "failure" | "blocked" | "cancelled";
+export type Escalation = "hitl" | "alert" | "ticket";
+
+/**
+ * Task node - work performed by an agent.
+ * - outputs: Possible outcomes (default: ["passed", "failed"])
+ * - maxRetries: Retry count on failure before following "failed" edge
+ */
+export interface TaskNode {
+  type: "task";
+  name: string;
+  description?: string;
+  agent?: string;
+  stage?: Stage;
+  outputs?: string[];
+  maxRetries?: number;
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Gate node - review or approval checkpoint.
+ * Functionally similar to task but semantically different.
+ */
+export interface GateNode {
+  type: "gate";
+  name: string;
+  description?: string;
+  agent?: string;
+  stage?: Stage;
+  outputs?: string[];
+  maxRetries?: number;
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Subflow node - connector to another workflow.
+ */
+export interface SubflowNode {
+  type: "subflow";
+  workflow: string;
+  name?: string;
+  description?: string;
+  inputs?: Record<string, string>;
+}
+
+export type Stage = "planning" | "development" | "verification" | "delivery";
+
+// =============================================================================
+// Edge Definition
+// =============================================================================
+
+/**
+ * Directed edge connecting two nodes.
+ * - from/to: Node IDs
+ * - on: Output value that triggers this edge (for conditional routing)
+ * - label: Display text
+ */
+export interface Edge {
+  from: string;
+  to: string;
+  on?: string;
+  label?: string;
+}
+
+// =============================================================================
+// Workflow Definition
+// =============================================================================
+
+export interface Workflow {
+  id: string;
+  name: string;
+  description?: string;
+  nodes: Record<string, Node>;
+  edges: Edge[];
+}
+
+// =============================================================================
+// Engine Types
+// =============================================================================
+
+export interface EvaluationResult {
+  nextStep: string | null;
+  action: EdgeAction;
+  retriesUsed?: number;
+  retriesRemaining?: number;
+  maxRetries?: number;
+  edge?: Edge;
+  reason?: string;
+}
+
+export type EdgeAction =
+  | "unconditional" // Edge with no 'on' condition
+  | "conditional" // Edge matched 'on' condition
+  | "retry" // Failed but within retry limit, looping back
+  | "escalate" // Failed and exceeded retry limit
+  | "no_outgoing_edges" // Terminal node (no edges)
+  | "no_matching_edge"; // No edge matched the output