@opsee/mcp-server 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,207 @@
+# 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 |
+
+## Remote MCP Server (Recommended)
+
+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
+{
+  "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"
+      }
+    }
+  }
+}
+```
+
+## 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 |
+|----------|-------------|---------|
+| `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
+# Start backend + frontend locally, then:
+
+# 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.6",
+  "version": "0.1.8",
   "description": "Opsee MCP server — manage projects, tasks, docs, and cycles from AI coding environments",
   "type": "module",
   "bin": {
@@ -11,20 +11,26 @@
     "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",
     "@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"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.0"
   },
   "engines": {
     "node": ">=18.0.0"