@opsee/mcp-server 0.8.1 → 0.8.3

package/src/tools/initiatives.ts

@@ -0,0 +1,321 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { overridePagination } from "../client/api.js";
+import {
+  formatInitiative,
+  formatInitiativeList,
+  formatInitiativeMemoryEntry,
+  formatInitiativeMemoryList,
+  formatInitiativeGraph,
+  formatInitiativeContext,
+  formatError,
+} from "../utils/format.js";
+
+const INITIATIVE_STATUSES = ["draft", "active", "paused", "completed", "abandoned"] as const;
+const ANCHOR_TYPES = ["none", "task", "milestone", "cycle"] as const;
+const MEMORY_KINDS = ["decision", "outcome", "learning", "blocker", "context"] as const;
+const MEMORY_SOURCE_TYPES = ["none", "task", "pull_request", "doc", "workflow"] as const;
+const EDGE_TYPES = ["blocks", "blocked_by", "duplicates", "relates_to"] as const;
+
+export function registerInitiativeTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_initiatives",
+    "List initiatives in an Opsee project.",
+    { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.initiatives.getInitiatives({
+          projectId,
+          pagination: overridePagination(),
+        });
+        return { content: [{ type: "text", text: formatInitiativeList(res.initiatives) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_initiative",
+    "Get details of a specific initiative by ID.",
+    { initiativeId: z.number().describe("The initiative ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ initiativeId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.initiatives.getInitiative({ id: initiativeId });
+        if (!res.initiative) return { content: [{ type: "text", text: "Initiative not found." }] };
+        return { content: [{ type: "text", text: formatInitiative(res.initiative) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_create_initiative",
+    "Create a new initiative in an Opsee project.",
+    {
+      projectId: z.number().describe("The project ID"),
+      title: z.string().describe("Initiative title"),
+      summary: z.string().optional().describe("Short summary of the initiative"),
+      status: z.enum(INITIATIVE_STATUSES).optional().describe("Initiative status. Defaults to 'draft'"),
+      anchorType: z.enum(ANCHOR_TYPES).optional().describe("Anchor type (none | task | milestone | cycle). Defaults to 'none'"),
+      anchorId: z.number().optional().describe("Anchor entity ID. Required when anchorType is not 'none'"),
+      coreIdea: z.string().optional().describe("Core idea body (the initiative's primary description). Markdown is supported and recommended — headings (##), bullets (-), checklists, code fences, **bold**/*italic*/`code`/links all render as formatted blocks in the UI (same behavior as task descriptions). Written as-is; the UI parses the markdown on read and re-saves it as BlockNote JSON on the next manual edit."),
+      coreIdeaContentType: z.string().optional().describe("Content type of coreIdea: 'text' (markdown — the default) or 'json' (BlockNote). Leave unset and just write markdown."),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, title, summary, status, anchorType, anchorId, coreIdea, coreIdeaContentType }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.initiatives.addInitiative({
+          projectId,
+          title,
+          summary,
+          status: status ?? "draft",
+          anchorType: anchorType ?? "none",
+          anchorId,
+          coreIdea,
+          coreIdeaContentType: coreIdeaContentType ?? "text",
+        });
+        if (!res.initiative)
+          return { content: [{ type: "text", text: "Failed to create initiative. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+        return {
+          content: [{ type: "text", text: `Initiative created:\n${formatInitiative(res.initiative)}` }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_update_initiative",
+    "Update an initiative's fields. Fetches the current initiative first, then applies only the provided changes.",
+    {
+      initiativeId: z.number().describe("The initiative ID to update"),
+      title: z.string().optional().describe("New title"),
+      summary: z.string().optional().describe("New summary"),
+      status: z.enum(INITIATIVE_STATUSES).optional().describe("New status"),
+      anchorType: z.enum(ANCHOR_TYPES).optional().describe("New anchor type"),
+      anchorId: z.number().optional().describe("New anchor entity ID"),
+      coreIdea: z.string().optional().describe("New core idea body. Markdown is supported and renders as formatted blocks in the UI (same as task descriptions)."),
+      coreIdeaContentType: z.string().optional().describe("Content type for coreIdea: 'text' (markdown — default) or 'json' (BlockNote)."),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ initiativeId, title, summary, status, anchorType, anchorId, coreIdea, coreIdeaContentType }) => {
+      try {
+        const clients = getClients();
+        const current = await clients.initiatives.getInitiative({ id: initiativeId });
+        if (!current.initiative)
+          return { content: [{ type: "text", text: "Initiative not found." }] };
+        const ini = current.initiative;
+        const res = await clients.initiatives.editInitiative({
+          id: initiativeId,
+          title: title ?? ini.title,
+          summary: summary !== undefined ? summary : ini.summary,
+          status: status ?? ini.status,
+          anchorType: anchorType ?? ini.anchorType,
+          anchorId: anchorId !== undefined ? anchorId : ini.anchorId,
+          coreIdea: coreIdea !== undefined ? coreIdea : ini.coreIdea,
+          coreIdeaContentType: coreIdeaContentType !== undefined ? coreIdeaContentType : ini.coreIdeaContentType,
+        });
+        if (!res.initiative)
+          return { content: [{ type: "text", text: "Failed to update initiative. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+        return {
+          content: [{ type: "text", text: `Initiative updated:\n${formatInitiative(res.initiative)}` }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_initiative",
+    "Delete an initiative permanently.",
+    { initiativeId: z.number().describe("The initiative ID to delete") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ initiativeId }) => {
+      try {
+        const clients = getClients();
+        await clients.initiatives.deleteInitiative({ id: initiativeId });
+        return { content: [{ type: "text", text: "Initiative deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_initiative_context",
+    "Load an entire Initiative work session in one call: the core-idea doc body, the execution task tree with parallel slices (what can run concurrently vs sequentially), the append-only memory log, and rolled-up PRs. Call this first when picking up or resuming work on an Initiative.",
+    {
+      initiativeId: z.number().describe("The initiative ID"),
+      memoryLimit: z.number().optional().describe("Cap on memory entries returned (most recent first); 0 or omitted = service default"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ initiativeId, memoryLimit }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.initiatives.getInitiativeContext({
+          initiativeId,
+          memoryLimit: memoryLimit ?? 0,
+        });
+        if (!res.initiative) return { content: [{ type: "text", text: "Initiative not found." }] };
+        const text = formatInitiativeContext(
+          res.initiative,
+          res.graph,
+          res.memoryEntries,
+          res.pullRequests,
+          res.comments,
+        );
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_initiative_graph",
+    "Get the task dependency graph for an initiative, including parallel execution batches (slices).",
+    { initiativeId: z.number().describe("The initiative ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ initiativeId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.initiatives.getInitiativeGraph({ initiativeId });
+        if (!res.graph) return { content: [{ type: "text", text: "No graph found for this initiative." }] };
+        return { content: [{ type: "text", text: formatInitiativeGraph(res.graph) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_decompose_initiative",
+    "Materialize a proposed breakdown as real Tasks under the Initiative in one atomic call. Wire the tree with temporary `ref` ids: set `parentRef` to nest a subtask, and add `edges` (from_ref blocks to_ref) to express sequencing — tasks with no blocking edge between them become parallel slices. All-or-nothing: a bad ref rolls the whole thing back.",
+    {
+      initiativeId: z.number().describe("The initiative ID"),
+      tasks: z.array(z.object({
+        ref: z.string().describe("Temporary reference ID used to wire edges and parent relationships"),
+        title: z.string().describe("Task title"),
+        description: z.string().optional().describe("Task description"),
+        parentRef: z.string().optional().describe("Ref of the parent task (to nest this as a subtask)"),
+        taskTypeId: z.number().optional().describe("Task type ID"),
+        taskPriorityId: z.number().optional().describe("Task priority ID"),
+        boardColumnId: z.number().optional().describe("Board column ID (status)"),
+      })).describe("Tasks to create under this initiative"),
+      edges: z.array(z.object({
+        fromRef: z.string().describe("Ref of the source task"),
+        toRef: z.string().describe("Ref of the target task"),
+        type: z.enum(EDGE_TYPES).describe("Dependency type: blocks | blocked_by | duplicates | relates_to"),
+      })).describe("Dependency edges between tasks (by ref)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ initiativeId, tasks, edges }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.initiatives.decomposeInitiative({
+          initiativeId,
+          tasks: tasks.map((t) => ({
+            ref: t.ref,
+            title: t.title,
+            description: t.description,
+            parentRef: t.parentRef,
+            taskTypeId: t.taskTypeId,
+            taskPriorityId: t.taskPriorityId,
+            boardColumnId: t.boardColumnId,
+          })),
+          edges: edges.map((e) => ({
+            fromRef: e.fromRef,
+            toRef: e.toRef,
+            type: e.type,
+          })),
+        });
+        const lines: string[] = [`Created ${res.createdTasks.length} task(s).`];
+        res.createdTasks.forEach((t, i) => {
+          lines.push(`  ${i + 1}. [${t.identifier || `#${t.id}`}] ${t.title} (ID: ${t.id})`);
+        });
+        if (res.graph) {
+          lines.push("\n" + formatInitiativeGraph(res.graph));
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_add_initiative_memory",
+    "Record a decision, outcome, learning, blocker, or context entry to the Initiative's append-only memory log. Agents should record here as they work, citing the source task or PR where relevant.",
+    {
+      initiativeId: z.number().describe("The initiative ID"),
+      kind: z.enum(MEMORY_KINDS).describe("Entry kind: decision | outcome | learning | blocker | context"),
+      body: z.string().describe("The memory entry body text"),
+      contentType: z.string().optional().describe("Content type of body (e.g. 'text'). Defaults to 'text'"),
+      sourceType: z.enum(MEMORY_SOURCE_TYPES).optional().describe("Source type: none | task | pull_request | doc | workflow. Defaults to 'none'"),
+      sourceId: z.number().optional().describe("ID of the source entity (task ID, PR ID, etc.)"),
+      sourceUrl: z.string().optional().describe("URL linking to the source"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ initiativeId, kind, body, contentType, sourceType, sourceId, sourceUrl }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.initiatives.addInitiativeMemoryEntry({
+          initiativeId,
+          kind,
+          body,
+          contentType: contentType ?? "text",
+          sourceType: sourceType ?? "none",
+          sourceId,
+          sourceUrl,
+        });
+        if (!res.memoryEntry)
+          return { content: [{ type: "text", text: "Failed to add memory entry. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+        return {
+          content: [{ type: "text", text: `Memory entry added:\n${formatInitiativeMemoryEntry(res.memoryEntry)}` }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_list_initiative_memory",
+    "List memory entries for an initiative (newest first). Optionally filter by kind, source type, or source ID.",
+    {
+      initiativeId: z.number().describe("The initiative ID"),
+      kinds: z.array(z.string()).optional().describe("Filter by entry kinds (decision | outcome | learning | blocker | context)"),
+      sourceType: z.string().optional().describe("Filter by source type (none | task | pull_request | doc | workflow)"),
+      sourceId: z.number().optional().describe("Filter by source entity ID"),
+    },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ initiativeId, kinds, sourceType, sourceId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.initiatives.getInitiativeMemory({
+          initiativeId,
+          kinds: kinds ?? [],
+          sourceType: sourceType ?? "",
+          sourceId,
+          pagination: overridePagination(),
+        });
+        return { content: [{ type: "text", text: formatInitiativeMemoryList(res.memoryEntries) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/tasks.ts

@@ -309,9 +309,10 @@ export function registerTaskTools(
       storyPoints: z.number().int().min(1).optional().describe("Story points estimate (positive integer)"),
       estimatedHours: z.number().min(0).optional().describe("Estimated effort in hours"),
       labelIds: z.array(z.number().int().min(0)).optional().describe("Replace this task's labels with this set. Omit to leave labels unchanged. Empty array clears all labels."),
+      initiativeId: z.number().int().min(0).optional().describe("Initiative ID to link this task to. >0 links the task to that Initiative, 0 detaches."),
     },
     { readOnlyHint: false, destructiveHint: false },
-    async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId, milestoneId, parentTaskId, storyPoints, estimatedHours, labelIds }) => {
+    async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId, milestoneId, parentTaskId, storyPoints, estimatedHours, labelIds, initiativeId }) => {
       try {
         const clients = getClients();
 
@@ -346,6 +347,7 @@ export function registerTaskTools(
           parentTaskId: parentTaskId ?? task.parentTaskId,
           repositoryIds: task.taskRepositories?.map((r: { id: number }) => r.id) ?? [],
           labelIds,
+          initiativeId: initiativeId !== undefined ? initiativeId : task.initiativeId,
         });
 
         if (!res.task)
@@ -570,6 +572,103 @@ export function registerTaskTools(
     },
   );
 
+  server.tool(
+    "opsee_link_task_to_initiative",
+    "Link an existing task to an Initiative. Fetches the task first so no other fields are blanked.",
+    {
+      taskId: z.number().describe("The task ID to link"),
+      initiativeId: z.number().int().min(1).describe("The initiative ID to link the task to"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, initiativeId }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.tasks.getTask({ id: taskId });
+        const task = getRes.task;
+        if (!task)
+          return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
+        const res = await clients.tasks.editTask({
+          id: task.id,
+          identifier: task.identifier,
+          title: task.title,
+          description: task.description,
+          displayOrder: task.displayOrder,
+          storyPoints: task.storyPoints,
+          estimatedHours: task.estimatedHours,
+          actualHours: task.actualHours,
+          dueDate: task.dueDate,
+          aiModeEnabled: task.aiModeEnabled,
+          metadataJson: task.metadataJson,
+          boardId: task.board?.id ?? 0,
+          boardColumnId: task.boardColumn?.id ?? 0,
+          projectId: task.project?.id ?? 0,
+          taskTypeId: task.taskType?.id ?? 0,
+          taskPriorityId: task.taskPriority?.id ?? 0,
+          reporterUserId: task.reporterUser?.id ?? 0,
+          assignedUserId: task.assignedUser?.id,
+          cycleId: task.cycle?.id,
+          milestoneId: task.milestoneId,
+          parentTaskId: task.parentTaskId,
+          repositoryIds: task.taskRepositories?.map((r: { id: number }) => r.id) ?? [],
+          initiativeId,
+        });
+        if (!res.task)
+          return { content: [{ type: "text", text: "Failed to link task. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+        return { content: [{ type: "text", text: `Task ${res.task.identifier} linked to initiative ${initiativeId}.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_unlink_task_from_initiative",
+    "Detach a task from its current Initiative. Fetches the task first so no other fields are blanked.",
+    {
+      taskId: z.number().describe("The task ID to unlink"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.tasks.getTask({ id: taskId });
+        const task = getRes.task;
+        if (!task)
+          return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
+        const res = await clients.tasks.editTask({
+          id: task.id,
+          identifier: task.identifier,
+          title: task.title,
+          description: task.description,
+          displayOrder: task.displayOrder,
+          storyPoints: task.storyPoints,
+          estimatedHours: task.estimatedHours,
+          actualHours: task.actualHours,
+          dueDate: task.dueDate,
+          aiModeEnabled: task.aiModeEnabled,
+          metadataJson: task.metadataJson,
+          boardId: task.board?.id ?? 0,
+          boardColumnId: task.boardColumn?.id ?? 0,
+          projectId: task.project?.id ?? 0,
+          taskTypeId: task.taskType?.id ?? 0,
+          taskPriorityId: task.taskPriority?.id ?? 0,
+          reporterUserId: task.reporterUser?.id ?? 0,
+          assignedUserId: task.assignedUser?.id,
+          cycleId: task.cycle?.id,
+          milestoneId: task.milestoneId,
+          parentTaskId: task.parentTaskId,
+          repositoryIds: task.taskRepositories?.map((r: { id: number }) => r.id) ?? [],
+          initiativeId: 0,
+        });
+        if (!res.task)
+          return { content: [{ type: "text", text: "Failed to unlink task. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+        return { content: [{ type: "text", text: `Task ${res.task.identifier} unlinked from initiative.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
   server.tool(
     "opsee_delete_task",
     "Delete a task by ID. This is permanent.",