@opsee/mcp-server 0.9.14 → 0.9.17

package/src/tools/tasks.ts

@@ -25,10 +25,10 @@ export function registerTaskTools(
     "opsee_list_tasks",
     "List tasks in an Opsee project. Supports filtering by status, assignee, board column, cycle, labels, priority, type, milestone, parent, due date, and update/create recency. labelIds uses AND semantics; multi-id filters (priorityIds/taskTypeIds/milestoneIds) use OR semantics. Supports sorting via sortBy (created_at|updated_at|due_date|priority|title|id|display_order) and sortDir (asc|desc).",
     {
-      projectId: z.number().describe("The project ID"),
-      columnId: z.number().optional().describe("Filter by board column ID (status)"),
-      assigneeId: z.number().optional().describe("Filter by assigned user ID"),
-      cycleId: z.number().optional().describe("Filter by cycle/sprint ID"),
+      projectId: z.number().int().min(1).describe("The project ID"),
+      columnId: z.number().int().min(1).optional().describe("Filter by board column ID (status)"),
+      assigneeId: z.number().int().min(1).optional().describe("Filter by assigned user ID"),
+      cycleId: z.number().int().min(1).optional().describe("Filter by cycle/sprint ID"),
       labelIds: z.array(z.number().int().min(1)).optional().describe("Filter by label IDs (AND semantics — task must have all listed labels)"),
       priorityIds: z.array(z.number().int().min(1)).optional().describe("Filter by one or more priority IDs (OR semantics)"),
       taskTypeIds: z.array(z.number().int().min(1)).optional().describe("Filter by one or more task type IDs (OR semantics)"),
@@ -42,8 +42,8 @@ export function registerTaskTools(
       dueAfter: z.string().optional().describe("Only tasks due at or after this date (RFC3339 or YYYY-MM-DD)"),
       sortBy: z.enum(["created_at", "updated_at", "due_date", "priority", "title", "id", "display_order"]).optional().describe("Sort column. NULLs sort last."),
       sortDir: z.enum(["asc", "desc"]).optional().describe("Sort direction (default: desc)"),
-      page: z.number().optional().describe("Page number (default: 1)"),
-      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+      page: z.number().int().min(1).optional().describe("Page number (default: 1)"),
+      pageSize: z.number().int().min(1).optional().describe("Items per page (default: 50)"),
     },
     { readOnlyHint: true, destructiveHint: false },
     async ({
@@ -109,7 +109,7 @@ export function registerTaskTools(
   server.tool(
     "opsee_get_task",
     "Get full details of a specific task by ID.",
-    { taskId: z.number().describe("The task ID") },
+    { taskId: z.number().int().min(1).describe("The task ID") },
     { readOnlyHint: true, destructiveHint: false },
     async ({ taskId }) => {
       try {
@@ -126,7 +126,7 @@ export function registerTaskTools(
   server.tool(
     "opsee_get_task_with_context",
     "One-shot composer that returns a task plus all its related context: labels, comments, dependencies (both directions), parent task, and subtasks. Use this when picking up a ticket — saves ~5 round-trips compared to calling each tool separately.",
-    { taskId: z.number().describe("The task ID") },
+    { taskId: z.number().int().min(1).describe("The task ID") },
     { readOnlyHint: true, destructiveHint: false },
     async ({ taskId }) => {
       try {
@@ -189,14 +189,14 @@ export function registerTaskTools(
     "opsee_create_task",
     "Create a new task in an Opsee project. Use opsee_list_task_types, opsee_list_task_priorities, and opsee_list_board_columns first to get valid values for optional fields.",
     {
-      projectId: z.number().describe("The project ID"),
+      projectId: z.number().int().min(1).describe("The project ID"),
       title: z.string().describe("Task title"),
       description: z.string().optional().describe("Task description. 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."),
-      taskTypeId: z.number().optional().describe("Task type ID (from opsee_list_task_types)"),
-      priorityId: z.number().optional().describe("Priority ID (from opsee_list_task_priorities)"),
-      boardColumnId: z.number().optional().describe("Board column ID (from opsee_list_board_columns)"),
-      assigneeId: z.number().optional().describe("Assigned user ID"),
-      cycleId: z.number().optional().describe("Cycle/sprint ID"),
+      taskTypeId: z.number().int().min(1).optional().describe("Task type ID (from opsee_list_task_types)"),
+      priorityId: z.number().int().min(1).optional().describe("Priority ID (from opsee_list_task_priorities)"),
+      boardColumnId: z.number().int().min(1).optional().describe("Board column ID (from opsee_list_board_columns)"),
+      assigneeId: z.number().int().min(1).optional().describe("Assigned user ID"),
+      cycleId: z.number().int().min(1).optional().describe("Cycle/sprint ID"),
       milestoneId: z.number().int().min(1).optional().describe("Milestone ID — attaches this task to the milestone."),
       parentTaskId: z.number().int().min(1).optional().describe("Parent task ID — makes this task a subtask of the given task."),
       storyPoints: z.number().int().min(1).optional().describe("Story points estimate (positive integer)"),
@@ -296,14 +296,14 @@ export function registerTaskTools(
     "opsee_update_task",
     "Update a task's fields (patch semantics - only provided fields are changed). Fetches the current task first, merges your changes, and sends the full update.",
     {
-      taskId: z.number().describe("The task ID to update"),
+      taskId: z.number().int().min(1).describe("The task ID to update"),
       title: z.string().optional().describe("New title"),
       description: z.string().optional().describe("New description. 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."),
-      taskTypeId: z.number().optional().describe("New task type ID"),
-      priorityId: z.number().optional().describe("New priority ID"),
-      boardColumnId: z.number().optional().describe("New board column ID (status)"),
-      assigneeId: z.number().optional().describe("New assigned user ID"),
-      cycleId: z.number().optional().describe("New cycle/sprint ID"),
+      taskTypeId: z.number().int().min(1).optional().describe("New task type ID"),
+      priorityId: z.number().int().min(1).optional().describe("New priority ID"),
+      boardColumnId: z.number().int().min(1).optional().describe("New board column ID (status)"),
+      assigneeId: 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(0).optional().describe("New milestone ID (0 detaches from the current milestone)."),
       parentTaskId: z.number().int().min(0).optional().describe("New parent task ID (0 clears the parent and promotes to a top-level task)."),
       storyPoints: z.number().int().min(1).optional().describe("Story points estimate (positive integer)"),
@@ -368,13 +368,13 @@ export function registerTaskTools(
     "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().describe("Project ID - all tasks must belong to this project"),
-      taskIds: z.array(z.number()).min(1).describe("Task IDs to update (at least one)"),
-      boardColumnId: z.number().optional().describe("New board column ID (status)"),
-      taskPriorityId: z.number().optional().describe("New priority ID"),
-      taskTypeId: z.number().optional().describe("New task type ID"),
-      assignedUserId: z.number().optional().describe("New assigned user ID"),
-      cycleId: z.number().optional().describe("New cycle/sprint ID"),
+      projectId: z.number().int().min(1).describe("Project ID - all tasks must belong to this project"),
+      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"),
@@ -418,9 +418,9 @@ export function registerTaskTools(
     "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().describe("Project ID - all tasks must belong to this project"),
-      taskIds: z.array(z.number()).min(1).describe("Task IDs to move"),
-      cycleId: z.number().describe("Target cycle/sprint ID"),
+      projectId: z.number().int().min(1).describe("Project ID - all tasks must belong to this project"),
+      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 }) => {
@@ -445,9 +445,9 @@ export function registerTaskTools(
     "opsee_bulk_move_to_column",
     "Convenience wrapper: move many tasks to the same board column (status) in one call.",
     {
-      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
-      taskIds: z.array(z.number()).min(1).describe("Task IDs to move"),
-      boardColumnId: z.number().describe("Target board column ID (status)"),
+      projectId: z.number().int().min(1).describe("Project ID - all tasks must belong to this project"),
+      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 }) => {
@@ -472,9 +472,9 @@ export function registerTaskTools(
     "opsee_bulk_assign",
     "Convenience wrapper: assign many tasks to the same user in one call.",
     {
-      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
-      taskIds: z.array(z.number()).min(1).describe("Task IDs to reassign"),
-      assigneeId: z.number().describe("Target user ID"),
+      projectId: z.number().int().min(1).describe("Project ID - all tasks must belong to this project"),
+      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 }) => {
@@ -499,9 +499,9 @@ export function registerTaskTools(
     "opsee_bulk_set_priority",
     "Convenience wrapper: set the same priority on many tasks in one call.",
     {
-      projectId: z.number().describe("Project ID - all tasks must belong to this project"),
-      taskIds: z.array(z.number()).min(1).describe("Task IDs to reprioritize"),
-      priorityId: z.number().describe("Target priority ID (from opsee_list_task_priorities)"),
+      projectId: z.number().int().min(1).describe("Project ID - all tasks must belong to this project"),
+      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 }) => {
@@ -526,7 +526,7 @@ export function registerTaskTools(
     "opsee_replace_task_labels",
     "Replace the entire set of labels on a single task. Use opsee_update_task with labelIds for the same effect, but this tool is more discoverable for the common 'set my labels to [...]' flow.",
     {
-      taskId: z.number().describe("The task ID"),
+      taskId: z.number().int().min(1).describe("The task ID"),
       labelIds: z.array(z.number().int().min(1)).describe("Label IDs to set (empty array clears all labels)"),
     },
     { readOnlyHint: false, destructiveHint: false },
@@ -576,7 +576,7 @@ export function registerTaskTools(
     "opsee_link_task_to_initiative",
     "Link an existing task to an Initiative — use this to bring an already-existing task into an initiative's scope. To create NEW tasks under an initiative, use opsee_decompose_initiative (first time) or opsee_reconcile_initiative (re-planning) instead. Fetches the task first so no other fields are blanked.",
     {
-      taskId: z.number().describe("The task ID to link"),
+      taskId: z.number().int().min(1).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 },
@@ -625,7 +625,7 @@ export function registerTaskTools(
     "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"),
+      taskId: z.number().int().min(1).describe("The task ID to unlink"),
     },
     { readOnlyHint: false, destructiveHint: false },
     async ({ taskId }) => {
@@ -672,7 +672,7 @@ export function registerTaskTools(
   server.tool(
     "opsee_delete_task",
     "Delete a task by ID. This is permanent.",
-    { taskId: z.number().describe("The task ID to delete") },
+    { taskId: z.number().int().min(1).describe("The task ID to delete") },
     { readOnlyHint: false, destructiveHint: true },
     async ({ taskId }) => {
       try {
@@ -689,8 +689,8 @@ export function registerTaskTools(
     "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().describe("Project ID - all tasks must belong to this project"),
-      taskIds: z.array(z.number()).min(1).describe("Task IDs to delete (at least one)"),
+      projectId: z.number().int().min(1).describe("Project ID - all tasks must belong to this project"),
+      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 }) => {

package/src/tools/user.ts

@@ -38,8 +38,8 @@ export function registerUserTools(
     "opsee_list_users",
     "Lists users in the authenticated company. Opsee scopes users at the Company level — there is no project-scoped user listing because Users do not have a per-project relation. Use this to resolve assignee names to IDs.",
     {
-      page: z.number().optional().describe("Page number (default: 1)"),
-      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+      page: z.number().int().min(1).optional().describe("Page number (default: 1)"),
+      pageSize: z.number().int().min(1).optional().describe("Items per page (default: 50)"),
     },
     { readOnlyHint: true, destructiveHint: false },
     async ({ page, pageSize }) => {
@@ -58,7 +58,7 @@ export function registerUserTools(
   server.tool(
     "opsee_get_user",
     "Get full details of a specific user by ID.",
-    { userId: z.number().describe("The user ID") },
+    { userId: z.number().int().min(1).describe("The user ID") },
     { readOnlyHint: true, destructiveHint: false },
     async ({ userId }) => {
       try {

package/src/tools/work-logs.ts

@@ -14,7 +14,7 @@ export function registerWorkLogTools(
   server.tool(
     "opsee_list_work_logs",
     "List all work-log entries for a task, oldest first. Includes the user who logged each entry, hours, and optional description.",
-    { taskId: z.number().describe("The task ID") },
+    { taskId: z.number().int().min(1).describe("The task ID") },
     { readOnlyHint: true, destructiveHint: false },
     async ({ taskId }) => {
       try {
@@ -52,7 +52,7 @@ export function registerWorkLogTools(
     "opsee_log_work",
     "Log time against a task. Posts as the authenticated user. Hours must be > 0.",
     {
-      taskId: z.number().describe("The task ID"),
+      taskId: z.number().int().min(1).describe("The task ID"),
       hours: z.number().min(0.1).describe("Hours worked (>= 0.1)"),
       description: z.string().optional().describe("Optional note describing what was done"),
     },
@@ -79,8 +79,8 @@ export function registerWorkLogTools(
     "opsee_delete_work_log",
     "Delete a work-log entry by ID. This is permanent.",
     {
-      taskId: z.number().describe("The task ID the work log belongs to"),
-      workLogId: z.number().describe("The work log ID to delete"),
+      taskId: z.number().int().min(1).describe("The task ID the work log belongs to"),
+      workLogId: z.number().int().min(1).describe("The work log ID to delete"),
     },
     { readOnlyHint: false, destructiveHint: true },
     async ({ taskId, workLogId }) => {
@@ -97,7 +97,7 @@ export function registerWorkLogTools(
   server.tool(
     "opsee_get_task_actual_hours",
     "Sum of all work_log hours on a task. Use this to compare against opsee_get_task's estimatedHours when assessing whether a task is over budget.",
-    { taskId: z.number().describe("The task ID") },
+    { taskId: z.number().int().min(1).describe("The task ID") },
     { readOnlyHint: true, destructiveHint: false },
     async ({ taskId }) => {
       try {

package/src/utils/__tests__/format.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from "vitest";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { formatError } from "../format.js";
+
+describe("formatError classification", () => {
+  test("ConnectError Unauthenticated → login instruction (correct command)", () => {
+    const msg = formatError(new ConnectError("nope", Code.Unauthenticated));
+    expect(msg).toContain("npx opsee-mcp login");
+    expect(msg).toMatch(/Not authenticated/i);
+  });
+
+  test("ConnectError Unavailable → reach-API message with raw detail", () => {
+    const msg = formatError(new ConnectError("backend down", Code.Unavailable));
+    expect(msg).toMatch(/Could not reach Opsee API/i);
+    expect(msg).toContain("backend down");
+  });
+
+  test("other ConnectError codes pass through as [Code] rawMessage", () => {
+    const msg = formatError(new ConnectError("task missing", Code.NotFound));
+    expect(msg).toBe("[NotFound] task missing");
+  });
+
+  test("does NOT misclassify a ConnectError whose text embeds 401/ECONNREFUSED", () => {
+    // The point of keying on the structured code: a NotFound whose message
+    // contains "401" must stay NotFound, not become an auth error.
+    const msg = formatError(new ConnectError('task "401 ECONNREFUSED" missing', Code.NotFound));
+    expect(msg).toBe('[NotFound] task "401 ECONNREFUSED" missing');
+    expect(msg).not.toMatch(/Not authenticated/i);
+  });
+
+  test("raw ECONNREFUSED error (err.code) → reach-API message", () => {
+    const err = Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:443"), {
+      code: "ECONNREFUSED",
+    });
+    expect(formatError(err)).toMatch(/Could not reach Opsee API/i);
+  });
+
+  test("raw ENOTFOUND error (err.code) → reach-API message", () => {
+    const err = Object.assign(new Error("getaddrinfo ENOTFOUND api"), {
+      code: "ENOTFOUND",
+    });
+    expect(formatError(err)).toMatch(/Could not reach Opsee API/i);
+  });
+
+  test("plain Error without a code → its message verbatim", () => {
+    expect(formatError(new Error("something odd"))).toBe("something odd");
+  });
+
+  test("non-Error value → String(value)", () => {
+    expect(formatError("boom")).toBe("boom");
+    expect(formatError(42)).toBe("42");
+  });
+});

package/src/utils/format.ts

@@ -1,6 +1,7 @@
 import type { Task, Project, Cycle, DocPage, DocSpace, Milestone, MilestoneTask, User, Label, TaskLabel, Comment, TaskDependency, Initiative, InitiativeMemoryEntry, TaskPullRequest } from "../../gen/api/v1/models_pb.js";
 import { TaskDependencyType } from "../../gen/api/v1/models_pb.js";
 import type { InitiativeGraph, InitiativeSlice, ReconcileChangeset } from "../../gen/api/v1/initiative_pb.js";
+import { Code, ConnectError } from "@connectrpc/connect";
 
 export function formatProject(p: Project): string {
   const lines = [
@@ -591,17 +592,26 @@ export function formatReconcileChangeset(changeset: ReconcileChangeset): string
 }
 
 export function formatError(error: unknown): string {
-  if (error instanceof Error) {
-    const msg = error.message;
-    const code = (error as any).code;
-    if (msg.includes("401") || msg.includes("Unauthenticated") || code === "unauthenticated") {
-      return "Not authenticated. Run `npx @opsee/mcp-server login` to connect your Opsee account.";
+  // Prefer the structured gRPC/Connect code over substring-matching the
+  // message: a backend error whose text embeds a task title containing "401"
+  // or "ECONNREFUSED" must not be misclassified as auth/network.
+  if (error instanceof ConnectError) {
+    if (error.code === Code.Unauthenticated) {
+      return "Not authenticated. Run `npx opsee-mcp login` to connect your Opsee account.";
+    }
+    if (error.code === Code.Unavailable) {
+      return `Could not reach Opsee API. Check your connection and OPSEE_API_URL. (${error.rawMessage})`;
     }
-    if (msg.includes("ECONNREFUSED") || msg.includes("ENOTFOUND")) {
-      return `Could not reach Opsee API. Check your connection and OPSEE_API_URL. (${msg})`;
+    return `[${Code[error.code]}] ${error.rawMessage}`;
+  }
+  if (error instanceof Error) {
+    // Raw transport errors before a Connect response carry a machine-readable
+    // code property (Node sets err.code); match on that, not the message text.
+    const code = (error as { code?: unknown }).code;
+    if (code === "ECONNREFUSED" || code === "ENOTFOUND") {
+      return `Could not reach Opsee API. Check your connection and OPSEE_API_URL. (${error.message})`;
     }
-    // Show full error details for debugging
-    return code ? `[${code}] ${msg}` : msg;
+    return error.message;
   }
   return String(error);
 }