@opsee/mcp-server 0.9.14 → 0.9.17

package/package.json

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

package/src/__tests__/kv-store.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from "vitest";
+import { InMemoryKVStore } from "../auth/kv-store.js";
+
+describe("InMemoryKVStore", () => {
+  test("stores and retrieves values", async () => {
+    const kv = new InMemoryKVStore();
+    await kv.set("a", "1");
+    expect(await kv.get("a")).toBe("1");
+    expect(await kv.get("missing")).toBeNull();
+  });
+
+  test("expires entries after their TTL", async () => {
+    const kv = new InMemoryKVStore();
+    await kv.set("a", "1", -1); // already expired
+    expect(await kv.get("a")).toBeNull();
+  });
+
+  test("bounds the store to maxEntries, evicting oldest first", async () => {
+    const kv = new InMemoryKVStore(3);
+    await kv.set("a", "1");
+    await kv.set("b", "2");
+    await kv.set("c", "3");
+    await kv.set("d", "4"); // exceeds cap -> "a" (oldest) evicted
+
+    expect(await kv.get("a")).toBeNull();
+    expect(await kv.get("b")).toBe("2");
+    expect(await kv.get("c")).toBe("3");
+    expect(await kv.get("d")).toBe("4");
+  });
+
+  test("re-setting a key refreshes its position so it is not evicted first", async () => {
+    const kv = new InMemoryKVStore(3);
+    await kv.set("a", "1");
+    await kv.set("b", "2");
+    await kv.set("a", "1-updated"); // refresh a -> b is now oldest
+    await kv.set("c", "3");
+    await kv.set("d", "4"); // evicts oldest live entry (b)
+
+    expect(await kv.get("b")).toBeNull();
+    expect(await kv.get("a")).toBe("1-updated");
+  });
+
+  test("evicts expired entries before live ones when over cap", async () => {
+    const kv = new InMemoryKVStore(2);
+    await kv.set("stale", "x", -1); // expired
+    await kv.set("a", "1");
+    await kv.set("b", "2"); // over cap -> expired "stale" dropped, a/b kept
+
+    expect(await kv.get("stale")).toBeNull();
+    expect(await kv.get("a")).toBe("1");
+    expect(await kv.get("b")).toBe("2");
+  });
+});

package/src/__tests__/tools.test.ts

@@ -3,6 +3,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { createServer } from "../server.js";
 import type { ApiClients } from "../client/api.js";
+import { Code, ConnectError } from "@connectrpc/connect";
 
 // --- Mock data ---
 
@@ -288,6 +289,19 @@ describe("MCP Tools", () => {
     expect(text).toContain("Bug");
   });
 
+  test("opsee_get_task rejects a non-positive / non-integer taskId", async () => {
+    // The ID-validation sweep: an id must be a positive integer. Zero,
+    // negatives, and fractionals fail schema validation (isError) before the
+    // handler runs. A valid positive integer (taskId: 10) succeeds above.
+    for (const taskId of [0, 1.5, -3]) {
+      const result = await client.callTool({
+        name: "opsee_get_task",
+        arguments: { taskId },
+      });
+      expect(result.isError, `taskId=${taskId} should be rejected`).toBe(true);
+    }
+  });
+
   test("opsee_create_task creates a task with defaults", async () => {
     const result = await client.callTool({
       name: "opsee_create_task",
@@ -869,8 +883,10 @@ describe("MCP Tools", () => {
 
   test("auth error returns login instruction", async () => {
     const authClients = createMockClients();
+    // The connect client surfaces backend auth failures as a ConnectError with
+    // Code.Unauthenticated (not a plain Error), which is what formatError keys on.
     (authClients.users as any).getMe = async () => {
-      throw new Error("Unauthenticated");
+      throw new ConnectError("unauthenticated", Code.Unauthenticated);
     };
 
     const [ct, st] = InMemoryTransport.createLinkedPair();

package/src/auth/__tests__/manager.test.ts

@@ -0,0 +1,67 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Credentials } from "../credentials.js";
+
+// Control what the manager reads from disk.
+const { mockRead } = vi.hoisted(() => ({ mockRead: vi.fn() }));
+vi.mock("../credentials.js", () => ({
+  readCredentials: mockRead,
+  clearCredentials: vi.fn(),
+}));
+
+import { AuthManager } from "../manager.js";
+
+const CANONICAL = "https://grpc.api.opsee.ai";
+const LEGACY_STALE = "https://api.opsee.dev";
+
+function creds(serverUrl: string): Credentials {
+  return {
+    token: "jwt.token.here",
+    serverUrl,
+    userId: "u",
+    companyId: "c",
+    expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+  };
+}
+
+// Build a manager whose credentials are populated from `stored` (null = none).
+function managerWith(stored: Credentials | null): AuthManager {
+  mockRead.mockReturnValue(stored);
+  const m = new AuthManager();
+  m.getToken(); // populates the private credentials field, as in real startup
+  return m;
+}
+
+describe("AuthManager.getServerUrl", () => {
+  const OLD_ENV = process.env.OPSEE_API_URL;
+  beforeEach(() => {
+    mockRead.mockReset();
+    delete process.env.OPSEE_API_URL;
+  });
+  afterEach(() => {
+    if (OLD_ENV === undefined) delete process.env.OPSEE_API_URL;
+    else process.env.OPSEE_API_URL = OLD_ENV;
+  });
+
+  test("returns the canonical default when nothing is stored", () => {
+    expect(managerWith(null).getServerUrl()).toBe(CANONICAL);
+  });
+
+  test("returns a stored, non-stale serverUrl unchanged", () => {
+    expect(managerWith(creds("https://custom.example.com")).getServerUrl()).toBe(
+      "https://custom.example.com",
+    );
+  });
+
+  test("treats the legacy stale host as unset and falls back to the canonical default", () => {
+    // The whole point of the migration: existing users with the dead host in
+    // ~/.opsee/credentials.json must NOT be pinned to it, without re-login.
+    expect(managerWith(creds(LEGACY_STALE)).getServerUrl()).toBe(CANONICAL);
+  });
+
+  test("OPSEE_API_URL env var overrides both stored and default", () => {
+    process.env.OPSEE_API_URL = "https://env.example.com";
+    expect(managerWith(creds("https://custom.example.com")).getServerUrl()).toBe(
+      "https://env.example.com",
+    );
+  });
+});

package/src/auth/__tests__/oauth-provider.test.ts

@@ -224,4 +224,49 @@ describe("OpseeOAuthProvider flow", () => {
     await provider.revokeToken(client, { token });
     await expect(provider.verifyAccessToken(token)).rejects.toThrow(/revoked/);
   });
+
+  // --- verifyAccessToken validation edge cases (require exp) ---
+
+  // Build a JWT-shaped token (header.payload.sig) from a payload object.
+  const tokenWith = (payload: Record<string, unknown>) =>
+    `header.${Buffer.from(JSON.stringify(payload)).toString("base64url")}.sig`;
+
+  test("accepts a token with a future exp and exposes its claims", async () => {
+    const future = Math.floor(Date.now() / 1000) + 3600;
+    const token = tokenWith({ exp: future, userId: "u1", companyId: "c1", role: "admin" });
+    await expect(provider.verifyAccessToken(token)).resolves.toMatchObject({
+      clientId: "opsee",
+      expiresAt: future,
+      extra: { userId: "u1", companyId: "c1", role: "admin" },
+    });
+  });
+
+  test("rejects a token with no exp claim (not valid indefinitely)", async () => {
+    const token = tokenWith({ userId: "u", companyId: "c" });
+    await expect(provider.verifyAccessToken(token)).rejects.toThrow(/missing expiry/i);
+  });
+
+  test("rejects a token whose exp is not a number", async () => {
+    const token = tokenWith({ exp: "later", userId: "u" });
+    await expect(provider.verifyAccessToken(token)).rejects.toThrow(/missing expiry/i);
+  });
+
+  test("rejects an expired token", async () => {
+    const past = Math.floor(Date.now() / 1000) - 10;
+    const token = tokenWith({ exp: past, userId: "u" });
+    await expect(provider.verifyAccessToken(token)).rejects.toThrow(/expired/i);
+  });
+
+  test("rejects a token with a non-JSON payload as Invalid token", async () => {
+    const badBody = Buffer.from("this is not json").toString("base64url");
+    await expect(provider.verifyAccessToken(`header.${badBody}.sig`)).rejects.toThrow(
+      /Invalid token/,
+    );
+  });
+
+  test("rejects a token that is not three parts", async () => {
+    await expect(provider.verifyAccessToken("only.two")).rejects.toThrow(
+      /Invalid token format/,
+    );
+  });
 });

package/src/auth/kv-store.ts

@@ -24,6 +24,11 @@ export interface KVStore {
  */
 export class InMemoryKVStore implements KVStore {
   private entries = new Map<string, { value: string; expiresAt: number | null }>();
+  private readonly maxEntries: number;
+
+  constructor(maxEntries = 10_000) {
+    this.maxEntries = maxEntries;
+  }
 
   async get(key: string): Promise<string | null> {
     const entry = this.entries.get(key);
@@ -38,12 +43,40 @@ export class InMemoryKVStore implements KVStore {
   async set(key: string, value: string, ttlSeconds?: number): Promise<void> {
     const expiresAt =
       ttlSeconds !== undefined ? Date.now() + ttlSeconds * 1000 : null;
+    // Re-insert so the most recently set key sorts last in iteration order and
+    // is evicted last.
+    this.entries.delete(key);
     this.entries.set(key, { value, expiresAt });
+    this.evictIfNeeded();
   }
 
   async del(key: string): Promise<void> {
     this.entries.delete(key);
   }
+
+  /**
+   * Bound memory. Dynamic client registrations are stored without a TTL (by
+   * design — clients cache their DCR indefinitely), so without a cap this
+   * fallback store grows forever in a long-running remote process that has no
+   * Redis. Evict expired entries first, then the oldest live entries.
+   */
+  private evictIfNeeded(): void {
+    if (this.entries.size <= this.maxEntries) return;
+
+    const now = Date.now();
+    for (const [k, e] of this.entries) {
+      if (e.expiresAt !== null && now > e.expiresAt) {
+        this.entries.delete(k);
+        if (this.entries.size <= this.maxEntries) return;
+      }
+    }
+
+    while (this.entries.size > this.maxEntries) {
+      const oldest = this.entries.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.entries.delete(oldest);
+    }
+  }
 }
 
 /** Redis-backed store. Expiry is delegated to Redis via the EX option. */

package/src/auth/login.ts

@@ -43,7 +43,7 @@ export async function startLoginFlow(): Promise<void> {
         if (token) {
           const credentials: Credentials = {
             token,
-            serverUrl: process.env.OPSEE_API_URL || "https://api.opsee.dev",
+            serverUrl: process.env.OPSEE_API_URL || "https://grpc.api.opsee.ai",
             userId,
             companyId,
             expiresAt,

package/src/auth/manager.ts

@@ -1,5 +1,11 @@
 import { readCredentials, clearCredentials, type Credentials } from "./credentials.js";
 
+const DEFAULT_SERVER_URL = "https://grpc.api.opsee.ai";
+// A stale default that older login builds wrote to ~/.opsee/credentials.json.
+// It points at a dead host, so treat a stored value of it as "unset" and fall
+// back to the canonical default instead of forcing users to re-login.
+const LEGACY_STALE_SERVER_URL = "https://api.opsee.dev";
+
 export class AuthManager {
   private credentials: Credentials | null = null;
 
@@ -15,10 +21,11 @@ export class AuthManager {
   }
 
   getServerUrl(): string {
+    const stored = this.credentials?.serverUrl;
     return (
       process.env.OPSEE_API_URL ||
-      this.credentials?.serverUrl ||
-      "https://grpc.api.opsee.ai"
+      (stored && stored !== LEGACY_STALE_SERVER_URL ? stored : undefined) ||
+      DEFAULT_SERVER_URL
     );
   }
 

package/src/auth/oauth-provider.ts

@@ -193,31 +193,37 @@ export class OpseeOAuthProvider implements OAuthServerProvider {
     const parts = token.split(".");
     if (parts.length !== 3) throw new Error("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.
+    let payload: { exp?: unknown; userId?: unknown; companyId?: unknown; role?: unknown };
     try {
-      const payload = JSON.parse(
-        Buffer.from(parts[1], "base64url").toString("utf-8"),
-      );
-
-      // Check expiry
-      if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
-        throw new Error("Token expired");
-      }
-
-      return {
-        token,
-        clientId: "opsee",
-        scopes: [],
-        expiresAt: payload.exp,
-        extra: {
-          userId: payload.userId,
-          companyId: payload.companyId,
-          role: payload.role,
-        },
-      };
-    } catch (err) {
-      if (err instanceof Error && err.message === "Token expired") throw err;
+      payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+    } catch {
       throw new Error("Invalid token");
     }
+
+    // Require an expiry claim and reject expired tokens. A token that omits
+    // exp must not be treated as valid indefinitely.
+    if (typeof payload.exp !== "number") {
+      throw new Error("Token missing expiry");
+    }
+    if (payload.exp < Math.floor(Date.now() / 1000)) {
+      throw new Error("Token expired");
+    }
+
+    return {
+      token,
+      clientId: "opsee",
+      scopes: [],
+      expiresAt: payload.exp,
+      extra: {
+        userId: payload.userId,
+        companyId: payload.companyId,
+        role: payload.role,
+      },
+    };
   }
 
   async revokeToken(

package/src/server-http.ts

@@ -21,7 +21,40 @@ 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.
+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).
+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.
+  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.
+  process.on("uncaughtException", (err) => {
+    console.error("Uncaught exception:", err);
+    process.exit(1);
+  });
+}
+
 export async function startHttpServer(): Promise<void> {
+  registerProcessGuards();
+
   const port = parseInt(process.env.MCP_PORT || "3100", 10);
   const host = process.env.MCP_HOST || "0.0.0.0";
   const serverUrl =
@@ -57,28 +90,41 @@ export async function startHttpServer(): Promise<void> {
 
   // --- Custom OAuth callback (Opsee login redirects here) ---
   app.get("/oauth/callback", async (req, res) => {
-    const { pending, token, userId, companyId, expiresAt } = req.query as Record<string, string>;
-
-    if (!pending || !token) {
-      res.status(400).send("Missing pending or token parameter");
-      return;
-    }
-
-    const result = await provider.handleCallback(
-      pending,
-      token,
-      userId || "",
-      companyId || "",
-      expiresAt || "",
-    );
-
-    if ("error" in result) {
-      res.status(400).send(result.error);
-      return;
+    try {
+      const pending = singleQueryParam(req.query.pending);
+      const token = singleQueryParam(req.query.token);
+      const userId = singleQueryParam(req.query.userId) ?? "";
+      const companyId = singleQueryParam(req.query.companyId) ?? "";
+      const expiresAt = singleQueryParam(req.query.expiresAt) ?? "";
+
+      if (!pending || !token) {
+        res.status(400).send("Missing or invalid pending or token parameter");
+        return;
+      }
+
+      const result = await provider.handleCallback(
+        pending,
+        token,
+        userId,
+        companyId,
+        expiresAt,
+      );
+
+      if ("error" in result) {
+        res.status(400).send(result.error);
+        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.
+      console.error("OAuth callback failed:", err);
+      if (!res.headersSent) {
+        res.status(500).send("Internal server error during OAuth callback");
+      }
     }
-
-    // Redirect to Claude's redirect_uri with the auth code
-    res.redirect(result.redirectUri);
   });
 
   // --- Bearer auth middleware for MCP endpoints ---
@@ -103,13 +149,44 @@ export async function startHttpServer(): Promise<void> {
       });
 
       const mcpServer = createServer();
-      await mcpServer.connect(transport);
-      await transport.handleRequest(req, res, req.body);
-      await transport.close();
-      await mcpServer.close();
+      try {
+        await mcpServer.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+      } catch (err) {
+        console.error("MCP request handling failed:", err);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: "2.0",
+            error: { code: -32603, message: "Internal server error" },
+            id: null,
+          });
+        }
+      } finally {
+        // Always tear down the per-request transport+server, even on error,
+        // so they are not leaked on every failed request.
+        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.
+  app.use(
+    (
+      err: unknown,
+      _req: express.Request,
+      res: express.Response,
+      _next: express.NextFunction,
+    ) => {
+      console.error("Unhandled request error:", err);
+      if (!res.headersSent) {
+        res.status(500).json({ error: "Internal server error" });
+      }
+    },
+  );
+
   app.listen(port, host, () => {
     console.log(`Opsee MCP server (remote) listening on ${host}:${port}`);
     console.log(`  MCP endpoint: ${serverUrl}/mcp`);

package/src/tools/acceptance-criteria.ts

@@ -35,7 +35,7 @@ export function registerAcceptanceCriterionTools(
   server.tool(
     "opsee_list_task_acceptance_criteria",
     "Lists STRUCTURED acceptance criteria from a separate DB entity, NOT the checklist items inside the task description. Most tasks have their AC inline in the description as `- [ ]` markdown — to read those, fetch the task description via opsee_get_task and parse the checklist lines yourself. This tool only returns rows from the `acceptance_criteria` table, which is the automation/power-user path, not the main UI. Returns items ordered by display_order then id with text + done flag + display_order.",
-    { taskId: z.number().describe("The task ID") },
+    { taskId: z.number().int().min(1).describe("The task ID") },
     { readOnlyHint: true, destructiveHint: false },
     async ({ taskId }) => {
       try {
@@ -57,7 +57,7 @@ export function registerAcceptanceCriterionTools(
     "opsee_add_acceptance_criterion",
     "POWER-USER PATH — writes a STRUCTURED criterion to the `acceptance_criteria` DB table, which does NOT surface in the task detail UI. For typical AC, use opsee_update_task and write `- [ ]` checkbox lines under a `## Acceptance criteria` heading in the task description instead — those render as clickable checkboxes via BlockNote. Use this tool only when you need machine-trackable AC for automation (e.g. mapping criteria to PRs, AI workflow outputs, reporting). display_order defaults to 0; pass an explicit value to control ordering.",
     {
-      taskId: z.number().describe("The task ID"),
+      taskId: z.number().int().min(1).describe("The task ID"),
       text: z.string().min(1).max(2000).describe("Criterion text (what passing this AC looks like)"),
       displayOrder: z.number().int().optional().describe("Display order (default: 0)"),
     },
@@ -84,7 +84,7 @@ export function registerAcceptanceCriterionTools(
     "opsee_update_acceptance_criterion",
     "POWER-USER PATH — patches a STRUCTURED criterion in the `acceptance_criteria` DB table. Does NOT touch description-embedded checkboxes; those live in the task description and are edited via opsee_update_task's description field. Use this only for the automation path that created the criterion via opsee_add_acceptance_criterion. Patch semantics: any subset of text / done / displayOrder; fields not supplied are left alone.",
     {
-      criterionId: z.number().describe("The criterion ID"),
+      criterionId: z.number().int().min(1).describe("The criterion ID"),
       text: z.string().max(2000).optional().describe("New text"),
       done: z.boolean().optional().describe("Mark complete or incomplete"),
       displayOrder: z.number().int().optional().describe("New display order"),
@@ -112,7 +112,7 @@ export function registerAcceptanceCriterionTools(
   server.tool(
     "opsee_delete_acceptance_criterion",
     "POWER-USER PATH — deletes a STRUCTURED criterion row from the `acceptance_criteria` DB table by ID. Does NOT remove `- [ ]` lines from a task description; for those, edit the description via opsee_update_task. Soft delete; this is permanent at the application layer.",
-    { criterionId: z.number().describe("The criterion ID") },
+    { criterionId: z.number().int().min(1).describe("The criterion ID") },
     { readOnlyHint: false, destructiveHint: true },
     async ({ criterionId }) => {
       try {

package/src/tools/comments.ts

@@ -17,10 +17,10 @@ export function registerCommentTools(
     "opsee_list_comments",
     "List comments on a task or an Initiative, oldest first. Includes both regular and internal comments visible to the caller. Provide exactly one of taskId or initiativeId.",
     {
-      taskId: z.number().optional().describe("The task ID (provide exactly one of taskId or initiativeId)"),
-      initiativeId: z.number().optional().describe("The initiative ID (provide exactly one of taskId or initiativeId)"),
-      page: z.number().optional().describe("Page number (default: 1)"),
-      pageSize: z.number().optional().describe("Items per page (default: 50)"),
+      taskId: z.number().int().min(1).optional().describe("The task ID (provide exactly one of taskId or initiativeId)"),
+      initiativeId: z.number().int().min(1).optional().describe("The initiative ID (provide exactly one of taskId or initiativeId)"),
+      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 ({ taskId, initiativeId, page, pageSize }) => {
@@ -42,8 +42,8 @@ export function registerCommentTools(
     "opsee_add_comment",
     "Add a comment to a task or an Initiative. Posts as the authenticated user. Provide exactly one of taskId or initiativeId. Set isInternal=true to mark the comment as internal (visibility depends on backend RBAC).",
     {
-      taskId: z.number().optional().describe("The task ID to comment on (provide exactly one of taskId or initiativeId)"),
-      initiativeId: z.number().optional().describe("The initiative ID to comment on (provide exactly one of taskId or initiativeId)"),
+      taskId: z.number().int().min(1).optional().describe("The task ID to comment on (provide exactly one of taskId or initiativeId)"),
+      initiativeId: z.number().int().min(1).optional().describe("The initiative ID to comment on (provide exactly one of taskId or initiativeId)"),
       content: z.string().min(1).describe("Comment body"),
       isInternal: z.boolean().optional().describe("Mark as internal comment (default: false)"),
     },
@@ -86,7 +86,7 @@ export function registerCommentTools(
     "opsee_edit_comment",
     "Edit an existing comment's content and/or internal flag. Posts as the original author. Use opsee_list_comments first to confirm the comment ID.",
     {
-      commentId: z.number().describe("The comment ID to edit"),
+      commentId: z.number().int().min(1).describe("The comment ID to edit"),
       content: z.string().min(1).describe("New comment body"),
       isInternal: z.boolean().optional().describe("Update the internal flag (defaults to the comment's existing value if omitted)"),
     },
@@ -124,7 +124,7 @@ export function registerCommentTools(
   server.tool(
     "opsee_delete_comment",
     "Delete a comment by ID. This is permanent.",
-    { commentId: z.number().describe("The comment ID") },
+    { commentId: z.number().int().min(1).describe("The comment ID") },
     { readOnlyHint: false, destructiveHint: true },
     async ({ commentId }) => {
       try {