@opsee/mcp-server 0.1.0

package/src/tools/cycles.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { formatCycleList, formatCycle, formatError } from "../utils/format.js";
+
+export function registerCycleTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_cycles",
+    "List cycles/sprints in an Opsee project.",
+    { projectId: z.number().describe("The project ID") },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.cycles.getCycles({ projectId });
+        return { content: [{ type: "text", text: formatCycleList(res.cycles) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_cycle",
+    "Get details of a specific cycle/sprint by ID.",
+    { cycleId: z.number().describe("The cycle ID") },
+    async ({ cycleId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.cycles.getCycle({ id: cycleId });
+        if (!res.cycle) return { content: [{ type: "text", text: "Cycle not found." }] };
+        return { content: [{ type: "text", text: formatCycle(res.cycle) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_create_cycle",
+    "Create a new cycle/sprint in an Opsee project.",
+    {
+      projectId: z.number().describe("The project ID"),
+      name: z.string().describe("Cycle name"),
+      startDate: z.string().describe("Start date (ISO 8601, e.g. 2026-03-25)"),
+      endDate: z.string().describe("End date (ISO 8601, e.g. 2026-04-08)"),
+      description: z.string().optional().describe("Cycle description"),
+    },
+    async ({ projectId, name, startDate, endDate, description }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.cycles.addCycle({
+          projectId,
+          name,
+          goal: "",
+          startDate: timestampFromDate(new Date(startDate)),
+          endDate: timestampFromDate(new Date(endDate)),
+          isActive: true,
+          description,
+        });
+        if (!res.cycle)
+          return { content: [{ type: "text", text: "Failed to create cycle." }] };
+
+        return {
+          content: [
+            { type: "text", text: `Cycle created:\n${formatCycle(res.cycle)}` },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/docs.ts

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { create } from "@bufbuild/protobuf";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { authManager } from "../auth/manager.js";
+import {
+  formatDocSpaceList,
+  formatDocPageList,
+  formatDocPage,
+  formatError,
+} from "../utils/format.js";
+import {
+  FilterOptionsSchema,
+  FilterSchema,
+} from "../../gen/api/v1/filter_pb.js";
+
+function toKebabCase(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+export function registerDocTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_doc_spaces",
+    "List documentation spaces in an Opsee project.",
+    { projectId: z.number().describe("The project ID") },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.docSpaces.getDocSpaces({
+          filterOptions: create(FilterOptionsSchema, {
+            filters: [
+              create(FilterSchema, {
+                key: "ProjectId",
+                value: String(projectId),
+              }),
+            ],
+          }),
+        });
+        return {
+          content: [{ type: "text", text: formatDocSpaceList(res.docSpaces) }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_list_doc_pages",
+    "List documentation pages in a doc space.",
+    { docSpaceId: z.number().describe("The doc space ID") },
+    async ({ docSpaceId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.docPages.getDocPages({
+          filterOptions: create(FilterOptionsSchema, {
+            filters: [
+              create(FilterSchema, {
+                key: "DocSpaceId",
+                value: String(docSpaceId),
+              }),
+            ],
+          }),
+        });
+        return {
+          content: [{ type: "text", text: formatDocPageList(res.docPages) }],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_doc_page",
+    "Read a documentation page's content by ID.",
+    { pageId: z.number().describe("The doc page ID") },
+    async ({ pageId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.docPages.getDocPage({ id: pageId });
+        if (!res.docPage)
+          return { content: [{ type: "text", text: "Doc page not found." }] };
+        return { content: [{ type: "text", text: formatDocPage(res.docPage) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_create_doc_page",
+    "Create a new documentation page in an Opsee project.",
+    {
+      projectId: z.number().describe("The project ID"),
+      title: z.string().describe("Page title"),
+      content: z.string().describe("Page content (text or JSON)"),
+      parentPageId: z.number().optional().describe("Parent page ID for nested pages"),
+    },
+    async ({ projectId, title, content, parentPageId }) => {
+      try {
+        const clients = getClients();
+
+        // Resolve current user for createdByUserId
+        let userId = Number(authManager.getUserId()) || 0;
+        if (!userId) {
+          const meRes = await clients.users.getMe({});
+          if (meRes.user) userId = meRes.user.id;
+        }
+
+        const res = await clients.docPages.addDocPage({
+          projectId,
+          title,
+          slug: toKebabCase(title),
+          currentContent: content,
+          contentType: "json",
+          currentVersionNumber: 1,
+          isRoot: !parentPageId,
+          isArchived: false,
+          displayOrder: 0,
+          parentPageId,
+          createdByUserId: userId,
+          updatedByUserId: userId,
+        });
+
+        if (!res.docPage)
+          return { content: [{ type: "text", text: "Failed to create doc page." }] };
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Doc page created:\n${formatDocPage(res.docPage)}`,
+            },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/projects.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { formatProjectList, formatProject, formatError } from "../utils/format.js";
+
+export function registerProjectTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_projects",
+    "List all Opsee projects the authenticated user has access to.",
+    {},
+    async () => {
+      try {
+        const clients = getClients();
+        const res = await clients.projects.getProjects({});
+        return { content: [{ type: "text", text: formatProjectList(res.projects) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_project",
+    "Get details of a specific Opsee project by ID.",
+    { projectId: z.number().describe("The project ID") },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.projects.getProject({ id: projectId });
+        if (!res.project) return { content: [{ type: "text", text: "Project not found." }] };
+        return { content: [{ type: "text", text: formatProject(res.project) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/repositories.ts

@@ -0,0 +1,41 @@
+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";
+
+export function registerRepositoryTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_repositories",
+    "List connected VCS repositories (GitHub/GitLab) for an Opsee project.",
+    { projectId: z.number().describe("The project ID") },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.vcsIntegrations.getVCSIntegrations({ projectId });
+        if (!res.vcsIntegrations?.length)
+          return { content: [{ type: "text", text: "No repositories connected." }] };
+
+        const text = res.vcsIntegrations
+          .map((v) => {
+            const provider = v.provider === 1 ? "GitHub" : v.provider === 2 ? "GitLab" : "Unknown";
+            return `- ${v.repoOwner}/${v.repoName} (${provider}, branch: ${v.defaultBranch}, active: ${v.isActive}, ID: ${v.id})`;
+          })
+          .join("\n");
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Connected repositories:\n${text}`,
+            },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/task-metadata.ts

@@ -0,0 +1,96 @@
+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";
+
+export function registerTaskMetadataTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_task_types",
+    "Get available task types (Bug, Feature, etc.) for an Opsee project. Use these IDs when creating or updating tasks.",
+    { projectId: z.number().describe("The project ID") },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.taskTypes.getTaskTypes({ projectId });
+        if (!res.taskTypes?.length)
+          return { content: [{ type: "text", text: "No task types found." }] };
+
+        const text = res.taskTypes
+          .map((t) => `- ${t.name} (ID: ${t.id})`)
+          .join("\n");
+        return { content: [{ type: "text", text: `Task types:\n${text}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_list_task_priorities",
+    "Get priority levels (Critical, High, Medium, Low, etc.) for an Opsee project. Use these IDs when creating or updating tasks.",
+    { projectId: z.number().describe("The project ID") },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.taskPriorities.getTaskPriorities({ projectId });
+        if (!res.taskPriorities?.length)
+          return { content: [{ type: "text", text: "No task priorities found." }] };
+
+        const text = res.taskPriorities
+          .map((p) => `- ${p.name} (level: ${p.level}, ID: ${p.id})`)
+          .join("\n");
+        return { content: [{ type: "text", text: `Task priorities:\n${text}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_list_boards",
+    "List Kanban boards for an Opsee project. Use the board ID to list board columns.",
+    { projectId: z.number().describe("The project ID") },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.boards.getBoards({ projectId });
+        if (!res.boards?.length)
+          return { content: [{ type: "text", text: "No boards found." }] };
+
+        const text = res.boards
+          .map((b) => `- ${b.name} (ID: ${b.id}, active: ${b.isActive})`)
+          .join("\n");
+        return { content: [{ type: "text", text: `Boards:\n${text}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_list_board_columns",
+    "Get board columns/statuses (To Do, In Progress, Done, etc.) for a board. Use these IDs when creating or updating tasks.",
+    { boardId: z.number().describe("The board ID") },
+    async ({ boardId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.boardColumns.getBoardColumns({ boardId });
+        if (!res.boardColumns?.length)
+          return { content: [{ type: "text", text: "No board columns found." }] };
+
+        const text = res.boardColumns
+          .map(
+            (c) =>
+              `- ${c.name} (ID: ${c.id}, order: ${c.displayOrder}, lifecycle: ${c.lifecycleState})`,
+          )
+          .join("\n");
+        return { content: [{ type: "text", text: `Board columns:\n${text}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/tasks.ts

@@ -0,0 +1,228 @@
+import { z } from "zod";
+import { create } from "@bufbuild/protobuf";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { defaultPagination } from "../client/api.js";
+import { authManager } from "../auth/manager.js";
+import { formatTaskList, formatTask, formatError } from "../utils/format.js";
+import {
+  FilterOptionsSchema,
+  FilterSchema,
+} from "../../gen/api/v1/filter_pb.js";
+
+export function registerTaskTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_tasks",
+    "List tasks in an Opsee project. Supports filtering by status, assignee, board column, and cycle.",
+    {
+      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"),
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+    },
+    async ({ projectId, columnId, assigneeId, cycleId, page, pageSize }) => {
+      try {
+        const clients = getClients();
+
+        const filters: Array<{ key: string; value: string }> = [];
+        if (columnId) filters.push({ key: "BoardColumnId", value: String(columnId) });
+        if (assigneeId) filters.push({ key: "AssignedUserId", value: String(assigneeId) });
+        if (cycleId) filters.push({ key: "CycleId", value: String(cycleId) });
+
+        const filterOptions = filters.length > 0
+          ? create(FilterOptionsSchema, {
+              filters: filters.map((f) => create(FilterSchema, f)),
+            })
+          : undefined;
+
+        const res = await clients.tasks.getTasks({
+          projectId,
+          pagination: defaultPagination(page || 1, pageSize || 50),
+          filterOptions,
+        });
+
+        return { content: [{ type: "text", text: formatTaskList(res.tasks) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_get_task",
+    "Get full details of a specific task by ID.",
+    { taskId: z.number().describe("The task ID") },
+    async ({ taskId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.tasks.getTask({ id: taskId });
+        if (!res.task) return { content: [{ type: "text", text: "Task not found. Use opsee_list_tasks to see available tasks." }] };
+        return { content: [{ type: "text", text: formatTask(res.task) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "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"),
+      title: z.string().describe("Task title"),
+      description: z.string().optional().describe("Task description"),
+      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"),
+    },
+    async ({ projectId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId }) => {
+      try {
+        const clients = getClients();
+
+        // Auto-resolve defaults
+        let resolvedBoardId = 0;
+        let resolvedColumnId = boardColumnId || 0;
+        let resolvedTaskTypeId = taskTypeId || 0;
+        let resolvedPriorityId = priorityId || 0;
+
+        // Get default board
+        const boardsRes = await clients.boards.getBoards({ projectId });
+        if (boardsRes.boards?.length) {
+          resolvedBoardId = boardsRes.boards[0].id;
+
+          // Get first column if not specified
+          if (!boardColumnId) {
+            const colsRes = await clients.boardColumns.getBoardColumns({
+              boardId: resolvedBoardId,
+            });
+            if (colsRes.boardColumns?.length) {
+              resolvedColumnId = colsRes.boardColumns[0].id;
+            }
+          }
+        }
+
+        // Get first task type if not specified
+        if (!taskTypeId) {
+          const typesRes = await clients.taskTypes.getTaskTypes({ projectId });
+          if (typesRes.taskTypes?.length) {
+            resolvedTaskTypeId = typesRes.taskTypes[0].id;
+          }
+        }
+
+        // Get first priority if not specified
+        if (!priorityId) {
+          const priRes = await clients.taskPriorities.getTaskPriorities({ projectId });
+          if (priRes.taskPriorities?.length) {
+            resolvedPriorityId = priRes.taskPriorities[0].id;
+          }
+        }
+
+        // Get reporter (current user)
+        let reporterUserId = 0;
+        const userId = authManager.getUserId();
+        if (userId) {
+          reporterUserId = Number(userId);
+        }
+        if (!reporterUserId) {
+          const meRes = await clients.users.getMe({});
+          if (meRes.user) reporterUserId = meRes.user.id;
+        }
+
+        const res = await clients.tasks.addTask({
+          projectId,
+          title,
+          description,
+          boardId: resolvedBoardId,
+          boardColumnId: resolvedColumnId,
+          taskTypeId: resolvedTaskTypeId,
+          taskPriorityId: resolvedPriorityId,
+          reporterUserId,
+          assignedUserId: assigneeId,
+          displayOrder: 0,
+          aiModeEnabled: false,
+          cycleId,
+          repositoryIds: [],
+        });
+
+        if (!res.task)
+          return { content: [{ type: "text", text: "Failed to create task." }] };
+
+        return {
+          content: [
+            { type: "text", text: `Task created:\n${formatTask(res.task)}` },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "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"),
+      title: z.string().optional().describe("New title"),
+      description: z.string().optional().describe("New description"),
+      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"),
+    },
+    async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId }) => {
+      try {
+        const clients = getClients();
+
+        // Read current task
+        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." }] };
+
+        // Merge changes into full EditTaskRequest
+        const res = await clients.tasks.editTask({
+          id: task.id,
+          identifier: task.identifier,
+          title: title ?? task.title,
+          description: 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: boardColumnId ?? task.boardColumn?.id ?? 0,
+          projectId: task.project?.id ?? 0,
+          taskTypeId: taskTypeId ?? task.taskType?.id ?? 0,
+          taskPriorityId: priorityId ?? task.taskPriority?.id ?? 0,
+          reporterUserId: task.reporterUser?.id ?? 0,
+          assignedUserId: assigneeId ?? task.assignedUser?.id,
+          cycleId: cycleId ?? task.cycle?.id,
+          repositoryIds: task.taskRepositories?.map((r: { id: number }) => r.id) ?? [],
+        });
+
+        if (!res.task)
+          return { content: [{ type: "text", text: "Failed to update task." }] };
+
+        return {
+          content: [
+            { type: "text", text: `Task updated:\n${formatTask(res.task)}` },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/user.ts

@@ -0,0 +1,33 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { formatError } from "../utils/format.js";
+
+export function registerUserTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_get_me",
+    "Get the currently authenticated Opsee user's profile (name, email, role, company).",
+    {},
+    async () => {
+      try {
+        const clients = getClients();
+        const res = await clients.users.getMe({});
+        const u = res.user;
+        if (!u) return { content: [{ type: "text", text: "No user found." }] };
+
+        const text = [
+          `${u.fullName} (${u.email})`,
+          `  ID: ${u.id}`,
+          `  Company: ${u.company?.name || "N/A"} (ID: ${u.companyId})`,
+          `  Roles: ${u.flattenedRoles?.join(", ") || "N/A"}`,
+        ].join("\n");
+
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}