@opsee/mcp-server 0.9.36 → 0.9.37

package/README.md

@@ -78,9 +78,26 @@ Ask Claude things like:
 | `opsee_update_cycle` | Update a cycle's fields |
 | `opsee_delete_cycle` | Delete a cycle |
 | `opsee_list_doc_spaces` | List doc spaces in a project |
+| `opsee_get_doc_space` | Get doc space details |
+| `opsee_create_doc_space` | Create a doc space |
+| `opsee_update_doc_space` | Update a doc space |
+| `opsee_delete_doc_space` | Delete a doc space |
 | `opsee_list_doc_pages` | List pages in a doc space |
 | `opsee_get_doc_page` | Read a doc page |
 | `opsee_create_doc_page` | Create a new doc page |
+| `opsee_update_doc_page` | Update a doc page (read-merge-write, with version snapshotting) |
+| `opsee_delete_doc_page` | Delete a doc page |
+| `opsee_set_doc_page_archived` | Archive or unarchive a doc page |
+| `opsee_list_doc_templates` | List doc templates in a project |
+| `opsee_create_doc_template` | Create a doc template |
+| `opsee_update_doc_template` | Update a doc template |
+| `opsee_delete_doc_template` | Delete a doc template |
+| `opsee_list_task_doc_pages` | List doc pages attached to a task |
+| `opsee_attach_doc_page_to_task` | Attach a doc page to a task |
+| `opsee_detach_doc_page_from_task` | Detach a doc page from a task |
+| `opsee_list_milestone_doc_pages` | List doc pages attached to a milestone |
+| `opsee_attach_doc_page_to_milestone` | Attach a doc page to a milestone |
+| `opsee_detach_doc_page_from_milestone` | Detach a doc page from a milestone |
 | `opsee_list_repositories` | List connected repositories |
 
 ## Task description format

package/package.json

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

package/src/client/api.ts

@@ -16,6 +16,7 @@ import { BoardColumnService } from "../../gen/api/v1/board_column_pb.js";
 import { CycleService } from "../../gen/api/v1/cycle_pb.js";
 import { DocSpaceService } from "../../gen/api/v1/doc_space_pb.js";
 import { DocPageService } from "../../gen/api/v1/doc_page_pb.js";
+import { DocPageVersionService } from "../../gen/api/v1/doc_page_version_pb.js";
 import { TaskTypeService } from "../../gen/api/v1/task_type_pb.js";
 import { TaskPriorityService } from "../../gen/api/v1/task_priority_pb.js";
 import { UserService } from "../../gen/api/v1/user_pb.js";
@@ -29,6 +30,9 @@ import { TaskDependencyService } from "../../gen/api/v1/task_dependency_pb.js";
 import { NotificationService } from "../../gen/api/v1/notification_pb.js";
 import { AcceptanceCriterionService } from "../../gen/api/v1/acceptance_criterion_pb.js";
 import { InitiativeService } from "../../gen/api/v1/initiative_pb.js";
+import { DocTemplateService } from "../../gen/api/v1/doc_template_pb.js";
+import { TaskDocPageService } from "../../gen/api/v1/task_doc_page_pb.js";
+import { MilestoneDocPageService } from "../../gen/api/v1/milestone_doc_page_pb.js";
 
 const authInterceptor: Interceptor = (next) => async (req) => {
   // Remote mode: token from AsyncLocalStorage (per-request)
@@ -102,6 +106,7 @@ export type ApiClients = {
   cycles: Client<typeof CycleService>;
   docSpaces: Client<typeof DocSpaceService>;
   docPages: Client<typeof DocPageService>;
+  docPageVersions: Client<typeof DocPageVersionService>;
   taskTypes: Client<typeof TaskTypeService>;
   taskPriorities: Client<typeof TaskPriorityService>;
   users: Client<typeof UserService>;
@@ -115,6 +120,9 @@ export type ApiClients = {
   notifications: Client<typeof NotificationService>;
   acceptanceCriteria: Client<typeof AcceptanceCriterionService>;
   initiatives: Client<typeof InitiativeService>;
+  docTemplates: Client<typeof DocTemplateService>;
+  taskDocPages: Client<typeof TaskDocPageService>;
+  milestoneDocPages: Client<typeof MilestoneDocPageService>;
 };
 
 export function getClients(): ApiClients {
@@ -127,6 +135,7 @@ export function getClients(): ApiClients {
       cycles: makeClient(CycleService),
       docSpaces: makeClient(DocSpaceService),
       docPages: makeClient(DocPageService),
+      docPageVersions: makeClient(DocPageVersionService),
       taskTypes: makeClient(TaskTypeService),
       taskPriorities: makeClient(TaskPriorityService),
       users: makeClient(UserService),
@@ -140,6 +149,9 @@ export function getClients(): ApiClients {
       notifications: makeClient(NotificationService),
       acceptanceCriteria: makeClient(AcceptanceCriterionService),
       initiatives: makeClient(InitiativeService),
+      docTemplates: makeClient(DocTemplateService),
+      taskDocPages: makeClient(TaskDocPageService),
+      milestoneDocPages: makeClient(MilestoneDocPageService),
     };
   }
   return cachedClients;

package/src/server.ts

@@ -15,6 +15,9 @@ import { registerWorkLogTools } from "./tools/work-logs.js";
 import { registerNotificationTools } from "./tools/notifications.js";
 import { registerAcceptanceCriterionTools } from "./tools/acceptance-criteria.js";
 import { registerInitiativeTools } from "./tools/initiatives.js";
+import { registerDocSpaceWriteTools } from "./tools/doc-spaces.js";
+import { registerDocTemplateTools } from "./tools/doc-templates.js";
+import { registerDocLinkTools } from "./tools/doc-links.js";
 
 export function createServer(clientFactory?: () => ApiClients): McpServer {
   const factory = clientFactory ?? getClients;
@@ -39,6 +42,9 @@ export function createServer(clientFactory?: () => ApiClients): McpServer {
   registerNotificationTools(server, factory);
   registerAcceptanceCriterionTools(server, factory);
   registerInitiativeTools(server, factory);
+  registerDocSpaceWriteTools(server, factory);
+  registerDocTemplateTools(server, factory);
+  registerDocLinkTools(server, factory);
 
   return server;
 }

package/src/tools/doc-links.ts

@@ -0,0 +1,170 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { ApiClients } from "../client/api.js";
+import { overridePagination } from "../client/api.js";
+import { formatDocPage, formatDocPageList, formatError } from "../utils/format.js";
+import type { DocPage } from "../../gen/api/v1/models_pb.js";
+
+// TaskDocPage and MilestoneDocPage rows both embed the linked DocPage; pull
+// those out so list views can reuse formatDocPageList from format/docs.ts
+// instead of a parallel formatter.
+function toDocPages<T extends { docPage?: DocPage }>(rows: T[]): DocPage[] {
+  return rows.map((r) => r.docPage).filter((p): p is DocPage => !!p);
+}
+
+export function registerDocLinkTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_task_doc_pages",
+    "List doc pages attached to a specific task.",
+    { taskId: z.number().int().min(1).describe("The task ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ taskId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.taskDocPages.getTaskDocPages({
+          taskId,
+          pagination: overridePagination(),
+        });
+        return { content: [{ type: "text", text: formatDocPageList(toDocPages(res.taskDocPages)) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_attach_doc_page_to_task",
+    "Attach an existing doc page to a task.",
+    {
+      taskId: z.number().int().min(1).describe("The task ID"),
+      docPageId: z.number().int().min(1).describe("The doc page ID to attach"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, docPageId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.taskDocPages.addTaskDocPage({ taskId, docPageId });
+        if (!res.taskDocPage?.docPage)
+          return { content: [{ type: "text", text: "Doc page attached." }] };
+        return { content: [{ type: "text", text: `Doc page attached:\n${formatDocPage(res.taskDocPage.docPage)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_detach_doc_page_from_task",
+    "Detach a doc page from a task. The DeleteTaskDocPage RPC takes the join-row id, which callers never have — this tool resolves it by listing the task's doc pages and matching on docPageId.",
+    {
+      taskId: z.number().int().min(1).describe("The task ID"),
+      docPageId: z.number().int().min(1).describe("The doc page ID to detach"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ taskId, docPageId }) => {
+      try {
+        const clients = getClients();
+        const listRes = await clients.taskDocPages.getTaskDocPages({
+          taskId,
+          pagination: overridePagination(),
+        });
+        const row = listRes.taskDocPages.find((r) => r.docPageId === docPageId);
+        if (!row)
+          return { content: [{ type: "text", text: `Doc page ${docPageId} is not attached to task ${taskId}.` }] };
+
+        try {
+          await clients.taskDocPages.deleteTaskDocPage({ id: row.id });
+        } catch (deleteError) {
+          // A concurrent detach can remove the row between the list above and
+          // this delete. The caller's intent (link gone) is already
+          // satisfied, so report the same outcome instead of a raw NotFound.
+          if (deleteError instanceof ConnectError && deleteError.code === Code.NotFound)
+            return { content: [{ type: "text", text: `Doc page ${docPageId} is not attached to task ${taskId}.` }] };
+          throw deleteError;
+        }
+        return { content: [{ type: "text", text: "Doc page detached." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_list_milestone_doc_pages",
+    "List doc pages attached to a specific milestone.",
+    { milestoneId: z.number().int().min(1).describe("The milestone ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ milestoneId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.milestoneDocPages.getMilestoneDocPages({
+          milestoneId,
+          pagination: overridePagination(),
+        });
+        return { content: [{ type: "text", text: formatDocPageList(toDocPages(res.milestoneDocPages)) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_attach_doc_page_to_milestone",
+    "Attach an existing doc page to a milestone.",
+    {
+      milestoneId: z.number().int().min(1).describe("The milestone ID"),
+      docPageId: z.number().int().min(1).describe("The doc page ID to attach"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ milestoneId, docPageId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.milestoneDocPages.addMilestoneDocPage({ milestoneId, docPageId });
+        if (!res.milestoneDocPage?.docPage)
+          return { content: [{ type: "text", text: "Doc page attached." }] };
+        return { content: [{ type: "text", text: `Doc page attached:\n${formatDocPage(res.milestoneDocPage.docPage)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_detach_doc_page_from_milestone",
+    "Detach a doc page from a milestone. The DeleteMilestoneDocPage RPC takes the join-row id, which callers never have — this tool resolves it by listing the milestone's doc pages and matching on docPageId.",
+    {
+      milestoneId: z.number().int().min(1).describe("The milestone ID"),
+      docPageId: z.number().int().min(1).describe("The doc page ID to detach"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ milestoneId, docPageId }) => {
+      try {
+        const clients = getClients();
+        const listRes = await clients.milestoneDocPages.getMilestoneDocPages({
+          milestoneId,
+          pagination: overridePagination(),
+        });
+        const row = listRes.milestoneDocPages.find((r) => r.docPageId === docPageId);
+        if (!row)
+          return { content: [{ type: "text", text: `Doc page ${docPageId} is not attached to milestone ${milestoneId}.` }] };
+
+        try {
+          await clients.milestoneDocPages.deleteMilestoneDocPage({ id: row.id });
+        } catch (deleteError) {
+          // Same TOCTOU as the task variant above: a concurrent detach can
+          // remove the row between the list and this delete.
+          if (deleteError instanceof ConnectError && deleteError.code === Code.NotFound)
+            return { content: [{ type: "text", text: `Doc page ${docPageId} is not attached to milestone ${milestoneId}.` }] };
+          throw deleteError;
+        }
+        return { content: [{ type: "text", text: "Doc page detached." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/doc-spaces.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { authManager } from "../auth/manager.js";
+import { formatDocSpace, formatError } from "../utils/format.js";
+import { toKebabCase } from "../utils/slug.js";
+
+async function resolveUserId(clients: ApiClients): Promise<number> {
+  let userId = Number(authManager.getUserId()) || 0;
+  if (!userId) {
+    const meRes = await clients.users.getMe({});
+    if (meRes.user) userId = meRes.user.id;
+  }
+  return userId;
+}
+
+export function registerDocSpaceWriteTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_get_doc_space",
+    "Get full details of a specific doc space by ID.",
+    { spaceId: z.number().int().min(1).describe("The doc space ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ spaceId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.docSpaces.getDocSpace({ id: spaceId });
+        if (!res.docSpace)
+          return { content: [{ type: "text", text: "Doc space not found. Use opsee_list_doc_spaces to see available doc spaces." }] };
+        return { content: [{ type: "text", text: formatDocSpace(res.docSpace) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_create_doc_space",
+    "Create a new documentation space in an Opsee project. Requires the Admin or Owner role; the User role has read-only access to doc spaces.",
+    {
+      projectId: z.number().int().min(1).describe("The project ID"),
+      title: z.string().min(1).describe("Doc space title"),
+      description: z.string().optional().describe("Doc space description"),
+      isDefault: z.boolean().optional().describe("Whether this is the project's default doc space (default: false)"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, title, description, isDefault }) => {
+      try {
+        const clients = getClients();
+        const userId = await resolveUserId(clients);
+        if (!userId)
+          return {
+            content: [{ type: "text", text: "Could not resolve the current user (no cached session and getMe returned none). The doc space was not created, since the backend would otherwise persist it as owned by user 0." }],
+            isError: true,
+          };
+
+        const res = await clients.docSpaces.addDocSpace({
+          title,
+          slug: toKebabCase(title),
+          description,
+          isDefault: isDefault ?? false,
+          isArchived: false,
+          projectId,
+          createdByUserId: userId,
+          updatedByUserId: userId,
+        });
+
+        if (!res.docSpace)
+          return { content: [{ type: "text", text: "Failed to create doc space. 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: `Doc space created:\n${formatDocSpace(res.docSpace)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_update_doc_space",
+    "Update a doc space's fields (patch semantics - only provided fields are changed). EditDocSpaceRequest has no field mask, so this fetches the current doc space first and resends every field. The slug is regenerated only when title changes.",
+    {
+      spaceId: z.number().int().min(1).describe("The doc space ID to update. Requires the Admin or Owner role."),
+      title: z.string().min(1).optional().describe("New title"),
+      description: z.string().optional().describe("New description"),
+      isDefault: z.boolean().optional().describe("Whether this is the project's default doc space"),
+      isArchived: z.boolean().optional().describe("Whether the doc space is archived"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ spaceId, title, description, isDefault, isArchived }) => {
+      try {
+        const clients = getClients();
+        const getRes = await clients.docSpaces.getDocSpace({ id: spaceId });
+        const space = getRes.docSpace;
+        if (!space)
+          return { content: [{ type: "text", text: "Doc space not found. Use opsee_list_doc_spaces to see available doc spaces." }] };
+
+        const userId = await resolveUserId(clients);
+        if (!userId)
+          return {
+            content: [{ type: "text", text: "Could not resolve the current user (no cached session and getMe returned none). The edit was not applied, since the backend would otherwise silently misattribute it to whoever last edited the doc space." }],
+            isError: true,
+          };
+
+        const res = await clients.docSpaces.editDocSpace({
+          id: space.id,
+          title: title ?? space.title,
+          slug: title ? toKebabCase(title) : space.slug,
+          description: description ?? space.description,
+          isDefault: isDefault ?? space.isDefault,
+          isArchived: isArchived ?? space.isArchived,
+          projectId: space.projectId,
+          createdByUserId: space.createdByUserId,
+          updatedByUserId: userId,
+        });
+
+        if (!res.docSpace)
+          return { content: [{ type: "text", text: "Failed to update doc space. 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: `Doc space updated:\n${formatDocSpace(res.docSpace)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_doc_space",
+    "Delete a doc space. Doc pages are not linked to doc spaces in the data model — DocPage.doc_space_id is a legacy proto field the backend no longer populates, since pages are attached directly to the project. Deleting a doc space only removes this grouping row; it has no effect on any doc pages.",
+    { spaceId: z.number().int().min(1).describe("The doc space ID to delete. Requires the Admin or Owner role.") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ spaceId }) => {
+      try {
+        const clients = getClients();
+        await clients.docSpaces.deleteDocSpace({ id: spaceId });
+        return { content: [{ type: "text", text: "Doc space deleted. Doc pages in the project are unaffected." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/doc-templates.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClients } from "../client/api.js";
+import { formatDocTemplate, formatDocTemplateList, formatError } from "../utils/format.js";
+
+export function registerDocTemplateTools(
+  server: McpServer,
+  getClients: () => ApiClients,
+): void {
+  server.tool(
+    "opsee_list_doc_templates",
+    "List documentation templates in an Opsee project.",
+    { projectId: z.number().int().min(1).describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
+    async ({ projectId }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.docTemplates.listDocTemplates({ projectId });
+        return { content: [{ type: "text", text: formatDocTemplateList(res.docTemplates) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_create_doc_template",
+    "Create a new documentation template in an Opsee project.",
+    {
+      projectId: z.number().int().min(1).describe("The project ID"),
+      name: z.string().min(1).max(200).describe("Template name"),
+      title: z.string().max(200).optional().describe("Template title"),
+      content: z.string().describe("Template content"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, name, title, content }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.docTemplates.createDocTemplate({
+          projectId,
+          name,
+          title: title ?? "",
+          content,
+        });
+
+        if (!res.docTemplate)
+          return { content: [{ type: "text", text: "Failed to create doc template. 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: `Doc template created:\n${formatDocTemplate(res.docTemplate)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_update_doc_template",
+    "Update a doc template's fields (patch semantics - only provided fields are changed). There is no GetDocTemplate RPC, so projectId is required: this tool looks up the current template via opsee_list_doc_templates for that project, merges in your changes, and resends the full update (UpdateDocTemplateRequest has no field mask).",
+    {
+      projectId: z.number().int().min(1).describe("The project ID the template belongs to — required because there is no GetDocTemplate RPC; the current template is found via a project list"),
+      templateId: z.number().int().min(1).describe("The doc template ID to update"),
+      name: z.string().min(1).max(200).optional().describe("New name"),
+      title: z.string().max(200).optional().describe("New title"),
+      content: z.string().optional().describe("New content"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ projectId, templateId, name, title, content }) => {
+      try {
+        const clients = getClients();
+        const listRes = await clients.docTemplates.listDocTemplates({ projectId });
+        const template = listRes.docTemplates.find((t) => t.id === templateId);
+        if (!template)
+          return { content: [{ type: "text", text: `Doc template ${templateId} not found in project ${projectId}. Use opsee_list_doc_templates to see available templates.` }] };
+
+        const res = await clients.docTemplates.updateDocTemplate({
+          id: template.id,
+          name: name ?? template.name,
+          title: title ?? template.title,
+          content: content ?? template.content,
+        });
+
+        if (!res.docTemplate)
+          return { content: [{ type: "text", text: "Failed to update doc template. 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: `Doc template updated:\n${formatDocTemplate(res.docTemplate)}` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_doc_template",
+    "Delete a doc template. Soft delete (the row is marked deleted, not erased), so it is recoverable by an operator but not through this API. Requires the Admin or Owner role; the User role can only list templates.",
+    { templateId: z.number().int().min(1).describe("The doc template ID to delete") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ templateId }) => {
+      try {
+        const clients = getClients();
+        await clients.docTemplates.deleteDocTemplate({ id: templateId });
+        return { content: [{ type: "text", text: "Doc template deleted." }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+}

package/src/tools/docs.ts

@@ -18,6 +18,15 @@ function toKebabCase(str: string): string {
     .replace(/^-|-$/g, "");
 }
 
+async function resolveCurrentUserId(clients: ApiClients): Promise<number> {
+  let userId = Number(authManager.getUserId()) || 0;
+  if (!userId) {
+    const meRes = await clients.users.getMe({});
+    if (meRes.user) userId = meRes.user.id;
+  }
+  return userId;
+}
+
 export function registerDocTools(
   server: McpServer,
   getClients: () => ApiClients,
@@ -150,4 +159,170 @@ export function registerDocTools(
       }
     },
   );
+
+  server.tool(
+    "opsee_update_doc_page",
+    "Update a documentation page's title, content, or contentType. Performs a read-merge-write: any field you don't pass is preserved from the existing page (EditDocPageRequest has no field mask, so an incomplete request would blank the rest). No optimistic lock -- a concurrent edit from the web UI can be silently lost. Cannot clear content to an empty string: the backend's struct-based update silently skips empty-string fields, so that call is rejected up front instead of reporting a false success. Does not take a display-order argument -- ordering is owned by opsee_move_doc_page (MoveDocPage), a separate endpoint. By default, changing the title or content also snapshots the prior version into page history -- pass snapshotVersion: false to skip that.",
+    {
+      pageId: z.number().int().min(1).describe("The doc page ID"),
+      title: z.string().optional().describe("New title. When provided, the slug is regenerated from it."),
+      content: z.string().optional().describe("New page content: markdown/plain text, or a BlockNote JSON array"),
+      contentType: z
+        .enum(["text", "json"])
+        .optional()
+        .describe(
+          "How the reader should interpret content. Only used when content is also provided; leave unset to detect it from the content.",
+        ),
+      changeSummary: z
+        .string()
+        .optional()
+        .describe("Short note describing the change, stored on the version snapshot"),
+      snapshotVersion: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe(
+          "Record this edit in page version history when the title or content changed. Defaults to true.",
+        ),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ pageId, title, content, contentType, changeSummary, snapshotVersion }) => {
+      try {
+        const clients = getClients();
+
+        const existingRes = await clients.docPages.getDocPage({ id: pageId });
+        const existing = existingRes.docPage;
+        if (!existing)
+          return { content: [{ type: "text", text: "Doc page not found." }], isError: true };
+
+        const userId = await resolveCurrentUserId(clients);
+        if (!userId)
+          return {
+            content: [{ type: "text", text: "Could not resolve the current user (no cached session and getMe returned none). The edit was not applied, since the backend would otherwise silently misattribute it to whoever last edited the page." }],
+            isError: true,
+          };
+
+        const finalTitle = title ?? existing.title;
+        const finalSlug = title !== undefined ? toKebabCase(title) : existing.slug;
+        if (title !== undefined && finalSlug === "")
+          return {
+            content: [{ type: "text", text: `Cannot update: title "${title}" has no alphanumeric characters usable in a slug. Choose a title with at least one letter or digit.` }],
+            isError: true,
+          };
+
+        const finalContent = content ?? existing.currentContent;
+        if (finalContent === "" && existing.currentContent !== "")
+          return {
+            content: [{ type: "text", text: "Cannot clear page content: the backend's EditDocPage endpoint uses a struct-based update that silently skips empty-string fields, so an empty content value would not actually be written. The page was left unchanged." }],
+            isError: true,
+          };
+
+        const finalContentType =
+          content !== undefined ? (contentType ?? detectDocContentType(content)) : existing.contentType;
+
+        const titleChanged = title !== undefined && title !== existing.title;
+        const contentChanged = content !== undefined && content !== existing.currentContent;
+        const shouldSnapshot = snapshotVersion && (titleChanged || contentChanged);
+        const nextVersionNumber = existing.currentVersionNumber + (shouldSnapshot ? 1 : 0);
+
+        const res = await clients.docPages.editDocPage({
+          id: pageId,
+          title: finalTitle,
+          slug: finalSlug,
+          currentContent: finalContent,
+          contentType: finalContentType,
+          currentVersionNumber: nextVersionNumber,
+          isRoot: existing.isRoot,
+          isArchived: existing.isArchived,
+          displayOrder: existing.displayOrder,
+          // EditDocPageRequest carries project_id, but the DocPage message read
+          // back from GetDocPage (proto/api/v1/models.proto) has no project_id
+          // field -- only the unused legacy doc_space_id -- so there is no way
+          // to read the existing value back to resend it here. Left unset.
+          parentPageId: existing.parentPageId,
+          createdByUserId: existing.createdByUserId,
+          updatedByUserId: userId,
+        });
+
+        if (!res.docPage)
+          return { content: [{ type: "text", text: "Failed to update doc page. The backend returned an empty response (no error). Retry; if it persists, surface the call to the Opsee team." }], isError: true };
+
+        let warning = "";
+        if (shouldSnapshot) {
+          try {
+            await clients.docPageVersions.addDocPageVersion({
+              versionNumber: nextVersionNumber,
+              title: finalTitle,
+              content: finalContent,
+              contentType: finalContentType,
+              changeSummary: changeSummary ?? "Edited via opsee_update_doc_page",
+              docPageId: pageId,
+              createdByUserId: userId,
+            });
+          } catch (snapshotError) {
+            // The page edit already committed, so this is reported rather than
+            // raised: the content is saved either way. Name the version number
+            // so the gap between the page counter and version history can be
+            // reconciled by hand.
+            warning = `\n\nWarning: the page was saved, but recording version ${nextVersionNumber} in page history failed: ${formatError(snapshotError)}\nThe page now reports version ${nextVersionNumber} with no matching history entry. Re-running this tool creates version ${nextVersionNumber + 1} rather than backfilling ${nextVersionNumber}.`;
+          }
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Doc page updated:\n${formatDocPage(res.docPage)}${warning}`,
+            },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_delete_doc_page",
+    "Delete a documentation page. This is a soft delete with no cascade: child pages are neither deleted nor reparented, so they keep their parent_page_id pointing at the now-deleted page. They still exist and are returned by opsee_list_doc_pages / opsee_get_doc_page, but they disappear from the page tree since their parent no longer resolves there. There is no undo exposed through this API. Requires the Admin or Owner role -- the User role can add/edit/read doc pages but not delete them, and this call fails with a permission error for a User-role caller. To hide a page reversibly instead, use opsee_set_doc_page_archived.",
+    { pageId: z.number().int().min(1).describe("The doc page ID") },
+    { readOnlyHint: false, destructiveHint: true },
+    async ({ pageId }) => {
+      try {
+        const clients = getClients();
+        await clients.docPages.deleteDocPage({ id: pageId });
+        return { content: [{ type: "text", text: `Doc page ${pageId} deleted.` }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
+
+  server.tool(
+    "opsee_set_doc_page_archived",
+    "Archive or unarchive a documentation page. This does not cascade to child pages. Archived pages are excluded from the doc page tree view by default. Reversible: call again with archived: false to restore it.",
+    {
+      pageId: z.number().int().min(1).describe("The doc page ID"),
+      archived: z.boolean().describe("true to archive, false to unarchive"),
+    },
+    { readOnlyHint: false, destructiveHint: false },
+    async ({ pageId, archived }) => {
+      try {
+        const clients = getClients();
+        const res = await clients.docPages.setDocPageArchived({ id: pageId, archived });
+        if (!res.docPage)
+          return { content: [{ type: "text", text: "Doc page not found." }], isError: true };
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Doc page ${archived ? "archived" : "unarchived"}:\n${formatDocPage(res.docPage)}`,
+            },
+          ],
+        };
+      } catch (error) {
+        return { content: [{ type: "text", text: formatError(error) }], isError: true };
+      }
+    },
+  );
 }

package/src/utils/format/doc-templates.ts

@@ -0,0 +1,23 @@
+import type { DocTemplate } from "../../../gen/api/v1/doc_template_pb.js";
+
+export function formatDocTemplate(t: DocTemplate): string {
+  const lines = [`${t.name}`];
+  if (t.title) lines.push(`  Title: ${t.title}`);
+  if (t.content) {
+    const content =
+      t.content.length > 500 ? t.content.substring(0, 500) + "..." : t.content;
+    lines.push(`  Content: ${content}`);
+  }
+  lines.push(`  Project ID: ${t.projectId}`);
+  lines.push(`  ID: ${t.id}`);
+  return lines.join("\n");
+}
+
+export function formatDocTemplateList(templates: DocTemplate[]): string {
+  if (templates.length === 0) return "No doc templates found.";
+  const header = `Found ${templates.length} doc template(s):\n`;
+  return (
+    header +
+    templates.map((t, i) => `${i + 1}. ${formatDocTemplate(t)}`).join("\n\n")
+  );
+}

package/src/utils/format/index.ts

@@ -16,6 +16,7 @@ export {
 } from "./milestone.js";
 export { formatUser, formatUserList } from "./user.js";
 export { formatLabel, formatLabelList, formatTaskLabelList } from "./label.js";
+export { formatDocTemplate, formatDocTemplateList } from "./doc-templates.js";
 export { formatComment, formatCommentList } from "./comment.js";
 export { blockNoteToMarkdown, isBlockNoteJSON, detectDocContentType } from "./blocknote.js";
 export {

package/src/utils/slug.ts

@@ -0,0 +1,10 @@
+// Slugs are derived client-side rather than left to the backend: Add*Request
+// messages for doc spaces and doc pages require a non-empty slug field with
+// no server-side default, so a create call must already carry one derived
+// from the title to succeed in a single round trip.
+export function toKebabCase(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+}