@opsee/mcp-server 0.9.31 → 0.9.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsee/mcp-server",
-  "version": "0.9.31",
+  "version": "0.9.33",
   "description": "Opsee MCP server — manage projects, tasks, docs, and cycles from AI coding environments",
   "type": "module",
   "bin": {

package/src/__tests__/blocknote-fixtures.test.ts

@@ -0,0 +1,58 @@
+import { describe, test, expect } from "vitest";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { blockNoteToMarkdown } from "../utils/format.js";
+
+// The BlockNote <-> markdown mapping is implemented three times against no
+// shared contract: this reader, orchestrator/internal/util/blocknote.go, and
+// the frontend BlockEditor via @blocknote/core. testdata/blocknote is the
+// language-neutral fixture set all three should eventually assert against;
+// this suite pins the TypeScript side of it.
+const FIXTURE_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../testdata/blocknote");
+
+interface Fixture {
+  name: string;
+  description: string;
+  /** Stored value when it is BlockNote JSON. Serialized before rendering. */
+  blocknote?: unknown[];
+  /** Stored value when it is not BlockNote JSON, passed through verbatim. */
+  input?: string;
+  markdown: string;
+}
+
+const fixtures = readdirSync(FIXTURE_DIR)
+  .filter((f) => f.endsWith(".json"))
+  .sort()
+  .map((f) => JSON.parse(readFileSync(join(FIXTURE_DIR, f), "utf8")) as Fixture);
+
+describe("blockNoteToMarkdown golden fixtures", () => {
+  // Naming the cases rather than counting them: a suite whose whole job is to
+  // catch drift must fail, not vacuously pass, if the fixtures go missing.
+  test("covers every construct the task-description contract promises", () => {
+    expect(fixtures.map((f) => f.name).sort()).toEqual([
+      "block-separation",
+      "checklist",
+      "code-fence",
+      "empty-document",
+      "heading-level-clamp",
+      "headings",
+      "inline-styles",
+      "links",
+      "nested-bullets",
+      "passthrough-malformed-block",
+      "passthrough-non-array-json",
+      "passthrough-plain-text",
+      "task-description",
+    ]);
+  });
+
+  for (const fixture of fixtures) {
+    test(`${fixture.name}: ${fixture.description}`, () => {
+      const isBlockNote = fixture.blocknote !== undefined;
+      expect(isBlockNote || typeof fixture.input === "string").toBe(true);
+      const stored = isBlockNote ? JSON.stringify(fixture.blocknote) : fixture.input!;
+      expect(blockNoteToMarkdown(stored)).toBe(fixture.markdown);
+    });
+  }
+});

package/src/tools/descriptions.ts

@@ -0,0 +1,25 @@
+/**
+ * Description strings shared by more than one tool or schema field.
+ *
+ * These are LLM-facing contract text: an agent picks a tool and fills its
+ * arguments from nothing but this wording. Copies that drift teach two
+ * different contracts for the same field, so anything repeated lives here.
+ */
+
+/** Task/description authoring rules. Shared by create and update. */
+export const TASK_DESCRIPTION_GUIDANCE =
+  "Markdown is supported — headings (##), bullets (-), code fences, inline **bold** / *italic* / `code` / links all render as proper formatted blocks in the UI. For ACCEPTANCE CRITERIA, write them inline in this description as a `## Acceptance criteria` heading followed by markdown checkbox lines: `- [ ] criterion text` and `- [x] done item`. The UI renders those as clickable checkboxes (BlockNote checkListItem) and users can toggle them. Do NOT use the structured opsee_add_acceptance_criterion tool for typical AC — it writes to a separate DB table that does not surface in the task detail UI; it's reserved for automation paths (PR-to-criterion mapping etc.). Written as-is to the backend; the frontend BlockEditor parses markdown on read and saves the parsed BlockNote JSON on the next edit, so the round-trip preserves structure.";
+
+export const CREATE_TASK_DESCRIPTION = `Task description. ${TASK_DESCRIPTION_GUIDANCE}`;
+
+export const UPDATE_TASK_DESCRIPTION = `New description. ${TASK_DESCRIPTION_GUIDANCE}`;
+
+export const BULK_PROJECT_ID = "Project ID - all tasks must belong to this project";
+
+export const STORY_POINTS_ESTIMATE = "Story points estimate (positive integer)";
+
+export const INITIATIVE_TASK_REF = "Temporary reference ID used to wire edges and parent relationships";
+
+export const INITIATIVE_TASK_PARENT_REF = "Ref of the parent task (to nest this as a subtask)";
+
+export const INITIATIVE_EDGE_TYPE = "Dependency type: blocks | blocked_by | duplicates | relates_to";

package/src/tools/initiatives.ts

@@ -12,6 +12,11 @@ import {
   formatReconcileChangeset,
   formatError,
 } from "../utils/format.js";
+import {
+  INITIATIVE_EDGE_TYPE,
+  INITIATIVE_TASK_PARENT_REF,
+  INITIATIVE_TASK_REF,
+} from "./descriptions.js";
 
 const INITIATIVE_STATUSES = ["draft", "active", "paused", "completed", "abandoned"] as const;
 const ANCHOR_TYPES = ["none", "task", "milestone", "cycle"] as const;
@@ -212,10 +217,10 @@ export function registerInitiativeTools(
     {
       initiativeId: z.number().int().min(1).describe("The initiative ID"),
       tasks: z.array(z.object({
-        ref: z.string().describe("Temporary reference ID used to wire edges and parent relationships"),
+        ref: z.string().describe(INITIATIVE_TASK_REF),
         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)"),
+        parentRef: z.string().optional().describe(INITIATIVE_TASK_PARENT_REF),
         taskTypeId: z.number().int().min(1).optional().describe("Task type ID"),
         taskPriorityId: z.number().int().min(1).optional().describe("Task priority ID"),
         boardColumnId: z.number().int().min(1).optional().describe("Board column ID (status)"),
@@ -223,7 +228,7 @@ export function registerInitiativeTools(
       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"),
+        type: z.enum(EDGE_TYPES).describe(INITIATIVE_EDGE_TYPE),
       })).describe("Dependency edges between tasks (by ref)"),
     },
     { readOnlyHint: false, destructiveHint: false },
@@ -283,10 +288,10 @@ export function registerInitiativeTools(
     {
       initiativeId: z.number().int().min(1).describe("The initiative ID"),
       tasks: z.array(z.object({
-        ref: z.string().describe("Temporary reference ID used to wire edges and parent relationships"),
+        ref: z.string().describe(INITIATIVE_TASK_REF),
         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)"),
+        parentRef: z.string().optional().describe(INITIATIVE_TASK_PARENT_REF),
         taskTypeId: z.number().int().min(1).optional().describe("Task type ID"),
         taskPriorityId: z.number().int().min(1).optional().describe("Task priority ID"),
         boardColumnId: z.number().int().min(1).optional().describe("Board column ID (status)"),
@@ -295,7 +300,7 @@ export function registerInitiativeTools(
       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"),
+        type: z.enum(EDGE_TYPES).describe(INITIATIVE_EDGE_TYPE),
       })).describe("Dependency edges between tasks (by ref)"),
       dryRun: z.boolean().optional().describe("When true, compute and return the changeset without writing anything. Always call with dryRun:true first to preview."),
     },

package/src/tools/tasks-bulk.ts

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { formatError } from "../utils/format.js";
+import { BULK_PROJECT_ID } from "./descriptions.js";
+
+// Multi-task edits. All of these go through the backend BulkEditTasks RPC,
+// which applies every change in one transaction and silently skips task ids
+// the caller cannot see - hence the "n of m" wording in every response.
+export function registerTaskBulkTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_bulk_update_tasks",
+    "Atomicity: backend wraps all updates in one DB transaction. Per-task lookup failures (task not visible to your company, or unknown ID) are silently skipped — compare updated_count against taskIds.length to detect partial application. Omitted fields are not touched. labelIds with a non-empty list replaces each task's labels; empty/omitted leaves them alone.",
+    {
+      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
+      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to update (at least one)"),
+      boardColumnId: z.number().int().min(1).optional().describe("New board column ID (status)"),
+      taskPriorityId: z.number().int().min(1).optional().describe("New priority ID"),
+      taskTypeId: z.number().int().min(1).optional().describe("New task type ID"),
+      assignedUserId: z.number().int().min(1).optional().describe("New assigned user ID"),
+      cycleId: z.number().int().min(1).optional().describe("New cycle/sprint ID"),
+      milestoneId: z.number().int().min(1).optional().describe("Milestone ID to attach every task to. Bulk only supports set, not clear — use opsee_update_task for detaching a single task."),
+      storyPoints: z.number().int().min(1).optional().describe("Story points to set on every task"),
+      estimatedHours: z.number().min(0).optional().describe("Estimated hours to set on every task"),
+      parentTaskId: z.number().int().min(0).optional().describe("Parent task ID for every task (pass 0 to clear)"),
+      labelIds: z.array(z.number().int().min(1)).optional().describe("Replace label attachments on every task with this set. Empty / omitted leaves labels untouched."),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, boardColumnId, taskPriorityId, taskTypeId, assignedUserId, cycleId, milestoneId, storyPoints, estimatedHours, parentTaskId, labelIds }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          boardColumnId,
+          taskPriorityId,
+          taskTypeId,
+          assignedUserId,
+          cycleId,
+          milestoneId,
+          storyPoints,
+          estimatedHours,
+          parentTaskId,
+          repositoryIds: [],
+          labelIds: labelIds ?? [],
+        });
+
+        const requested = taskIds.length;
+        const updated = res.updatedCount;
+        let text = `Updated ${updated} of ${requested} task(s).`;
+        if (updated < requested) {
+          text += " (Tasks not visible to your company or not found were skipped.)";
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_move_to_cycle",
+    "Convenience wrapper: move many tasks to the same cycle in one call. Equivalent to opsee_bulk_update_tasks with only cycleId set.",
+    {
+      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
+      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to move"),
+      cycleId: z.number().int().min(1).describe("Target cycle/sprint ID"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, cycleId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          cycleId,
+          repositoryIds: [],
+          labelIds: [],
+        });
+        const text = `Moved ${res.updatedCount} of ${taskIds.length} task(s) to cycle ${cycleId}.`;
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_move_to_column",
+    "Convenience wrapper: move many tasks to the same board column (status) in one call.",
+    {
+      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
+      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to move"),
+      boardColumnId: z.number().int().min(1).describe("Target board column ID (status)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, boardColumnId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          boardColumnId,
+          repositoryIds: [],
+          labelIds: [],
+        });
+        const text = `Moved ${res.updatedCount} of ${taskIds.length} task(s) to column ${boardColumnId}.`;
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_assign",
+    "Convenience wrapper: assign many tasks to the same user in one call.",
+    {
+      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
+      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to reassign"),
+      assigneeId: z.number().int().min(1).describe("Target user ID"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, assigneeId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          assignedUserId: assigneeId,
+          repositoryIds: [],
+          labelIds: [],
+        });
+        const text = `Assigned ${res.updatedCount} of ${taskIds.length} task(s) to user ${assigneeId}.`;
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_set_priority",
+    "Convenience wrapper: set the same priority on many tasks in one call.",
+    {
+      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
+      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to reprioritize"),
+      priorityId: z.number().int().min(1).describe("Target priority ID (from opsee_list_task_priorities)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, taskIds, priorityId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkEditTasks({
+          projectId,
+          taskIds,
+          taskPriorityId: priorityId,
+          repositoryIds: [],
+          labelIds: [],
+        });
+        const text = `Set priority ${priorityId} on ${res.updatedCount} of ${taskIds.length} task(s).`;
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/tasks-delete.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { formatError } from "../utils/format.js";
+import { BULK_PROJECT_ID } from "./descriptions.js";
+
+// Task deletion, single and bulk.
+export function registerTaskDeleteTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_delete_task",
+    "Delete a task by ID. This is permanent.",
+    { taskId: z.number().int().min(1).describe("The task ID to delete") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ taskId }) => {
+      try {
+        const clients = getClients();
+        await clients.tasks.deleteTask({ id: taskId });
+        return { content: [{ type: "text", text: "Task deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_bulk_delete_tasks",
+    "Delete multiple tasks in one call. Tasks not visible to your company or not found are silently skipped — compare deletedCount against taskIds.length to detect partial application. This is permanent.",
+    {
+      projectId: z.number().int().min(1).describe(BULK_PROJECT_ID),
+      taskIds: z.array(z.number().int().min(1)).min(1).describe("Task IDs to delete (at least one)"),
+    },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ projectId, taskIds }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.bulkDeleteTasks({ projectId, taskIds });
+        const requested = taskIds.length;
+        const deleted = res.deletedCount;
+        let text = `Deleted ${deleted} of ${requested} task(s).`;
+        if (deleted < requested) {
+          text += " (Tasks not visible to your company or not found were skipped.)";
+        }
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}