@opsee/mcp-server 0.1.5 → 0.1.7

package/README.md

@@ -0,0 +1,108 @@
+# Opsee MCP Server
+
+Manage your Opsee projects, tasks, docs, and cycles directly from AI-powered coding environments like Claude Code and Cursor.
+
+## Quick Start
+
+### 1. Authenticate
+
+```bash
+npx @opsee/mcp-server login
+```
+
+This opens your browser to sign in to Opsee. Your credentials are saved to `~/.opsee/credentials.json`.
+
+### 2. Add to Claude Code
+
+```bash
+claude mcp add opsee -- npx @opsee/mcp-server serve
+```
+
+### 3. Restart Claude Code
+
+Exit and reopen Claude Code. Run `/mcp` to verify `opsee` shows as connected.
+
+### 4. Start using it
+
+Ask Claude things like:
+- "List my Opsee projects"
+- "Show tasks in project Codlas"
+- "Create a task called 'Fix login bug' in project 1"
+- "What cycles are active in project 1?"
+- "Show me the docs in project 1"
+
+## Available Tools (19)
+
+| Tool | Description |
+|------|-------------|
+| `opsee_get_me` | Get your profile info |
+| `opsee_list_projects` | List all projects |
+| `opsee_get_project` | Get project details |
+| `opsee_list_tasks` | List tasks with filters |
+| `opsee_get_task` | Get task details |
+| `opsee_create_task` | Create a new task |
+| `opsee_update_task` | Update task fields |
+| `opsee_list_task_types` | Get task types (Bug, Feature, etc.) |
+| `opsee_list_task_priorities` | Get priority levels |
+| `opsee_list_boards` | List Kanban boards |
+| `opsee_list_board_columns` | Get board columns/statuses |
+| `opsee_list_cycles` | List cycles/sprints |
+| `opsee_get_cycle` | Get cycle details |
+| `opsee_create_cycle` | Create a new cycle |
+| `opsee_list_doc_spaces` | List doc spaces |
+| `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_list_repositories` | List connected repositories |
+
+## Cursor / Other MCP Clients
+
+Add this to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "opsee": {
+      "command": "npx",
+      "args": ["@opsee/mcp-server", "serve"]
+    }
+  }
+}
+```
+
+## CI / Headless Environments
+
+Skip the browser login by setting a token directly:
+
+```json
+{
+  "mcpServers": {
+    "opsee": {
+      "command": "npx",
+      "args": ["@opsee/mcp-server", "serve"],
+      "env": {
+        "OPSEE_API_TOKEN": "your-jwt-token"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPSEE_API_URL` | Backend gRPC API URL | `https://grpc.api.opsee.ai` |
+| `OPSEE_APP_URL` | Frontend URL (for login) | `https://opsee.ai` |
+| `OPSEE_API_TOKEN` | Direct JWT token (bypasses login) | — |
+| `OPSEE_CREDENTIALS_PATH` | Override credential file path | `~/.opsee/credentials.json` |
+
+## Local Development
+
+```bash
+# With local backend + frontend running:
+OPSEE_APP_URL=http://localhost:5173 OPSEE_API_URL=http://localhost:9990 npx @opsee/mcp-server login
+
+# Then add to Claude Code:
+claude mcp add opsee -e OPSEE_API_URL=http://localhost:9990 -- npx @opsee/mcp-server serve
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsee/mcp-server",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Opsee MCP server — manage projects, tasks, docs, and cycles from AI coding environments",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
     "start": "npx tsx src/index.ts",
     "proto-local": "rm -rf ./gen && cd .. && buf build -o mcp/descriptor.bin && cd mcp && buf generate --include-imports descriptor.bin && rm descriptor.bin",
     "proto": "rm -rf ./gen && curl -k 'https://general.storage.codilas.link/opsee/proto/descriptor.bin' --output ./descriptor.bin && buf generate --include-imports descriptor.bin && rm ./descriptor.bin",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.2.3",
@@ -24,7 +25,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.13.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/__tests__/tools.test.ts

@@ -0,0 +1,465 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+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";
+
+// --- Mock data ---
+
+const mockProject = {
+  id: 1,
+  name: "Test Project",
+  shortName: "TP",
+  slug: "test-project",
+  description: "A test project",
+  isActive: true,
+};
+
+const mockTask = {
+  id: 10,
+  identifier: "TP-1",
+  title: "Fix the bug",
+  description: "Something is broken",
+  displayOrder: 0,
+  storyPoints: 3,
+  aiModeEnabled: false,
+  boardColumn: { id: 1, name: "To Do" },
+  taskPriority: { id: 2, name: "High" },
+  taskType: { id: 1, name: "Bug" },
+  assignedUser: { id: 5, fullName: "Alice" },
+  cycle: { id: 1, name: "Sprint 1" },
+  reporterUser: { id: 5 },
+  board: { id: 1 },
+  project: { id: 1 },
+  taskRepositories: [],
+};
+
+const mockUser = {
+  id: 5,
+  fullName: "Alice Test",
+  email: "alice@test.com",
+  companyId: 1,
+  company: { name: "TestCo" },
+  flattenedRoles: ["User"],
+};
+
+const mockBoard = { id: 1, name: "Main Board", isActive: true };
+const mockBoardColumn = {
+  id: 1,
+  name: "To Do",
+  displayOrder: 0,
+  lifecycleState: "active",
+};
+
+const mockCycle = {
+  id: 1,
+  name: "Sprint 1",
+  description: "First sprint",
+  goal: "Ship v1",
+  startDate: "2026-03-01",
+  endDate: "2026-03-15",
+  isActive: true,
+};
+
+const mockDocSpace = {
+  id: 1,
+  title: "Engineering Docs",
+  description: "Technical documentation",
+  slug: "engineering-docs",
+  isDefault: true,
+};
+
+const mockDocPage = {
+  id: 1,
+  title: "Getting Started",
+  slug: "getting-started",
+  currentContent: "Welcome to the docs",
+  currentVersionNumber: 1,
+  createdByUser: { fullName: "Alice" },
+};
+
+const mockTaskType = { id: 1, name: "Bug" };
+const mockTaskPriority = { id: 2, name: "High", level: 2 };
+const mockVcsIntegration = {
+  id: 1,
+  provider: 2,
+  repoOwner: "acme",
+  repoName: "backend",
+  defaultBranch: "main",
+  isActive: true,
+};
+
+// --- Mock client factory ---
+
+function createMockClients(): ApiClients {
+  return {
+    projects: {
+      getProjects: async () => ({ projects: [mockProject] }),
+      getProject: async () => ({ project: mockProject }),
+    },
+    tasks: {
+      getTasks: async () => ({ tasks: [mockTask] }),
+      getTask: async () => ({ task: mockTask }),
+      addTask: async () => ({ task: mockTask }),
+      editTask: async () => ({ task: { ...mockTask, title: "Updated bug" } }),
+    },
+    boards: {
+      getBoards: async () => ({ boards: [mockBoard] }),
+    },
+    boardColumns: {
+      getBoardColumns: async () => ({ boardColumns: [mockBoardColumn] }),
+    },
+    cycles: {
+      getCycles: async () => ({ cycles: [mockCycle] }),
+      getCycle: async () => ({ cycle: mockCycle }),
+      addCycle: async () => ({ cycle: mockCycle }),
+    },
+    docSpaces: {
+      getDocSpaces: async () => ({ docSpaces: [mockDocSpace] }),
+    },
+    docPages: {
+      getDocPages: async () => ({ docPages: [mockDocPage] }),
+      getDocPage: async () => ({ docPage: mockDocPage }),
+      addDocPage: async () => ({ docPage: mockDocPage }),
+    },
+    taskTypes: {
+      getTaskTypes: async () => ({ taskTypes: [mockTaskType] }),
+    },
+    taskPriorities: {
+      getTaskPriorities: async () => ({
+        taskPriorities: [mockTaskPriority],
+      }),
+    },
+    users: {
+      getMe: async () => ({ user: mockUser }),
+    },
+    vcsIntegrations: {
+      getVCSIntegrations: async () => ({
+        vcsIntegrations: [mockVcsIntegration],
+      }),
+    },
+  } as unknown as ApiClients;
+}
+
+// --- Test suite ---
+
+describe("MCP Tools", () => {
+  let client: Client;
+  let cleanup: () => Promise<void>;
+
+  beforeAll(async () => {
+    const [clientTransport, serverTransport] =
+      InMemoryTransport.createLinkedPair();
+    const server = createServer(() => createMockClients());
+    await server.connect(serverTransport);
+
+    client = new Client({ name: "test-client", version: "1.0.0" });
+    await client.connect(clientTransport);
+
+    cleanup = async () => {
+      await client.close();
+      await server.close();
+    };
+  });
+
+  afterAll(async () => {
+    await cleanup();
+  });
+
+  // --- Project tools ---
+
+  test("opsee_list_projects returns projects", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_projects",
+      arguments: {},
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Test Project");
+    expect(text).toContain("TP");
+    expect(text).toContain("1 project(s)");
+  });
+
+  test("opsee_get_project returns project details", async () => {
+    const result = await client.callTool({
+      name: "opsee_get_project",
+      arguments: { projectId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Test Project");
+    expect(text).toContain("test-project");
+    expect(text).toContain("ID: 1");
+  });
+
+  // --- Task tools ---
+
+  test("opsee_list_tasks returns tasks for a project", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_tasks",
+      arguments: { projectId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("TP-1");
+    expect(text).toContain("Fix the bug");
+    expect(text).toContain("1 task(s)");
+  });
+
+  test("opsee_get_task returns task details", async () => {
+    const result = await client.callTool({
+      name: "opsee_get_task",
+      arguments: { taskId: 10 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("TP-1");
+    expect(text).toContain("Fix the bug");
+    expect(text).toContain("High");
+    expect(text).toContain("Bug");
+  });
+
+  test("opsee_create_task creates a task with defaults", async () => {
+    const result = await client.callTool({
+      name: "opsee_create_task",
+      arguments: { projectId: 1, title: "New task" },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Task created");
+    expect(text).toContain("TP-1");
+  });
+
+  test("opsee_update_task does read-modify-write", async () => {
+    const result = await client.callTool({
+      name: "opsee_update_task",
+      arguments: { taskId: 10, title: "Updated title" },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Task updated");
+  });
+
+  // --- User tools ---
+
+  test("opsee_get_me returns current user", async () => {
+    const result = await client.callTool({
+      name: "opsee_get_me",
+      arguments: {},
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Alice Test");
+    expect(text).toContain("alice@test.com");
+    expect(text).toContain("TestCo");
+  });
+
+  // --- Board/metadata tools ---
+
+  test("opsee_list_boards returns boards", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_boards",
+      arguments: { projectId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Main Board");
+    expect(text).toContain("ID: 1");
+  });
+
+  test("opsee_list_board_columns returns columns", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_board_columns",
+      arguments: { boardId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("To Do");
+    expect(text).toContain("ID: 1");
+  });
+
+  test("opsee_list_task_types returns types", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_task_types",
+      arguments: { projectId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Bug");
+    expect(text).toContain("ID: 1");
+  });
+
+  test("opsee_list_task_priorities returns priorities", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_task_priorities",
+      arguments: { projectId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("High");
+    expect(text).toContain("level: 2");
+  });
+
+  // --- Cycle tools ---
+
+  test("opsee_list_cycles returns cycles", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_cycles",
+      arguments: { projectId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Sprint 1");
+    expect(text).toContain("1 cycle(s)");
+  });
+
+  test("opsee_get_cycle returns cycle details", async () => {
+    const result = await client.callTool({
+      name: "opsee_get_cycle",
+      arguments: { cycleId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Sprint 1");
+    expect(text).toContain("Ship v1");
+    expect(text).toContain("ID: 1");
+  });
+
+  test("opsee_create_cycle creates a cycle", async () => {
+    const result = await client.callTool({
+      name: "opsee_create_cycle",
+      arguments: {
+        projectId: 1,
+        name: "Sprint 2",
+        startDate: "2026-03-25",
+        endDate: "2026-04-08",
+      },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Cycle created");
+    expect(text).toContain("Sprint 1");
+  });
+
+  // --- Doc tools ---
+
+  test("opsee_list_doc_spaces returns spaces", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_doc_spaces",
+      arguments: { projectId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Engineering Docs");
+    expect(text).toContain("1 doc space(s)");
+  });
+
+  test("opsee_list_doc_pages returns pages", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_doc_pages",
+      arguments: { docSpaceId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Getting Started");
+  });
+
+  test("opsee_get_doc_page returns page content", async () => {
+    const result = await client.callTool({
+      name: "opsee_get_doc_page",
+      arguments: { pageId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Getting Started");
+    expect(text).toContain("Welcome to the docs");
+  });
+
+  test("opsee_create_doc_page creates a page", async () => {
+    const result = await client.callTool({
+      name: "opsee_create_doc_page",
+      arguments: {
+        projectId: 1,
+        title: "New Page",
+        content: "Hello world",
+      },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Doc page created");
+    expect(text).toContain("Getting Started");
+  });
+
+  // --- Repository tools ---
+
+  test("opsee_list_repositories returns connected repos", async () => {
+    const result = await client.callTool({
+      name: "opsee_list_repositories",
+      arguments: { projectId: 1 },
+    });
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("acme/backend");
+    expect(text).toContain("GitLab");
+  });
+
+  // --- Error handling ---
+
+  test("tool returns isError on API failure", async () => {
+    const errorClients = createMockClients();
+    (errorClients.projects as any).getProjects = async () => {
+      throw new Error("connection refused ECONNREFUSED");
+    };
+
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    const errorServer = createServer(() => errorClients);
+    await errorServer.connect(st);
+
+    const errorClient = new Client({
+      name: "error-test",
+      version: "1.0.0",
+    });
+    await errorClient.connect(ct);
+
+    const result = await errorClient.callTool({
+      name: "opsee_list_projects",
+      arguments: {},
+    });
+
+    expect(result.isError).toBe(true);
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("ECONNREFUSED");
+
+    await errorClient.close();
+    await errorServer.close();
+  });
+
+  test("auth error returns login instruction", async () => {
+    const authClients = createMockClients();
+    (authClients.users as any).getMe = async () => {
+      throw new Error("Unauthenticated");
+    };
+
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    const authServer = createServer(() => authClients);
+    await authServer.connect(st);
+
+    const authClient = new Client({ name: "auth-test", version: "1.0.0" });
+    await authClient.connect(ct);
+
+    const result = await authClient.callTool({
+      name: "opsee_get_me",
+      arguments: {},
+    });
+
+    expect(result.isError).toBe(true);
+    const text = (result.content as Array<{ type: string; text: string }>)[0]
+      .text;
+    expect(text).toContain("Not authenticated");
+    expect(text).toContain("login");
+
+    await authClient.close();
+    await authServer.close();
+  });
+});

package/src/auth/credentials.ts

@@ -22,7 +22,7 @@ export function readCredentials(): Credentials | null {
   if (process.env.OPSEE_API_TOKEN) {
     return {
       token: process.env.OPSEE_API_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/login.ts

@@ -27,7 +27,7 @@ const ERROR_HTML = `<!DOCTYPE html>
 export async function startLoginFlow(): Promise<void> {
   const port = 9876;
   const callbackUrl = `http://localhost:${port}/callback`;
-  const appUrl = process.env.OPSEE_APP_URL || "https://app.opsee.dev";
+  const appUrl = process.env.OPSEE_APP_URL || "https://opsee.ai";
   const loginUrl = `${appUrl}/auth/mcp?callback=${encodeURIComponent(callbackUrl)}`;
 
   return new Promise<void>((resolve, reject) => {

package/src/auth/manager.ts

@@ -18,7 +18,7 @@ export class AuthManager {
     return (
       process.env.OPSEE_API_URL ||
       this.credentials?.serverUrl ||
-      "https://api.opsee.dev"
+      "https://grpc.api.opsee.ai"
     );
   }
 

package/src/client/api.ts

@@ -59,33 +59,54 @@ export function defaultPagination(
   });
 }
 
-function createTransport() {
-  return createConnectTransport({
-    baseUrl: authManager.getServerUrl(),
-    httpVersion: "1.1",
-    interceptors: [authInterceptor, paginationInterceptor],
-  });
+let transport: ReturnType<typeof createConnectTransport> | null = null;
+let cachedClients: ApiClients | null = null;
+
+function getTransport() {
+  if (!transport) {
+    transport = createConnectTransport({
+      baseUrl: authManager.getServerUrl(),
+      httpVersion: "1.1",
+      interceptors: [authInterceptor, paginationInterceptor],
+    });
+  }
+  return transport;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function makeClient<T extends GenService<any>>(service: T): Client<T> {
-  return createClient(service, createTransport());
+  return createClient(service, getTransport());
 }
 
-export function getClients() {
-  return {
-    projects: makeClient(ProjectService),
-    tasks: makeClient(TaskService),
-    boards: makeClient(BoardService),
-    boardColumns: makeClient(BoardColumnService),
-    cycles: makeClient(CycleService),
-    docSpaces: makeClient(DocSpaceService),
-    docPages: makeClient(DocPageService),
-    taskTypes: makeClient(TaskTypeService),
-    taskPriorities: makeClient(TaskPriorityService),
-    users: makeClient(UserService),
-    vcsIntegrations: makeClient(VCSIntegrationService),
-  };
-}
+export type ApiClients = {
+  projects: Client<typeof ProjectService>;
+  tasks: Client<typeof TaskService>;
+  boards: Client<typeof BoardService>;
+  boardColumns: Client<typeof BoardColumnService>;
+  cycles: Client<typeof CycleService>;
+  docSpaces: Client<typeof DocSpaceService>;
+  docPages: Client<typeof DocPageService>;
+  taskTypes: Client<typeof TaskTypeService>;
+  taskPriorities: Client<typeof TaskPriorityService>;
+  users: Client<typeof UserService>;
+  vcsIntegrations: Client<typeof VCSIntegrationService>;
+};
 
-export type ApiClients = ReturnType<typeof getClients>;
+export function getClients(): ApiClients {
+  if (!cachedClients) {
+    cachedClients = {
+      projects: makeClient(ProjectService),
+      tasks: makeClient(TaskService),
+      boards: makeClient(BoardService),
+      boardColumns: makeClient(BoardColumnService),
+      cycles: makeClient(CycleService),
+      docSpaces: makeClient(DocSpaceService),
+      docPages: makeClient(DocPageService),
+      taskTypes: makeClient(TaskTypeService),
+      taskPriorities: makeClient(TaskPriorityService),
+      users: makeClient(UserService),
+      vcsIntegrations: makeClient(VCSIntegrationService),
+    };
+  }
+  return cachedClients;
+}

package/src/server.ts

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { getClients } from "./client/api.js";
+import { getClients, type ApiClients } from "./client/api.js";
 import { registerUserTools } from "./tools/user.js";
 import { registerProjectTools } from "./tools/projects.js";
 import { registerTaskTools } from "./tools/tasks.js";
@@ -8,19 +8,21 @@ import { registerCycleTools } from "./tools/cycles.js";
 import { registerDocTools } from "./tools/docs.js";
 import { registerRepositoryTools } from "./tools/repositories.js";
 
-export function createServer(): McpServer {
+export function createServer(clientFactory?: () => ApiClients): McpServer {
+  const factory = clientFactory ?? getClients;
+
   const server = new McpServer({
     name: "opsee",
     version: "0.1.0",
   });
 
-  registerUserTools(server, getClients);
-  registerProjectTools(server, getClients);
-  registerTaskTools(server, getClients);
-  registerTaskMetadataTools(server, getClients);
-  registerCycleTools(server, getClients);
-  registerDocTools(server, getClients);
-  registerRepositoryTools(server, getClients);
+  registerUserTools(server, factory);
+  registerProjectTools(server, factory);
+  registerTaskTools(server, factory);
+  registerTaskMetadataTools(server, factory);
+  registerCycleTools(server, factory);
+  registerDocTools(server, factory);
+  registerRepositoryTools(server, factory);
 
   return server;
 }

package/src/utils/format.ts

@@ -126,16 +126,16 @@ export function formatDocPageList(pages: DocPage[]): string {
 
 export function formatError(error: unknown): string {
   if (error instanceof Error) {
-    if (error.message.includes("401") || error.message.includes("Unauthenticated")) {
-      return "Not authenticated. Run `npx opsee-mcp login` to connect your Opsee account.";
+    const msg = error.message;
+    const code = (error as any).code;
+    if (msg.includes("401") || msg.includes("Unauthenticated") || code === "unauthenticated") {
+      return "Not authenticated. Run `npx @opsee/mcp-server login` to connect your Opsee account.";
     }
-    if (error.message.includes("not found") || error.message.includes("404")) {
-      return `Not found. ${error.message}`;
+    if (msg.includes("ECONNREFUSED") || msg.includes("ENOTFOUND")) {
+      return `Could not reach Opsee API. Check your connection and OPSEE_API_URL. (${msg})`;
     }
-    if (error.message.includes("ECONNREFUSED") || error.message.includes("ENOTFOUND")) {
-      return "Could not reach Opsee API. Check your connection and OPSEE_API_URL.";
-    }
-    return error.message;
+    // Show full error details for debugging
+    return code ? `[${code}] ${msg}` : msg;
   }
   return String(error);
 }