@opsee/mcp-server 0.9.59 → 0.10.0

package/src/auth/oauth-provider.ts

@@ -18,8 +18,6 @@ import {
 import type { KVStore } from "./kv-store.js";
 import { renewAccessToken, type TokenRenewer } from "./renew.js";
 
-// --- Stored value shapes ---
-
 interface PendingAuth {
   clientId: string;
   redirectUri: string;
@@ -37,17 +35,15 @@ interface AuthCode {
   clientId: string;
 }
 
-/** Server-side record behind an opaque refresh token. */
+/** RefreshRecord is the server-side record behind an opaque refresh token. */
 interface RefreshRecord {
-  /** The last access token issued to this session. Used to mint the next one. */
+  /** Last access token issued to this session; used to mint the next one. */
   accessToken: string;
   userId: string;
   companyId: string;
   clientId: string;
 }
 
-// --- Redis key namespacing + TTLs ---
-
 const CLIENT_KEY = (id: string) => `oauth:client:${id}`;
 const PENDING_KEY = (id: string) => `oauth:pending:${id}`;
 const CODE_KEY = (code: string) => `oauth:code:${code}`;
@@ -56,16 +52,11 @@ const REFRESH_KEY = (token: string) => `oauth:refresh:${token}`;
 
 const FLOW_TTL_SECONDS = 10 * 60; // pending auths + auth codes: 10 minutes
 const REVOKED_FALLBACK_TTL_SECONDS = 24 * 60 * 60; // if token expiry is unknown
-// Refresh tokens outlive the access token they renew, so a client that has been
-// idle for longer than one access-token lifetime can still come back without
-// sending the user through an interactive login.
+// Refresh tokens outlive the access token they renew, so an idle client returns without a login.
 const REFRESH_TTL_SECONDS = 180 * 24 * 60 * 60; // 180 days
 
-/**
- * Converts an RFC3339 expiry into the `expires_in` seconds an OAuth token
- * response carries. Returns undefined when the expiry is absent or unparseable
- * so the field is simply omitted rather than reported as an immediate expiry.
- */
+/** expiresInFrom converts an RFC3339 expiry to `expires_in` seconds, or undefined so the field is
+ * omitted rather than read as an immediate expiry. */
 function expiresInFrom(expiresAt: string): number | undefined {
   if (!expiresAt) return undefined;
   const expMs = new Date(expiresAt).getTime();
@@ -81,12 +72,8 @@ export class OpseeClientStore implements OAuthRegisteredClientsStore {
   ): Promise<OAuthClientInformationFull | undefined> {
     const raw = await this.store.get(CLIENT_KEY(clientId));
     if (!raw) {
-      // Unknown client. With a shared Redis store this means the client was
-      // never registered (or its registration expired) — return undefined so
-      // the SDK responds with invalid_client and the MCP client re-registers
-      // via Dynamic Client Registration. (Previously we returned a synthetic
-      // client with an empty redirect_uris list, which made the SDK reject
-      // every redirect_uri with "Unregistered redirect_uri".)
+      // undefined makes the SDK answer invalid_client so the client re-registers via DCR. A synthetic
+      // client with empty redirect_uris instead fails every redirect with "Unregistered redirect_uri".
       return undefined;
     }
     return JSON.parse(raw) as OAuthClientInformationFull;
@@ -102,19 +89,14 @@ export class OpseeClientStore implements OAuthRegisteredClientsStore {
       client_id_issued_at: Math.floor(Date.now() / 1000),
     };
 
-    // Only confidential clients get a secret. A public client registers with
-    // token_endpoint_auth_method "none" and authenticates via PKCE alone. If we
-    // minted a secret for it anyway, the SDK's token endpoint would then *require*
-    // that secret (see authenticateClient) and reject the PKCE-only token request
-    // with invalid_client — breaking every public client (e.g. Claude).
+    // Only confidential clients get a secret: minting one for a PKCE-only client makes the SDK's token
+    // endpoint require it and reject the request with invalid_client.
     if (client.token_endpoint_auth_method !== "none") {
       registered.client_secret = randomBytes(32).toString("hex");
     }
 
-    // Persist without a TTL. Clients cache their Dynamic Client Registration
-    // indefinitely and the DCR response advertises no expiry, so a server-side
-    // TTL guarantees that any client idle past the TTL comes back with a
-    // client_id we no longer recognise and gets invalid_client at /authorize.
+    // No TTL: DCR advertises no expiry and clients cache it forever, so an expiring record would
+    // return as an unrecognised client_id at /authorize.
     await this.store.set(CLIENT_KEY(clientId), JSON.stringify(registered));
     return registered;
   }
@@ -144,9 +126,7 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     return this._clientsStore;
   }
 
-  /**
-   * Step 1: Claude calls /authorize. We redirect to Opsee's login UI.
-   */
+  /** authorize: step 1, redirect the client to Opsee's login UI. */
   async authorize(
     client: OAuthClientInformationFull,
     params: AuthorizationParams,
@@ -166,16 +146,13 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
       FLOW_TTL_SECONDS,
     );
 
-    // Build callback URL back to our server
     const callbackUrl = `${this.serverUrl}/oauth/callback?pending=${pendingId}`;
     const loginUrl = `${this.appUrl}/auth/mcp?callback=${encodeURIComponent(callbackUrl)}`;
 
     res.redirect(loginUrl);
   }
 
-  /**
-   * Called by SDK to get the code_challenge for PKCE validation.
-   */
+  /** challengeForAuthorizationCode returns the stored code_challenge for PKCE validation. */
   async challengeForAuthorizationCode(
     _client: OAuthClientInformationFull,
     authorizationCode: string,
@@ -185,9 +162,7 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     return (JSON.parse(raw) as AuthCode).codeChallenge;
   }
 
-  /**
-   * Step 3: Claude exchanges auth code for access token.
-   */
+  /** exchangeAuthorizationCode: step 3, trade the auth code for an access token. */
   async exchangeAuthorizationCode(
     _client: OAuthClientInformationFull,
     authorizationCode: string,
@@ -195,8 +170,7 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     const raw = await this.store.get(CODE_KEY(authorizationCode));
     if (!raw) throw new Error("Invalid or expired authorization code");
 
-    // One-time use
-    await this.store.del(CODE_KEY(authorizationCode));
+    await this.store.del(CODE_KEY(authorizationCode)); // one-time use
 
     const code = JSON.parse(raw) as AuthCode;
 
@@ -204,9 +178,7 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
       access_token: code.token,
       token_type: "bearer",
       expires_in: expiresInFrom(code.expiresAt),
-      // Without a refresh token the client has exactly one credential: any
-      // failure to present it — expiry, revocation, a transient 5xx — can only
-      // be recovered by sending the user through an interactive login again.
+      // Without a refresh token, any credential failure can only be recovered by interactive login.
       refresh_token: await this.issueRefreshToken({
         accessToken: code.token,
         userId: code.userId,
@@ -216,11 +188,7 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     };
   }
 
-  /**
-   * Mints an opaque refresh token for a session and persists the record it
-   * stands for. Refresh tokens are rotated on every use, so each call replaces
-   * the previous handle.
-   */
+  /** issueRefreshToken mints an opaque refresh token; tokens rotate on every use. */
   private async issueRefreshToken(record: RefreshRecord): Promise<string> {
     const refreshToken = randomBytes(32).toString("hex");
     await this.store.set(
@@ -231,14 +199,8 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     return refreshToken;
   }
 
-  /**
-   * Trades a refresh token for a freshly minted access token.
-   *
-   * The stored access token is used to authenticate the renewal against the
-   * backend, so the session rolls forward for as long as the client keeps
-   * refreshing — the user is only sent back through the login UI once the
-   * stored token has itself lapsed.
-   */
+  /** exchangeRefreshToken trades a refresh token for a new access token, authenticating the renewal
+   * with the stored token so the session rolls forward until that token itself lapses. */
   async exchangeRefreshToken(
     client: OAuthClientInformationFull,
     refreshToken: string,
@@ -248,23 +210,19 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
 
     const record = JSON.parse(raw) as RefreshRecord;
 
-    // A refresh token belongs to the client it was issued to. Without this a
-    // leaked handle could be redeemed by any other registered client.
+    // Bind to the issuing client, or a leaked handle is redeemable by any registered client.
     if (record.clientId !== client.client_id) {
       throw new InvalidGrantError("Refresh token was issued to another client");
     }
 
-    // Rotate: the presented handle is spent whether or not renewal succeeds, so
-    // a captured refresh token cannot be replayed.
+    // Rotate: the handle is spent even if renewal fails, so it cannot be replayed.
     await this.store.del(REFRESH_KEY(refreshToken));
 
     let renewed;
     try {
       renewed = await this.renew(record.accessToken);
     } catch (err) {
-      // The stored token is no longer good enough to mint another (expired,
-      // user deactivated, backend rejecting it). Surface invalid_grant so the
-      // client falls back to a full authorization instead of retrying forever.
+      // invalid_grant makes the client fall back to full authorization instead of retrying forever.
       throw new InvalidGrantError(
         `Could not renew the session: ${err instanceof Error ? err.message : String(err)}`,
       );
@@ -283,23 +241,16 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     };
   }
 
-  /**
-   * Validate the access token (JWT from Opsee backend).
-   * We do lightweight validation here; the backend does full validation on API calls.
-   */
+  /** verifyAccessToken does lightweight JWT validation; the backend fully validates on each API call. */
   async verifyAccessToken(token: string): Promise<AuthInfo> {
     if (await this.isRevoked(token)) {
       throw new InvalidTokenError("Token has been revoked");
     }
 
-    // Decode JWT payload without crypto verification
     const parts = token.split(".");
     if (parts.length !== 3) throw new InvalidTokenError("Invalid token format");
 
-    // Scope the try to ONLY the decode/parse: a malformed payload becomes
-    // "Invalid token". The validation checks below run outside the catch so
-    // their errors propagate verbatim — the caller no longer depends on
-    // string-matching error messages that a refactor or locale could change.
+    // Try scoped to the parse only, so validation errors below propagate verbatim.
     let payload: { exp?: unknown; userId?: unknown; companyId?: unknown; role?: unknown };
     try {
       payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
@@ -307,8 +258,7 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
       throw new InvalidTokenError("Invalid token");
     }
 
-    // Require an expiry claim and reject expired tokens. A token that omits
-    // exp must not be treated as valid indefinitely.
+    // A token omitting exp must not be valid indefinitely.
     if (typeof payload.exp !== "number") {
       throw new InvalidTokenError("Token missing expiry");
     }
@@ -329,19 +279,8 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     };
   }
 
-  /**
-   * Checks the revocation denylist, treating an unreachable store as "not
-   * revoked".
-   *
-   * This lookup runs on every authenticated request. Letting a store error
-   * propagate would turn a momentary Redis hiccup — a failover, a reconnect, a
-   * command timeout — into a failed request for every live session at once,
-   * and with no way for a client to tell that apart from a real credential
-   * problem, the user ends up re-authenticating by hand. Revocation is a
-   * best-effort denylist on top of a token that is already time-bounded and
-   * re-validated by the backend on every API call, so a read failure degrades
-   * to the pre-revocation behaviour rather than locking everyone out.
-   */
+  /** isRevoked checks the denylist, treating an unreachable store as "not revoked": this runs on every
+   * request, and the token is already time-bounded and re-validated by the backend. */
   private async isRevoked(token: string): Promise<boolean> {
     try {
       return (await this.store.get(REVOKED_KEY(token))) !== null;
@@ -358,13 +297,10 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     _client: OAuthClientInformationFull,
     request: OAuthTokenRevocationRequest,
   ): Promise<void> {
-    // A refresh handle is opaque, not a JWT — drop the record outright so it
-    // cannot be redeemed, rather than filing it on the JWT denylist where
-    // verifyAccessToken would never look it up.
+    // A refresh handle is opaque, not a JWT, so drop the record: the JWT denylist is never consulted for it.
     await this.store.del(REFRESH_KEY(request.token));
 
-    // Keep the revocation marker only as long as the token could still be
-    // valid. Derive that from the JWT's exp when available.
+    // Keep the marker only while the token could still be valid, per the JWT's exp.
     let ttl = REVOKED_FALLBACK_TTL_SECONDS;
     const parts = request.token.split(".");
     if (parts.length === 3) {
@@ -377,18 +313,13 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
           if (remaining > 0) ttl = remaining;
         }
       } catch {
-        // Fall back to default TTL on undecodable tokens.
+        // Undecodable token: keep the default TTL.
       }
     }
     await this.store.set(REVOKED_KEY(request.token), "1", ttl);
   }
 
-  // --- Custom methods for the callback flow ---
-
-  /**
-   * Step 2: Opsee login redirects back to /oauth/callback.
-   * We generate an auth code and redirect to Claude's redirect_uri.
-   */
+  /** handleCallback: step 2, mint an auth code and redirect back to the client's redirect_uri. */
   async handleCallback(
     pendingId: string,
     token: string,
@@ -399,12 +330,10 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     const raw = await this.store.get(PENDING_KEY(pendingId));
     if (!raw) return { error: "Invalid or expired pending authorization" };
 
-    // One-time use
-    await this.store.del(PENDING_KEY(pendingId));
+    await this.store.del(PENDING_KEY(pendingId)); // one-time use
 
     const pending = JSON.parse(raw) as PendingAuth;
 
-    // Generate authorization code
     const authCode = randomBytes(32).toString("hex");
     const code: AuthCode = {
       token,
@@ -417,7 +346,6 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     };
     await this.store.set(CODE_KEY(authCode), JSON.stringify(code), FLOW_TTL_SECONDS);
 
-    // Build redirect URL with code and state
     const url = new URL(pending.redirectUri);
     url.searchParams.set("code", authCode);
     if (pending.state) url.searchParams.set("state", pending.state);

package/src/auth/renew.ts

@@ -2,9 +2,7 @@ import { createClient } from "@connectrpc/connect";
 import { createConnectTransport } from "@connectrpc/connect-node";
 import { AccountService } from "../../gen/api/v1/account_pb.js";
 
-/**
- * A freshly minted MCP access token plus the identity it belongs to.
- */
+/** A freshly minted MCP access token and the identity it belongs to. */
 export interface RenewedToken {
   token: string;
   userId: string;
@@ -13,15 +11,9 @@ export interface RenewedToken {
   expiresAt: string;
 }
 
-/**
- * Mints a new MCP access token on behalf of the holder of `currentToken`.
- *
- * `GenerateMCPToken` authenticates the caller from the bearer token itself, so
- * a still-valid token is all that is needed to roll a new one — no user
- * interaction and no signing key on this side. That is what lets a refresh
- * token renew a session: we keep the last good access token server-side and
- * trade it for a fresh one, rather than handing the same token back forever.
- */
+/** Mints a new access token for the holder of `currentToken`. GenerateMCPToken authenticates from the
+ * bearer itself, so a still-valid token rolls a new one with no user interaction and no local signing
+ * key, which is what lets a refresh token renew the session. */
 export type TokenRenewer = (currentToken: string) => Promise<RenewedToken>;
 
 function backendUrl(): string {
@@ -29,9 +21,7 @@ function backendUrl(): string {
 }
 
 export const renewAccessToken: TokenRenewer = async (currentToken) => {
-  // Built per call rather than cached: the bearer differs for every renewal,
-  // and renewals are rare enough that connection reuse is not worth the risk
-  // of leaking one user's token onto another user's request.
+  // Per call, not cached: the bearer differs each time, and reuse risks leaking one user's token.
   const transport = createConnectTransport({
     baseUrl: backendUrl(),
     httpVersion: "1.1",

package/src/client/api.ts

@@ -35,15 +35,13 @@ 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)
-  // Local mode: token from credentials file
+  // Remote mode reads the per-request token from AsyncLocalStorage; local mode from the credentials file.
   const token = getCurrentToken() || authManager.getToken();
   if (token) {
     req.header.set("Authorization", `Bearer ${token}`);
   }
-  // Mark this as an automation (MCP) client so the backend stamps live board
-  // events with the system actor — an agent acting under a user's token must
-  // not be self-skipped on that user's own board. (ADR-0002 §5; Slice 5.)
+  // Marks an automation client so board events carry the system actor: an agent using a user's token
+  // must not be self-skipped on that user's board (ADR-0002 §5).
   req.header.set("X-Opsee-Client", "mcp");
   return await next(req);
 };

package/src/server-http.ts

@@ -21,31 +21,24 @@ const SUCCESS_HTML = `<!DOCTYPE html>
 </body>
 </html>`;
 
-// Express parses a repeated query param (?token=a&token=b) into a string[], so
-// a blanket `req.query as Record<string,string>` cast lies to the type system
-// and lets an array slip through as if it were a string. Accept only a single
-// string value; anything else (array, missing) becomes undefined.
+// Express turns a repeated query param into string[], which a blanket cast would smuggle through as a
+// string. Accept a single string only; arrays and missing values become undefined.
 function singleQueryParam(value: unknown): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
 
 let processHandlersRegistered = false;
 
-// Register last-resort process guards exactly once. Registering inside
-// startHttpServer directly would accumulate duplicate listeners if it were
-// ever called more than once (tests, restart loops).
+// Registered once: doing this inside startHttpServer would stack duplicate listeners across calls.
 function registerProcessGuards(): void {
   if (processHandlersRegistered) return;
   processHandlersRegistered = true;
 
-  // An unhandled rejection is logged but not fatal: the per-request handlers
-  // catch their own errors, so this is a diagnostic backstop, not a crash path.
+  // Not fatal: request handlers catch their own errors, so this is only a diagnostic backstop.
   process.on("unhandledRejection", (reason) => {
     console.error("Unhandled promise rejection:", reason);
   });
-  // An uncaught exception leaves the process in an undefined state. Log and
-  // exit non-zero so the supervisor (k8s/systemd) restarts a clean process,
-  // rather than continuing to serve from a corrupt one.
+  // Exit non-zero so the supervisor restarts a clean process instead of serving from a corrupt one.
   process.on("uncaughtException", (err) => {
     console.error("Uncaught exception:", err);
     process.exit(1);
@@ -67,17 +60,15 @@ export async function startHttpServer(): Promise<void> {
   const issuerUrl = new URL(serverUrl);
 
   const app = express();
-  // Trust proxy headers (X-Forwarded-For) from nginx ingress
+  // Trust X-Forwarded-For from the nginx ingress.
   app.set("trust proxy", 1);
   app.use(cors());
   app.use(express.json());
 
-  // --- Health check ---
   app.get("/health", (_req, res) => {
     res.json({ status: "ok" });
   });
 
-  // --- OAuth 2.0 endpoints (authorize, token, register, metadata) ---
   app.use(
     mcpAuthRouter({
       provider,
@@ -88,7 +79,7 @@ export async function startHttpServer(): Promise<void> {
     }),
   );
 
-  // --- Custom OAuth callback (Opsee login redirects here) ---
+  // OAuth callback: the Opsee login redirects here.
   app.get("/oauth/callback", async (req, res) => {
     try {
       const pending = singleQueryParam(req.query.pending);
@@ -115,11 +106,9 @@ export async function startHttpServer(): Promise<void> {
         return;
       }
 
-      // Redirect to Claude's redirect_uri with the auth code
       res.redirect(result.redirectUri);
     } catch (err) {
-      // Without this, a throw here (e.g. Redis down in handleCallback) leaves
-      // the request hanging until the client times out.
+      // Without this, a throw (e.g. Redis down) hangs the request until the client times out.
       console.error("OAuth callback failed:", err);
       if (!res.headersSent) {
         res.status(500).send("Internal server error during OAuth callback");
@@ -127,22 +116,19 @@ export async function startHttpServer(): Promise<void> {
     }
   });
 
-  // --- Bearer auth middleware for MCP endpoints ---
   const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(new URL(serverUrl));
   const authMiddleware = requireBearerAuth({
     verifier: provider,
     resourceMetadataUrl,
   });
 
-  // --- MCP Streamable HTTP transport (stateless mode) ---
-  // Each request creates a fresh transport+server - no session persistence needed.
-  // This works reliably behind proxies/load balancers and with Claude Code's HTTP transport.
+  // Stateless Streamable HTTP: a fresh transport+server per request, which survives proxies and
+  // load balancers without session persistence.
 
   app.all("/mcp", authMiddleware, async (req, res) => {
-    // Extract the verified JWT from the auth middleware
     const accessToken = req.auth?.token;
 
-    // Wrap the MCP handling in the token context so API calls use this user's JWT
+    // Run inside the token context so API calls carry this user's JWT.
     await tokenContext.run({ token: accessToken || "" }, async () => {
       const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: undefined, // stateless - no session IDs
@@ -162,17 +148,15 @@ export async function startHttpServer(): Promise<void> {
           });
         }
       } finally {
-        // Always tear down the per-request transport+server, even on error,
-        // so they are not leaked on every failed request.
+        // Tear down even on error, or every failed request leaks a transport+server.
         await transport.close().catch(() => {});
         await mcpServer.close().catch(() => {});
       }
     });
   });
 
-  // Centralized error handler (must have 4 args to be recognized by Express).
-  // Catches synchronous throws from handlers so the client gets a 500 instead
-  // of a hung connection.
+  // Error handler; needs 4 args for Express to recognise it. Turns handler throws into a 500 rather
+  // than a hung connection.
   app.use(
     (
       err: unknown,

package/src/tools/acceptance-criteria.ts

@@ -3,20 +3,10 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ApiClients } from "../client/api.js";
 import { formatError } from "../utils/format.js";
 
-// Structured Acceptance Criterion entity — SECONDARY path.
-//
-// The PRIMARY way to record AC on an Opsee task is markdown inside the
-// task description: a `## Acceptance criteria` heading followed by
-// `- [ ]` / `- [x]` checkbox lines. BlockNote renders those as
-// clickable checkbox blocks in the task detail UI. /tpm and any other
-// AI agent should write AC via opsee_update_task's description field
-// using that convention.
-//
-// These four tools operate on a SEPARATE DB entity (acceptance_criteria
-// table) intended for automation paths that need machine-trackable AC
-// outside the description — PR-to-criterion mapping, AI workflow
-// outputs, reporting. They do NOT surface in the current task detail
-// UI; do not use them as the default AC write path.
+// Secondary AC path. The primary one is markdown in the task description (a `## Acceptance criteria`
+// heading with `- [ ]` lines), which BlockNote renders as checkboxes; agents should write AC there via
+// opsee_update_task. These tools write the separate acceptance_criteria table for automation that needs
+// machine-trackable AC (PR mapping, workflow output, reporting) and do not surface in the task UI.
 
 function formatCriterion(c: {
   id: number;

package/src/tools/descriptions.ts

@@ -1,10 +1,5 @@
-/**
- * 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.
- */
+/** Description strings shared by more than one tool or schema field. This is LLM-facing contract text,
+ * and drifting copies teach two contracts for one field, so anything repeated lives here. */
 
 /** Task/description authoring rules. Shared by create and update. */
 export const TASK_DESCRIPTION_GUIDANCE =

package/src/tools/doc-links.ts

@@ -6,9 +6,7 @@ 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.
+// Both row types embed the linked DocPage; unwrap so list views reuse formatDocPageList.
 function toDocPages<T extends { docPage?: DocPage }>(rows: T[]): DocPage[] {
   return rows.map((r) => r.docPage).filter((p): p is DocPage => !!p);
 }
@@ -17,9 +15,8 @@ type LinkTarget =
   | { kind: "task" | "milestone"; id: number }
   | { error: { content: [{ type: "text"; text: string }]; isError: true } };
 
-// OPS-203: attach/detach used to be four tools (task and milestone variants of
-// each). They are now one pair with the target passed as a parameter, so the
-// exactly-one-of rule has to be enforced here rather than by the tool split.
+// The task/milestone attach/detach variants became one pair with a target parameter, so the
+// exactly-one-of rule is enforced here rather than by the tool split.
 function resolveTarget(taskId?: number, milestoneId?: number): LinkTarget {
   if ((taskId === undefined) === (milestoneId === undefined)) {
     return {
@@ -124,9 +121,7 @@ export function registerDocLinkTools(
             await clients.milestoneDocPages.deleteMilestoneDocPage({ id: rowId });
           }
         } 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.
+          // A concurrent detach already satisfied the caller's intent, so report success, not NotFound.
           if (deleteError instanceof ConnectError && deleteError.code === Code.NotFound) return notAttached;
           throw deleteError;
         }

package/src/tools/doc-spaces.ts

@@ -127,7 +127,7 @@ export function registerDocSpaceWriteTools(
 
   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.",
+    "Delete a doc space. Doc pages are not linked to doc spaces in the data model — 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 }) => {