@opsee/mcp-server 0.1.6 → 0.1.8

package/src/auth/token-context.ts

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+interface TokenContext {
+  token: string;
+}
+
+export const tokenContext = new AsyncLocalStorage<TokenContext>();
+
+export function getCurrentToken(): string | null {
+  return tokenContext.getStore()?.token ?? null;
+}

package/src/client/api.ts

@@ -3,6 +3,7 @@ import { createConnectTransport } from "@connectrpc/connect-node";
 import { create } from "@bufbuild/protobuf";
 import type { GenService } from "@bufbuild/protobuf/codegenv1";
 import { authManager } from "../auth/manager.js";
+import { getCurrentToken } from "../auth/token-context.js";
 import {
   PaginationSchema,
   type Pagination,
@@ -21,7 +22,9 @@ import { UserService } from "../../gen/api/v1/user_pb.js";
 import { VCSIntegrationService } from "../../gen/api/v1/vcs_integration_pb.js";
 
 const authInterceptor: Interceptor = (next) => async (req) => {
-  const token = authManager.getToken();
+  // Remote mode: token from AsyncLocalStorage (per-request)
+  // Local mode: token from credentials file
+  const token = getCurrentToken() || authManager.getToken();
   if (token) {
     req.header.set("Authorization", `Bearer ${token}`);
   }
@@ -59,33 +62,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/index-http.ts

@@ -0,0 +1,6 @@
+import { startHttpServer } from "./server-http.js";
+
+startHttpServer().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/server-http.ts

@@ -0,0 +1,120 @@
+import express from "express";
+import cors from "cors";
+import { randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { mcpAuthRouter, getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { OpseeOAuthProvider } from "./auth/oauth-provider.js";
+import { tokenContext } from "./auth/token-context.js";
+import { createServer } from "./server.js";
+
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html>
+<head><title>Opsee MCP - Connected</title></head>
+<body style="font-family: system-ui; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background: #f8f9fa;">
+  <div style="text-align: center; padding: 2rem;">
+    <h1 style="color: #10b981;">Connected!</h1>
+    <p>Your Opsee account is now linked. You can close this window.</p>
+  </div>
+</body>
+</html>`;
+
+export async function startHttpServer(): Promise<void> {
+  const port = parseInt(process.env.MCP_PORT || "3100", 10);
+  const host = process.env.MCP_HOST || "0.0.0.0";
+  const serverUrl =
+    process.env.MCP_SERVER_URL || `http://localhost:${port}`;
+  const backendUrl =
+    process.env.OPSEE_API_URL || "https://grpc.api.opsee.ai";
+
+  const provider = new OpseeOAuthProvider(serverUrl);
+  const issuerUrl = new URL(serverUrl);
+
+  // Periodically clean up expired auth entries
+  setInterval(() => provider.cleanup(), 60_000);
+
+  const app = express();
+  // Trust proxy headers (X-Forwarded-For) from 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,
+      issuerUrl,
+      serviceDocumentationUrl: new URL(
+        "https://github.com/ArtisanCloud/opsee",
+      ),
+    }),
+  );
+
+  // --- Custom OAuth callback (Opsee login redirects here) ---
+  app.get("/oauth/callback", (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 = 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);
+  });
+
+  // --- 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.
+
+  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
+    await tokenContext.run({ token: accessToken || "" }, async () => {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined, // stateless — no session IDs
+      });
+
+      const mcpServer = createServer();
+      await mcpServer.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+      await transport.close();
+      await mcpServer.close();
+    });
+  });
+
+  app.listen(port, host, () => {
+    console.log(`Opsee MCP server (remote) listening on ${host}:${port}`);
+    console.log(`  MCP endpoint: ${serverUrl}/mcp`);
+    console.log(`  OAuth authorize: ${serverUrl}/authorize`);
+    console.log(`  Backend: ${backendUrl}`);
+  });
+}

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/tools/cycles.ts

@@ -12,6 +12,7 @@ export function registerCycleTools(
     "opsee_list_cycles",
     "List cycles/sprints in an Opsee project.",
     { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ projectId }) => {
       try {
         const clients = getClients();
@@ -27,6 +28,7 @@ export function registerCycleTools(
     "opsee_get_cycle",
     "Get details of a specific cycle/sprint by ID.",
     { cycleId: z.number().describe("The cycle ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ cycleId }) => {
       try {
         const clients = getClients();
@@ -49,6 +51,7 @@ export function registerCycleTools(
       endDate: z.string().describe("End date (ISO 8601, e.g. 2026-04-08)"),
       description: z.string().optional().describe("Cycle description"),
     },
+    { readOnlyHint: false, destructiveHint: false },
     async ({ projectId, name, startDate, endDate, description }) => {
       try {
         const clients = getClients();

package/src/tools/docs.ts

@@ -29,6 +29,7 @@ export function registerDocTools(
     "opsee_list_doc_spaces",
     "List documentation spaces in an Opsee project.",
     { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ projectId }) => {
       try {
         const clients = getClients();
@@ -55,6 +56,7 @@ export function registerDocTools(
     "opsee_list_doc_pages",
     "List documentation pages in a doc space.",
     { docSpaceId: z.number().describe("The doc space ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ docSpaceId }) => {
       try {
         const clients = getClients();
@@ -81,6 +83,7 @@ export function registerDocTools(
     "opsee_get_doc_page",
     "Read a documentation page's content by ID.",
     { pageId: z.number().describe("The doc page ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ pageId }) => {
       try {
         const clients = getClients();
@@ -103,6 +106,7 @@ export function registerDocTools(
       content: z.string().describe("Page content (text or JSON)"),
       parentPageId: z.number().optional().describe("Parent page ID for nested pages"),
     },
+    { readOnlyHint: false, destructiveHint: false },
     async ({ projectId, title, content, parentPageId }) => {
       try {
         const clients = getClients();

package/src/tools/projects.ts

@@ -11,6 +11,7 @@ export function registerProjectTools(
     "opsee_list_projects",
     "List all Opsee projects the authenticated user has access to.",
     {},
+    { readOnlyHint: true, destructiveHint: false },
     async () => {
       try {
         const clients = getClients();
@@ -26,6 +27,7 @@ export function registerProjectTools(
     "opsee_get_project",
     "Get details of a specific Opsee project by ID.",
     { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ projectId }) => {
       try {
         const clients = getClients();

package/src/tools/repositories.ts

@@ -11,6 +11,7 @@ export function registerRepositoryTools(
     "opsee_list_repositories",
     "List connected VCS repositories (GitHub/GitLab) for an Opsee project.",
     { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ projectId }) => {
       try {
         const clients = getClients();

package/src/tools/task-metadata.ts

@@ -11,6 +11,7 @@ export function registerTaskMetadataTools(
     "opsee_list_task_types",
     "Get available task types (Bug, Feature, etc.) for an Opsee project. Use these IDs when creating or updating tasks.",
     { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ projectId }) => {
       try {
         const clients = getClients();
@@ -32,6 +33,7 @@ export function registerTaskMetadataTools(
     "opsee_list_task_priorities",
     "Get priority levels (Critical, High, Medium, Low, etc.) for an Opsee project. Use these IDs when creating or updating tasks.",
     { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ projectId }) => {
       try {
         const clients = getClients();
@@ -53,6 +55,7 @@ export function registerTaskMetadataTools(
     "opsee_list_boards",
     "List Kanban boards for an Opsee project. Use the board ID to list board columns.",
     { projectId: z.number().describe("The project ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ projectId }) => {
       try {
         const clients = getClients();
@@ -74,6 +77,7 @@ export function registerTaskMetadataTools(
     "opsee_list_board_columns",
     "Get board columns/statuses (To Do, In Progress, Done, etc.) for a board. Use these IDs when creating or updating tasks.",
     { boardId: z.number().describe("The board ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ boardId }) => {
       try {
         const clients = getClients();

package/src/tools/tasks.ts

@@ -25,6 +25,7 @@ export function registerTaskTools(
       page: z.number().optional().describe("Page number (default: 1)"),
       pageSize: z.number().optional().describe("Items per page (default: 50)"),
     },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ projectId, columnId, assigneeId, cycleId, page, pageSize }) => {
       try {
         const clients = getClients();
@@ -57,6 +58,7 @@ export function registerTaskTools(
     "opsee_get_task",
     "Get full details of a specific task by ID.",
     { taskId: z.number().describe("The task ID") },
+    { readOnlyHint: true, destructiveHint: false },
     async ({ taskId }) => {
       try {
         const clients = getClients();
@@ -82,6 +84,7 @@ export function registerTaskTools(
       assigneeId: z.number().optional().describe("Assigned user ID"),
       cycleId: z.number().optional().describe("Cycle/sprint ID"),
     },
+    { readOnlyHint: false, destructiveHint: false },
     async ({ projectId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId }) => {
       try {
         const clients = getClients();
@@ -178,6 +181,7 @@ export function registerTaskTools(
       assigneeId: z.number().optional().describe("New assigned user ID"),
       cycleId: z.number().optional().describe("New cycle/sprint ID"),
     },
+    { readOnlyHint: false, destructiveHint: false },
     async ({ taskId, title, description, taskTypeId, priorityId, boardColumnId, assigneeId, cycleId }) => {
       try {
         const clients = getClients();

package/src/tools/user.ts

@@ -10,6 +10,7 @@ export function registerUserTools(
     "opsee_get_me",
     "Get the currently authenticated Opsee user's profile (name, email, role, company).",
     {},
+    { readOnlyHint: true, destructiveHint: false },
     async () => {
       try {
         const clients = getClients();

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);
 }