@opsee/mcp-server 0.1.6 → 0.1.8

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/oauth-provider.ts

@@ -0,0 +1,254 @@
+import { randomBytes, randomUUID, createHash } from "node:crypto";
+import type { Response } from "express";
+import type {
+  OAuthServerProvider,
+  AuthorizationParams,
+} from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { OAuthRegisteredClientsStore } from "@modelcontextprotocol/sdk/server/auth/clients.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type {
+  OAuthClientInformationFull,
+  OAuthTokens,
+  OAuthTokenRevocationRequest,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+
+// --- In-memory stores ---
+
+interface PendingAuth {
+  clientId: string;
+  redirectUri: string;
+  state?: string;
+  codeChallenge: string;
+  createdAt: number;
+}
+
+interface AuthCode {
+  token: string;
+  userId: string;
+  companyId: string;
+  expiresAt: string;
+  codeChallenge: string;
+  redirectUri: string;
+  clientId: string;
+  createdAt: number;
+}
+
+const TTL_MS = 10 * 60 * 1000; // 10 minutes
+
+export class OpseeClientStore implements OAuthRegisteredClientsStore {
+  private clients = new Map<string, OAuthClientInformationFull>();
+
+  getClient(clientId: string): OAuthClientInformationFull | undefined {
+    return this.clients.get(clientId);
+  }
+
+  registerClient(
+    client: Omit<OAuthClientInformationFull, "client_id" | "client_id_issued_at">,
+  ): OAuthClientInformationFull {
+    const clientId = randomUUID();
+    const clientSecret = randomBytes(32).toString("hex");
+    const registered: OAuthClientInformationFull = {
+      ...client,
+      client_id: clientId,
+      client_secret: clientSecret,
+      client_id_issued_at: Math.floor(Date.now() / 1000),
+    };
+    this.clients.set(clientId, registered);
+    return registered;
+  }
+}
+
+export class OpseeOAuthProvider implements OAuthServerProvider {
+  private _clientsStore = new OpseeClientStore();
+  private pendingAuths = new Map<string, PendingAuth>();
+  private authCodes = new Map<string, AuthCode>();
+  private revokedTokens = new Set<string>();
+
+  private serverUrl: string;
+  private appUrl: string;
+
+  constructor(serverUrl: string, appUrl?: string) {
+    this.serverUrl = serverUrl;
+    this.appUrl = appUrl || process.env.OPSEE_APP_URL || "https://opsee.ai";
+  }
+
+  get clientsStore(): OAuthRegisteredClientsStore {
+    return this._clientsStore;
+  }
+
+  /**
+   * Step 1: Claude calls /authorize. We redirect to Opsee's login UI.
+   */
+  async authorize(
+    client: OAuthClientInformationFull,
+    params: AuthorizationParams,
+    res: Response,
+  ): Promise<void> {
+    const pendingId = randomBytes(16).toString("hex");
+
+    this.pendingAuths.set(pendingId, {
+      clientId: client.client_id,
+      redirectUri: params.redirectUri,
+      state: params.state,
+      codeChallenge: params.codeChallenge,
+      createdAt: Date.now(),
+    });
+
+    // 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.
+   */
+  async challengeForAuthorizationCode(
+    _client: OAuthClientInformationFull,
+    authorizationCode: string,
+  ): Promise<string> {
+    const code = this.authCodes.get(authorizationCode);
+    if (!code) throw new Error("Invalid authorization code");
+    return code.codeChallenge;
+  }
+
+  /**
+   * Step 3: Claude exchanges auth code for access token.
+   */
+  async exchangeAuthorizationCode(
+    _client: OAuthClientInformationFull,
+    authorizationCode: string,
+  ): Promise<OAuthTokens> {
+    const code = this.authCodes.get(authorizationCode);
+    if (!code) throw new Error("Invalid or expired authorization code");
+
+    if (Date.now() - code.createdAt > TTL_MS) {
+      this.authCodes.delete(authorizationCode);
+      throw new Error("Authorization code expired");
+    }
+
+    // One-time use
+    this.authCodes.delete(authorizationCode);
+
+    // Calculate expires_in from the JWT's expiresAt
+    let expiresIn: number | undefined;
+    if (code.expiresAt) {
+      const expMs = new Date(code.expiresAt).getTime() - Date.now();
+      expiresIn = Math.max(0, Math.floor(expMs / 1000));
+    }
+
+    return {
+      access_token: code.token,
+      token_type: "bearer",
+      expires_in: expiresIn,
+    };
+  }
+
+  async exchangeRefreshToken(): Promise<OAuthTokens> {
+    throw new Error("Refresh tokens are not supported. Re-authenticate to get a new token.");
+  }
+
+  /**
+   * Validate the access token (JWT from Opsee backend).
+   * We do lightweight validation here; the backend does full validation on API calls.
+   */
+  async verifyAccessToken(token: string): Promise<AuthInfo> {
+    if (this.revokedTokens.has(token)) {
+      throw new Error("Token has been revoked");
+    }
+
+    // Decode JWT payload without crypto verification
+    const parts = token.split(".");
+    if (parts.length !== 3) throw new Error("Invalid token format");
+
+    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;
+      throw new Error("Invalid token");
+    }
+  }
+
+  async revokeToken(
+    _client: OAuthClientInformationFull,
+    request: OAuthTokenRevocationRequest,
+  ): Promise<void> {
+    this.revokedTokens.add(request.token);
+  }
+
+  // --- 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(
+    pendingId: string,
+    token: string,
+    userId: string,
+    companyId: string,
+    expiresAt: string,
+  ): { redirectUri: string } | { error: string } {
+    const pending = this.pendingAuths.get(pendingId);
+    if (!pending) return { error: "Invalid or expired pending authorization" };
+
+    if (Date.now() - pending.createdAt > TTL_MS) {
+      this.pendingAuths.delete(pendingId);
+      return { error: "Pending authorization expired" };
+    }
+
+    // One-time use
+    this.pendingAuths.delete(pendingId);
+
+    // Generate authorization code
+    const authCode = randomBytes(32).toString("hex");
+    this.authCodes.set(authCode, {
+      token,
+      userId,
+      companyId,
+      expiresAt,
+      codeChallenge: pending.codeChallenge,
+      redirectUri: pending.redirectUri,
+      clientId: pending.clientId,
+      createdAt: Date.now(),
+    });
+
+    // 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);
+
+    return { redirectUri: url.toString() };
+  }
+
+  /** Periodic cleanup of expired entries */
+  cleanup(): void {
+    const now = Date.now();
+    for (const [id, entry] of this.pendingAuths) {
+      if (now - entry.createdAt > TTL_MS) this.pendingAuths.delete(id);
+    }
+    for (const [code, entry] of this.authCodes) {
+      if (now - entry.createdAt > TTL_MS) this.authCodes.delete(code);
+    }
+  }
+}