@cliangdev/flux-plugin 0.2.0 → 0.3.0

package/src/server/tools/get-entity.ts

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import { toMcpEpic, toMcpPrd, toMcpTask } from "../utils/mcp-response.js";
+import {
+  type EntityType,
+  getValidTransitions,
+} from "../utils/status-transitions.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  ref: z.string().min(1, "Entity reference is required"),
+  include: z.array(z.string()).optional(),
+});
+
+function getEntityTypeInfo(ref: string): {
+  code: "P" | "E" | "T";
+  type: EntityType;
+} | null {
+  // Try Flux-style ref format first (e.g., FLUX-P1, FLUX-E2, FLUX-T3)
+  const match = ref.match(/-([PET])\d+$/);
+  if (match) {
+    const code = match[1] as "P" | "E" | "T";
+    const type: EntityType =
+      code === "P" ? "prd" : code === "E" ? "epic" : "task";
+    return { code, type };
+  }
+  // For other ref formats (e.g., Linear: CAL-10), return null to indicate
+  // we need to try each entity type
+  return null;
+}
+
+// Valid includes per entity type - now returns summaries, not full data
+const VALID_INCLUDES: Record<string, string[]> = {
+  P: ["epics", "tasks", "criteria", "dependencies"],
+  E: ["tasks", "criteria", "dependencies"],
+  T: ["criteria", "dependencies"],
+};
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+  const adapter = getAdapter();
+
+  const typeInfo = getEntityTypeInfo(parsed.ref);
+  const includes = parsed.include || [];
+
+  // If ref format is unknown (e.g., Linear refs like CAL-10), try each entity type
+  let entityCode: "P" | "E" | "T";
+  let entityType: EntityType;
+
+  if (typeInfo) {
+    entityCode = typeInfo.code;
+    entityType = typeInfo.type;
+  } else {
+    // Try PRD first, then Epic, then Task
+    const prd = await adapter.getPrd(parsed.ref);
+    if (prd) {
+      entityCode = "P";
+      entityType = "prd";
+    } else {
+      const epic = await adapter.getEpic(parsed.ref);
+      if (epic) {
+        entityCode = "E";
+        entityType = "epic";
+      } else {
+        const task = await adapter.getTask(parsed.ref);
+        if (task) {
+          entityCode = "T";
+          entityType = "task";
+        } else {
+          throw new Error(`Entity not found: ${parsed.ref}`);
+        }
+      }
+    }
+  }
+
+  const validIncludes = VALID_INCLUDES[entityCode];
+  let result: Record<string, unknown>;
+
+  if (entityCode === "P") {
+    const prd = await adapter.getPrd(parsed.ref);
+    if (!prd) throw new Error(`Entity not found: ${parsed.ref}`);
+
+    result = { ...toMcpPrd(prd) };
+
+    // Add available status transitions
+    result.available_transitions = getValidTransitions(entityType, prd.status);
+
+    // Always include dependencies by default
+    const deps = await adapter.getDependencies(parsed.ref);
+    result.dependencies = deps;
+
+    // Process includes
+    for (const inc of includes) {
+      if (!validIncludes.includes(inc)) continue;
+
+      if (inc === "epics") {
+        const epicsResult = await adapter.listEpics(
+          { prdRef: parsed.ref },
+          { limit: 100 },
+        );
+        result.epics = epicsResult.items.map((e) => ({
+          ref: e.ref,
+          title: e.title,
+          status: e.status,
+        }));
+        result.epic_count = epicsResult.total;
+      }
+
+      if (inc === "tasks") {
+        // Get tasks via epics
+        const epicsResult = await adapter.listEpics(
+          { prdRef: parsed.ref },
+          { limit: 100 },
+        );
+        const taskRefs: { ref: string; title: string; status: string }[] = [];
+        for (const epic of epicsResult.items) {
+          const tasksResult = await adapter.listTasks(
+            { epicRef: epic.ref },
+            { limit: 100 },
+          );
+          taskRefs.push(
+            ...tasksResult.items.map((t) => ({
+              ref: t.ref,
+              title: t.title,
+              status: t.status,
+            })),
+          );
+        }
+        result.tasks = taskRefs;
+        result.task_count = taskRefs.length;
+      }
+
+      if (inc === "criteria") {
+        // PRD: get criteria count from epics and tasks
+        const epicsResult = await adapter.listEpics(
+          { prdRef: parsed.ref },
+          { limit: 100 },
+        );
+        let totalCriteria = 0;
+        let metCriteria = 0;
+        for (const epic of epicsResult.items) {
+          const epicCriteria = await adapter.getCriteria(epic.ref);
+          totalCriteria += epicCriteria.length;
+          metCriteria += epicCriteria.filter((c) => c.isMet).length;
+
+          const tasksResult = await adapter.listTasks(
+            { epicRef: epic.ref },
+            { limit: 100 },
+          );
+          for (const task of tasksResult.items) {
+            const taskCriteria = await adapter.getCriteria(task.ref);
+            totalCriteria += taskCriteria.length;
+            metCriteria += taskCriteria.filter((c) => c.isMet).length;
+          }
+        }
+        result.criteria_count = totalCriteria;
+        result.criteria_met = metCriteria;
+      }
+    }
+
+    // Add hint for PRDs about where to find full content
+    if (prd.folderPath) {
+      result.content_hint =
+        "Use Read tool on folder_path + '/prd.md' for full PRD content";
+    }
+  } else if (entityCode === "E") {
+    const epic = await adapter.getEpic(parsed.ref);
+    if (!epic) throw new Error(`Entity not found: ${parsed.ref}`);
+
+    result = { ...toMcpEpic(epic) };
+    result.available_transitions = getValidTransitions(entityType, epic.status);
+
+    // Always include dependencies by default
+    const deps = await adapter.getDependencies(parsed.ref);
+    result.dependencies = deps;
+
+    for (const inc of includes) {
+      if (!validIncludes.includes(inc)) continue;
+
+      if (inc === "tasks") {
+        const tasksResult = await adapter.listTasks(
+          { epicRef: parsed.ref },
+          { limit: 100 },
+        );
+        result.tasks = tasksResult.items.map((t) => ({
+          ref: t.ref,
+          title: t.title,
+          status: t.status,
+        }));
+        result.task_count = tasksResult.total;
+      }
+
+      if (inc === "criteria") {
+        const criteria = await adapter.getCriteria(parsed.ref);
+        result.criteria = criteria.map((c) => ({
+          id: c.id,
+          criteria: c.criteria,
+          is_met: c.isMet,
+        }));
+        result.criteria_count = criteria.length;
+        result.criteria_met = criteria.filter((c) => c.isMet).length;
+      }
+    }
+  } else {
+    const task = await adapter.getTask(parsed.ref);
+    if (!task) throw new Error(`Entity not found: ${parsed.ref}`);
+
+    result = { ...toMcpTask(task) };
+    result.available_transitions = getValidTransitions(entityType, task.status);
+
+    // Always include dependencies by default
+    const deps = await adapter.getDependencies(parsed.ref);
+    result.dependencies = deps;
+
+    for (const inc of includes) {
+      if (!validIncludes.includes(inc)) continue;
+
+      if (inc === "criteria") {
+        const criteria = await adapter.getCriteria(parsed.ref);
+        result.criteria = criteria.map((c) => ({
+          id: c.id,
+          criteria: c.criteria,
+          is_met: c.isMet,
+        }));
+        result.criteria_count = criteria.length;
+        result.criteria_met = criteria.filter((c) => c.isMet).length;
+      }
+    }
+  }
+
+  return result;
+}
+
+export const getEntityTool: ToolDefinition = {
+  name: "get_entity",
+  description:
+    "Get a single entity by reference with optional summaries. Required: ref (e.g., 'FLUX-P1'). Optional: include array - PRD: ['epics','tasks','criteria','dependencies'], Epic: ['tasks','criteria','dependencies'], Task: ['criteria','dependencies']. Returns entity with available_transitions (valid next statuses), counts, and refs. For PRDs, use Read tool on folder_path + '/prd.md' for full content.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/get-linear-url.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import type { LinearAdapter } from "../adapters/linear/adapter.js";
+import { linearConfigExists } from "../adapters/linear/config.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({
+  ref: z.string().min(1, "Entity ref is required"),
+});
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+
+  if (!linearConfigExists()) {
+    throw new Error("Linear not configured. Run configure_linear first.");
+  }
+
+  const adapter = getAdapter() as LinearAdapter;
+  return adapter.getLinearUrl(parsed.ref);
+}
+
+export const getLinearUrlTool: ToolDefinition = {
+  name: "get_linear_url",
+  description:
+    "Get the Linear web URL for any entity ref. Required: ref (project ID like 'proj_abc123' or issue identifier like 'ENG-42'). Returns {url, type, name/identifier}.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/get-stats.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { getAdapter } from "../adapters/index.js";
+import { toMcpStats } from "../utils/mcp-response.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({});
+
+// Re-export interface for backward compatibility with render-status.ts
+export interface ProjectStats {
+  prds: {
+    total: number;
+    draft: number;
+    approved: number;
+    completed: number;
+    archived: number;
+  };
+  epics: {
+    total: number;
+    pending: number;
+    in_progress: number;
+    completed: number;
+  };
+  tasks: {
+    total: number;
+    pending: number;
+    in_progress: number;
+    completed: number;
+  };
+}
+
+/**
+ * Compute project statistics using the adapter.
+ * Returns MCP-formatted stats (snake_case).
+ * This is exported for use by render-status.ts
+ */
+export async function computeStats(): Promise<ProjectStats> {
+  const adapter = getAdapter();
+  const stats = await adapter.getStats();
+  return toMcpStats(stats);
+}
+
+async function handler(_input: unknown) {
+  return computeStats();
+}
+
+export const getStatsTool: ToolDefinition = {
+  name: "get_stats",
+  description:
+    "Get aggregated project statistics. No parameters. Returns counts by status: {prds: {total, draft, approved, completed, archived}, epics: {total, pending, in_progress, completed}, tasks: {total, pending, in_progress, completed}}. Note: totals exclude archived PRDs and their epics/tasks. The archived count shows how many PRDs are archived.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/get-version.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { VERSION } from "../../version.js";
+import type { ToolDefinition } from "./index.js";
+
+const inputSchema = z.object({});
+
+async function handler(_input: unknown) {
+  return {
+    version: VERSION,
+    name: "flux-plugin",
+  };
+}
+
+export const getVersionTool: ToolDefinition = {
+  name: "get_version",
+  description:
+    "Get Flux plugin version information. No parameters required. Returns {version: string, name: 'flux-plugin'}.",
+  inputSchema,
+  handler,
+};

package/src/server/tools/index.ts

@@ -0,0 +1,158 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { config } from "../config.js";
+import { logger } from "../utils/logger.js";
+
+const TOOLS_WITHOUT_PROJECT = ["init_project", "get_version"];
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: z.ZodType;
+  handler: (input: unknown) => Promise<unknown>;
+}
+
+export interface ToolError {
+  error: true;
+  message: string;
+  code: string;
+}
+
+export interface ProjectNotInitializedError extends ToolError {
+  code: "PROJECT_NOT_INITIALIZED";
+  setup: {
+    instructions: string;
+    options: Array<{
+      method: "command" | "tool";
+      name: string;
+      description: string;
+      params?: Record<string, string>;
+    }>;
+  };
+}
+
+export function createError(message: string, code: string): ToolError {
+  return { error: true, message, code };
+}
+
+export function createProjectNotInitializedError(
+  cwd: string,
+  projectRoot: string,
+): ProjectNotInitializedError {
+  return {
+    error: true,
+    code: "PROJECT_NOT_INITIALIZED",
+    message: `No Flux project found. Current directory: ${cwd}, resolved project root: ${projectRoot}`,
+    setup: {
+      instructions:
+        "Initialize a Flux project before using Flux tools. Use one of the following options:",
+      options: [
+        {
+          method: "command",
+          name: "/flux",
+          description:
+            "Interactive setup with guided prompts (recommended for first-time setup)",
+        },
+        {
+          method: "tool",
+          name: "init_project",
+          description: "Direct initialization via MCP tool",
+          params: {
+            name: "Project name (required)",
+            vision: "Brief project description (required)",
+            adapter: "local | linear (default: local)",
+          },
+        },
+      ],
+    },
+  };
+}
+
+export function registerTools(server: Server, tools: ToolDefinition[]) {
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: z.toJSONSchema(t.inputSchema),
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    logger.debug(`Calling tool: ${toolName}`, request.params.arguments);
+
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+      logger.error(`Unknown tool: ${toolName}`);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              createError(`Unknown tool: ${toolName}`, "UNKNOWN_TOOL"),
+            ),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    if (!TOOLS_WITHOUT_PROJECT.includes(toolName) && !config.projectExists) {
+      const error = createProjectNotInitializedError(
+        process.cwd(),
+        config.projectRoot,
+      );
+      logger.error(error.message);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(error, null, 2),
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    try {
+      const result = await tool.handler(request.params.arguments);
+      logger.debug(`Tool ${toolName} completed successfully`);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      logger.error(`Tool ${toolName} failed: ${message}`);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(createError(message, "TOOL_ERROR")),
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+}
+
+export { configureLinearTool } from "./configure-linear.js";
+export { createEpicTool } from "./create-epic.js";
+export { createPrdTool } from "./create-prd.js";
+export { createTaskTool } from "./create-task.js";
+export { addCriteriaTool, markCriteriaMetTool } from "./criteria.js";
+export { deleteEntityTool } from "./delete-entity.js";
+export { addDependencyTool, removeDependencyTool } from "./dependencies.js";
+export { getEntityTool } from "./get-entity.js";
+export { getLinearUrlTool } from "./get-linear-url.js";
+export { getStatsTool } from "./get-stats.js";
+export { getVersionTool } from "./get-version.js";
+export { initProjectTool } from "./init-project.js";
+export { queryEntitiesTool } from "./query-entities.js";
+export { renderStatusTool } from "./render-status.js";
+export { updateEntityTool } from "./update-entity.js";
+export { updateStatusTool } from "./update-status.js";

package/src/server/tools/init-project.ts

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import type { AdapterConfig } from "../adapters/types.js";
+import { config } from "../config.js";
+import {
+  generateId,
+  generatePrefix,
+  getDb,
+  initDb,
+  insert,
+} from "../db/index.js";
+import type { ToolDefinition } from "./index.js";
+
+function getStatusLineBinaryPath(): string {
+  const thisDir = dirname(new URL(import.meta.url).pathname);
+  return join(thisDir, "..", "..", "..", "bin", "flux-status");
+}
+
+function setupClaudeSettings(projectRoot: string): void {
+  const claudeDir = join(projectRoot, ".claude");
+  const settingsPath = join(claudeDir, "settings.local.json");
+  const statusBinaryPath = getStatusLineBinaryPath();
+
+  if (!existsSync(statusBinaryPath)) {
+    return;
+  }
+
+  if (!existsSync(claudeDir)) {
+    mkdirSync(claudeDir, { recursive: true });
+  }
+
+  let settings: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    } catch {
+      settings = {};
+    }
+  }
+
+  if (!settings.statusLine) {
+    settings.statusLine = {
+      type: "command",
+      command: statusBinaryPath,
+    };
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+  }
+}
+
+const adapterTypes = ["local", "specflux", "linear", "notion"] as const;
+
+const inputSchema = z.object({
+  name: z.string().min(1, "Project name is required"),
+  vision: z.string().min(1, "Project vision is required"),
+  adapter: z.enum(adapterTypes).optional().default("local"),
+});
+
+async function handler(input: unknown) {
+  const parsed = inputSchema.parse(input);
+
+  if (existsSync(config.fluxPath)) {
+    throw new Error("Flux project already initialized in this directory");
+  }
+
+  mkdirSync(config.fluxPath, { recursive: true });
+
+  const refPrefix = generatePrefix(parsed.name);
+  const adapterConfig: AdapterConfig = { type: parsed.adapter };
+
+  const projectJson = {
+    name: parsed.name,
+    vision: parsed.vision,
+    ref_prefix: refPrefix,
+    project_root: config.projectRoot,
+    adapter: adapterConfig,
+    created_at: new Date().toISOString(),
+  };
+
+  writeFileSync(config.projectJsonPath, JSON.stringify(projectJson, null, 2));
+  config.clearCache();
+
+  initDb();
+
+  const projectId = generateId("proj");
+  const db = getDb();
+  insert(db, "projects", {
+    id: projectId,
+    name: parsed.name,
+    ref_prefix: refPrefix,
+  });
+
+  setupClaudeSettings(config.projectRoot);
+
+  return {
+    success: true,
+    project: projectJson,
+    message: `Flux project initialized. Run /flux:prd to start planning.`,
+  };
+}
+
+export const initProjectTool: ToolDefinition = {
+  name: "init_project",
+  description:
+    "Initialize a new Flux project. Required: name, vision. Optional: adapter (local|specflux|linear|notion, default 'local'). Creates .flux/ directory with project.json and SQLite database. Returns {success, project, message}. Fails if .flux/ already exists.",
+  inputSchema,
+  handler,
+};