@opsee/mcp-server 0.1.7 → 0.2.0

package/README.md

@@ -55,9 +55,73 @@ Ask Claude things like:
 | `opsee_create_doc_page` | Create a new doc page |
 | `opsee_list_repositories` | List connected repositories |
 
-## Cursor / Other MCP Clients
+## Remote MCP Server (Recommended)
 
-Add this to your MCP client config:
+The remote server runs in the cloud with OAuth 2.0 authentication — no local setup or tokens needed.
+
+### Environments
+
+| Environment | URL | Opsee Instance |
+|-------------|-----|----------------|
+| **Production** | `https://mcp.api.opsee.ai/mcp` | `https://opsee.ai` |
+| **Development** | `https://opsee-development.mcp.cls.codilas.link/mcp` | `https://opsee-development.cdn.codilas.link` |
+
+### Claude Code
+
+```bash
+# Production
+claude mcp add opsee --transport http https://mcp.api.opsee.ai/mcp
+
+# Development
+claude mcp add opsee-dev --transport http https://opsee-development.mcp.cls.codilas.link/mcp
+```
+
+Restart Claude Code. On first use, your browser opens for Opsee login. After authenticating, all tools are available immediately.
+
+You can have both environments connected at the same time — use tools prefixed with the server name (e.g. `opsee` for production, `opsee-dev` for development).
+
+### Cursor / Other MCP Clients
+
+```json
+{
+  "mcpServers": {
+    "opsee": {
+      "type": "http",
+      "url": "https://mcp.api.opsee.ai/mcp"
+    }
+  }
+}
+```
+
+Replace the URL with the development endpoint if targeting that environment.
+
+Your MCP client handles the OAuth flow automatically — just sign in when prompted.
+
+### How it works
+
+1. Client connects to the MCP endpoint (e.g. `https://mcp.api.opsee.ai/mcp`)
+2. Server returns 401 with OAuth discovery metadata
+3. Client registers itself and opens the Opsee login page in your browser
+4. After login, the client exchanges the auth code for an access token
+5. All subsequent tool calls use the token automatically
+
+## Local MCP Server (Alternative)
+
+Run the MCP server locally via npx. Requires a one-time login to get a token.
+
+### 1. Authenticate
+
+```bash
+npx @opsee/mcp-server login
+```
+
+### 2. Add to Claude Code
+
+```bash
+claude mcp add opsee -- npx @opsee/mcp-server serve
+```
+
+### Cursor / Other MCP Clients (Local)
 
 ```json
 {
@@ -70,7 +134,7 @@ Add this to your MCP client config:
 }
 ```
 
-## CI / Headless Environments
+### CI / Headless Environments
 
 Skip the browser login by setting a token directly:
 
@@ -88,21 +152,56 @@ Skip the browser login by setting a token directly:
 }
 ```
 
-## Environment Variables
+## Self-Hosting the Remote Server
+
+Deploy the MCP server in your own infrastructure using Docker.
+
+### Docker
+
+```bash
+docker build -f mcp/Dockerfile . -t opsee-mcp-server
+
+docker run -p 3100:3100 \
+  -e MCP_SERVER_URL=https://mcp.yourdomain.com \
+  -e OPSEE_API_URL=http://your-backend:8080 \
+  -e OPSEE_APP_URL=https://your-frontend.com \
+  opsee-mcp-server
+```
+
+### Kubernetes
+
+The server includes Kustomize configs following the same pattern as the backend:
+
+```bash
+# Development
+kubectl apply -k mcp/k8/environments/development/ -n opsee-development
+
+# Production
+kubectl apply -k mcp/k8/environments/production/ -n opsee-production
+```
+
+### 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) | — |
+| `MCP_SERVER_URL` | Public URL of this MCP server (for OAuth redirects) | `http://localhost:3100` |
+| `MCP_HOST` | Bind host | `0.0.0.0` |
+| `MCP_PORT` | Bind port | `3100` |
+| `OPSEE_API_URL` | Backend Connect RPC URL | `https://grpc.api.opsee.ai` |
+| `OPSEE_APP_URL` | Frontend URL (OAuth login page) | `https://opsee.ai` |
+| `OPSEE_API_TOKEN` | Direct JWT token for local mode | — |
 | `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
+# Start backend + frontend locally, then:
 
-# Then add to Claude Code:
+# Local mode (stdio):
+OPSEE_APP_URL=http://localhost:5173 OPSEE_API_URL=http://localhost:9990 npx @opsee/mcp-server login
 claude mcp add opsee -e OPSEE_API_URL=http://localhost:9990 -- npx @opsee/mcp-server serve
+
+# Remote mode (HTTP):
+MCP_SERVER_URL=http://localhost:3100 OPSEE_API_URL=http://localhost:9990 OPSEE_APP_URL=http://localhost:5173 npx @opsee/mcp-server serve-remote
+claude mcp add opsee-local --transport http http://localhost:3100/mcp
 ```

package/bin/opsee-mcp.js

@@ -13,9 +13,15 @@ const tsxPkg = dirname(require.resolve("tsx/package.json"));
 const tsx = resolve(tsxPkg, "dist", "cli.mjs");
 
 const command = process.argv[2];
-const script = command === "login"
-  ? resolve(__dirname, "..", "src", "auth", "login-cli.ts")
-  : resolve(__dirname, "..", "src", "index.ts");
+let script;
+if (command === "login") {
+  script = resolve(__dirname, "..", "src", "auth", "login-cli.ts");
+} else if (command === "serve-remote") {
+  script = resolve(__dirname, "..", "src", "index-http.ts");
+} else {
+  // Default: stdio mode (local)
+  script = resolve(__dirname, "..", "src", "index.ts");
+}
 
 const child = spawn(process.execPath, [tsx, script], { stdio: "inherit", env: process.env });
 child.on("exit", (code) => process.exit(code || 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsee/mcp-server",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Opsee MCP server — manage projects, tasks, docs, and cycles from AI coding environments",
   "type": "module",
   "bin": {
@@ -19,11 +19,15 @@
     "@connectrpc/connect": "^2.0.2",
     "@connectrpc/connect-node": "^2.0.2",
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
     "open": "^10.1.0",
     "tsx": "^4.21.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
     "@types/node": "^22.13.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.0"

package/src/auth/oauth-provider.ts

@@ -0,0 +1,266 @@
+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 {
+    const known = this.clients.get(clientId);
+    if (known) return known;
+
+    // Accept any client ID — required for stateless multi-replica deployments
+    // where registration may have happened on a different pod.
+    // The OAuth flow itself (PKCE + auth code) provides the security.
+    return {
+      client_id: clientId,
+      redirect_uris: [],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code"],
+      response_types: ["code"],
+    } as unknown as OAuthClientInformationFull;
+  }
+
+  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);
+    }
+  }
+}

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

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/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();