mcp-server-cloud-agent 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetalTorque
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,28 +1,43 @@
 # mcp-server-cloud-agent
 
-MCP server for **Cloud Agent** — an AI software engineer that writes code, opens PRs, reviews code, generates tests, runs security scans, and answers codebase questions.
+MCP server for **Cloud Agent** — a hosted AI software engineer that writes code, opens PRs, reviews code, generates tests, runs security scans, and answers codebase questions.
 
 Connect from any MCP client (Claude Code, Cursor, Windsurf, or your own agents) and delegate engineering tasks.
 
+## How it works
+
+This package is a **local stdio MCP proxy** that forwards requests to the Cloud Agent hosted backend at `cloudagent.metaltorque.dev`. Your MCP client communicates with this server over stdio; the server makes authenticated HTTPS calls to the backend on your behalf.
+
+**Data flow:** MCP client → (stdio) → this server → (HTTPS) → Cloud Agent backend → GitHub
+
+**What data leaves your machine:**
+- Task descriptions, repo names, file paths, and PR URLs you provide
+- Your API key (sent over HTTPS only, never over HTTP)
+
+**What the backend does with your data:**
+- Clones repos from GitHub using its own GitHub App credentials
+- Executes tasks in isolated sandboxes
+- Opens PRs and posts reviews to GitHub on your behalf
+
 ## Tools (9)
 
-| Tool | Description |
-|------|-------------|
-| `run_task` | Write code, fix bugs, add features — returns result + PR URL |
-| `review_pr` | Review a GitHub PR with structured feedback, optionally post to GitHub |
-| `ask_codebase` | Ask questions about any GitHub repo (auto-indexes on first use) |
-| `generate_tests` | Generate tests for a file or feature, opens a PR |
-| `security_scan` | Security + dependency scan across one or more repos |
-| `list_sessions` | List recent sessions with status, cost, duration, PR URLs |
-| `list_playbooks` | List available workflow templates (bug-triage, test-coverage, etc.) |
-| `run_playbook` | Run a playbook against a repo |
-| `get_usage` | Usage stats — sessions, cost, time saved, breakdowns |
+| Tool | Description | Side effects |
+|------|-------------|--------------|
+| `run_task` | Write code, fix bugs, add features — returns result + PR URL | Creates branches and PRs |
+| `review_pr` | Review a GitHub PR with structured feedback | Optionally posts comments to GitHub |
+| `ask_codebase` | Ask questions about any GitHub repo (auto-indexes on first use) | Read-only |
+| `generate_tests` | Generate tests for a file, opens a PR | Creates branches and PRs |
+| `security_scan` | Security + dependency scan across one or more repos | Read-only |
+| `list_sessions` | List recent sessions with status, cost, duration, PR URLs | Read-only |
+| `list_playbooks` | List available workflow templates | Read-only |
+| `run_playbook` | Run a playbook against a repo | Creates branches and PRs |
+| `get_usage` | Usage stats — sessions, cost, time saved, breakdowns | Read-only |
 
 ## Setup
 
 ### 1. Get an API key
 
-Sign in to your Cloud Agent web workspace and generate an API key at `/auth/api-key`.
+Sign in to your Cloud Agent workspace at [cloudagent.metaltorque.dev](https://cloudagent.metaltorque.dev) and generate an API key at `/auth/api-key`. Keys use the `ca_*` prefix.
 
 ### 2. Configure your MCP client
 
@@ -68,28 +83,51 @@ Sign in to your Cloud Agent web workspace and generate an API key at `/auth/api-
 Once configured, your MCP client can call these tools directly:
 
 **Fix a bug:**
-> "Use cloud-agent to fix the broken login flow in myorg/myapp"
+> "Use cloud-agent run_task on myorg/myapp to fix the broken login flow"
 
 **Review a PR:**
-> "Use cloud-agent to review https://github.com/myorg/myapp/pull/42"
+> "Use cloud-agent review_pr on https://github.com/myorg/myapp/pull/42"
 
 **Ask about code:**
-> "Use cloud-agent to explain how authentication works in myorg/myapp"
+> "Use cloud-agent ask_codebase on myorg/myapp: how does authentication work?"
 
 **Generate tests:**
-> "Use cloud-agent to generate tests for src/auth.ts in myorg/myapp"
+> "Use cloud-agent generate_tests on myorg/myapp for src/auth.ts"
 
 **Security scan:**
-> "Use cloud-agent to scan myorg/myapp and myorg/api for vulnerabilities"
+> "Use cloud-agent security_scan on myorg/myapp and myorg/api"
+
+## Sample Output
 
-**Run a playbook:**
-> "Use cloud-agent to run the bug-triage playbook on myorg/myapp"
+**run_task response:**
+```json
+{
+  "response": "Fixed the login redirect bug. Changed src/auth.ts to properly handle OAuth callback URLs.",
+  "cost_usd": 0.42,
+  "duration_ms": 45000,
+  "pr_url": "https://github.com/myorg/myapp/pull/87"
+}
+```
 
-## What is Cloud Agent?
+**security_scan response:**
+```json
+{
+  "repos_scanned": 1,
+  "vulnerabilities": 3,
+  "secrets_found": 0,
+  "findings": [...]
+}
+```
 
-Cloud Agent is a Devin-alternative that puts an AI software engineer where your team already works — Slack, Teams, Jira, Linear, and 12 more platforms. It writes code, opens PRs, reviews code, generates tests, runs security scans, and answers codebase questions.
+## Troubleshooting
 
-This MCP server gives any MCP-compatible AI client the same capabilities.
+| Problem | Solution |
+|---------|----------|
+| "CLOUD_AGENT_API_KEY is required" | Set the env var in your MCP client config |
+| "Refusing to send API key over insecure HTTP" | Use HTTPS (the default). Don't set `CLOUD_AGENT_URL` to an HTTP URL |
+| "Request timed out" | Tasks can take up to 10 minutes. Check `list_sessions` for status |
+| "HTTP 401" | Your API key is invalid or expired. Generate a new one |
+| "HTTP 429" | Rate limited. Wait and retry |
 
 ## License
 

package/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["joepangallo"]
+}

package/index.js

@@ -12,6 +12,11 @@ const { version } = require("./package.json");
 const API_KEY = process.env.CLOUD_AGENT_API_KEY || "";
 const BASE_URL = (process.env.CLOUD_AGENT_URL || "https://cloudagent.metaltorque.dev").replace(/\/$/, "");
 
+// ── Shared schemas ──────────────────────────────────────────────────
+
+const repoSchema = z.string().regex(/^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/, "Must be owner/repo format, e.g. 'facebook/react'");
+const prUrlSchema = z.string().url().regex(/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+/, "Must be a GitHub PR URL, e.g. https://github.com/owner/repo/pull/123");
+
 // ── HTTP helper ─────────────────────────────────────────────────────
 
 const MAX_RESPONSE_SIZE = 5 * 1024 * 1024; // 5MB
@@ -70,8 +75,11 @@ function request(method, urlPath, body, timeout = 600_000) {
   });
 }
 
+// ── Shared helpers ──────────────────────────────────────────────────
+
 function noKeyError() {
   return {
+    isError: true,
     content: [{
       type: "text",
       text: "Error: CLOUD_AGENT_API_KEY environment variable is required.\n\nGet an API key from your Cloud Agent web workspace at /auth/api-key.\nAPI keys use the ca_* prefix.",
@@ -79,6 +87,29 @@ function noKeyError() {
   };
 }
 
+function errorResult(e) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: `Error: ${e.message}` }],
+  };
+}
+
+function toolResult(text) {
+  return {
+    content: [{ type: "text", text }],
+  };
+}
+
+async function authedCall(method, path, body, formatter) {
+  if (!API_KEY) return noKeyError();
+  try {
+    const result = await request(method, path, body);
+    return toolResult(formatter(result));
+  } catch (e) {
+    return errorResult(e);
+  }
+}
+
 // ── MCP Server ──────────────────────────────────────────────────────
 
 const server = new McpServer({
@@ -87,31 +118,29 @@ const server = new McpServer({
 });
 
 // ── Tool: run_task ──────────────────────────────────────────────────
+// Positional: tool(name, description, paramsSchema, annotations, handler)
 
 server.tool(
   "run_task",
   "Run a coding task: write code, fix bugs, add features, refactor. The AI agent clones the repo, makes changes, and opens a PR. Returns the result and PR URL when complete.",
   {
-    prompt: z.string().describe("Task description, e.g. 'Fix the login bug in owner/repo' or 'Add dark mode to owner/repo'"),
+    repo: repoSchema.describe("GitHub repo in owner/repo format, e.g. 'facebook/react'"),
+    task: z.string().min(1).describe("Task description, e.g. 'Fix the login bug' or 'Add dark mode to the settings page'"),
+    base_branch: z.string().optional().describe("Branch to base changes on (default: main)"),
   },
-  async ({ prompt }) => {
-    if (!API_KEY) return noKeyError();
-    try {
-      const result = await request("POST", "/query", { prompt });
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            response: result.response,
-            cost_usd: result.cost_usd,
-            duration_ms: result.duration_ms,
-            pr_url: result.pr_url || null,
-          }, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
+  { destructiveHint: true, readOnlyHint: false, openWorldHint: true },
+  async ({ repo, task, base_branch }) => {
+    const prompt = base_branch
+      ? `In ${repo} (branch: ${base_branch}): ${task}`
+      : `In ${repo}: ${task}`;
+    return authedCall("POST", "/query", { prompt }, (result) =>
+      JSON.stringify({
+        response: result.response,
+        cost_usd: result.cost_usd,
+        duration_ms: result.duration_ms,
+        pr_url: result.pr_url || null,
+      }, null, 2)
+    );
   }
 );
 
@@ -121,26 +150,14 @@ server.tool(
   "review_pr",
   "Review a GitHub pull request. Returns structured feedback with issues, verdict, and suggestions. Optionally posts review comments directly to GitHub.",
   {
-    pr_url: z.string().describe("Full GitHub PR URL, e.g. https://github.com/owner/repo/pull/123"),
+    pr_url: prUrlSchema.describe("Full GitHub PR URL, e.g. https://github.com/owner/repo/pull/123"),
     post_comments: z.boolean().optional().describe("Post review comments directly to GitHub (default: false)"),
   },
-  async ({ pr_url, post_comments }) => {
-    if (!API_KEY) return noKeyError();
-    try {
-      const result = await request("POST", "/review", {
-        pr_url,
-        post_review: post_comments === true,
-      });
-      return {
-        content: [{
-          type: "text",
-          text: result.review || JSON.stringify(result, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
-  }
+  { destructiveHint: false, readOnlyHint: false, openWorldHint: true },
+  async ({ pr_url, post_comments }) =>
+    authedCall("POST", "/review", { pr_url, post_review: post_comments === true }, (result) =>
+      result.review || JSON.stringify(result, null, 2)
+    )
 );
 
 // ── Tool: ask_codebase ──────────────────────────────────────────────
@@ -149,58 +166,35 @@ server.tool(
   "ask_codebase",
   "Ask a question about any GitHub repository's codebase. Auto-indexes the repo on first use. Returns an answer with file references.",
   {
-    question: z.string().describe("Question about the codebase, e.g. 'How does authentication work?'"),
-    repo: z.string().describe("GitHub repo in owner/repo format, e.g. 'facebook/react'"),
+    question: z.string().min(1).describe("Question about the codebase, e.g. 'How does authentication work?'"),
+    repo: repoSchema.describe("GitHub repo in owner/repo format, e.g. 'facebook/react'"),
   },
-  async ({ question, repo }) => {
-    if (!API_KEY) return noKeyError();
-    try {
-      const result = await request("POST", "/ask", { question, repo });
-      return {
-        content: [{
-          type: "text",
-          text: result.answer || JSON.stringify(result, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
-  }
+  { destructiveHint: false, readOnlyHint: true, openWorldHint: true },
+  async ({ question, repo }) =>
+    authedCall("POST", "/ask", { question, repo }, (result) =>
+      result.answer || JSON.stringify(result, null, 2)
+    )
 );
 
 // ── Tool: generate_tests ────────────────────────────────────────────
 
 server.tool(
   "generate_tests",
-  "Generate tests for a file or feature in a GitHub repository. Creates test files and opens a PR with them.",
+  "Generate tests for a specific file in a GitHub repository. Creates test files and opens a PR with them.",
   {
-    repo: z.string().describe("GitHub repo in owner/repo format"),
-    file: z.string().optional().describe("Specific file to test, e.g. 'src/auth.ts'"),
-    feature: z.string().optional().describe("Feature to test, e.g. 'user authentication'"),
+    repo: repoSchema.describe("GitHub repo in owner/repo format"),
+    file: z.string().min(1).describe("File to generate tests for, e.g. 'src/auth.ts'"),
   },
-  async ({ repo, file, feature }) => {
-    if (!API_KEY) return noKeyError();
-    const target = file || feature;
-    if (!target) {
-      return { content: [{ type: "text", text: "Error: Provide either 'file' or 'feature' to test." }] };
-    }
-    try {
-      const result = await request("POST", "/test", { file, feature, repo });
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            response: result.response,
-            cost_usd: result.cost_usd,
-            duration_ms: result.duration_ms,
-            pr_url: result.pr_url || null,
-          }, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
-  }
+  { destructiveHint: true, readOnlyHint: false, openWorldHint: true },
+  async ({ repo, file }) =>
+    authedCall("POST", "/test", { file, repo }, (result) =>
+      JSON.stringify({
+        response: result.response,
+        cost_usd: result.cost_usd,
+        duration_ms: result.duration_ms,
+        pr_url: result.pr_url || null,
+      }, null, 2)
+    )
 );
 
 // ── Tool: security_scan ─────────────────────────────────────────────
@@ -209,23 +203,14 @@ server.tool(
   "security_scan",
   "Run a security and dependency scan on one or more GitHub repositories. Checks for vulnerabilities, secret exposure, and security anti-patterns.",
   {
-    repos: z.array(z.string()).describe("Array of repos in owner/repo format, e.g. ['owner/repo1', 'owner/repo2']"),
+    repos: z.array(repoSchema).min(1).describe("Array of repos in owner/repo format, e.g. ['owner/repo1', 'owner/repo2']"),
     type: z.enum(["all", "dependencies", "secrets", "code"]).optional().describe("Scan type (default: all)"),
   },
-  async ({ repos, type }) => {
-    if (!API_KEY) return noKeyError();
-    try {
-      const result = await request("POST", "/scan", { repos, type: type || "all" });
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
-  }
+  { destructiveHint: false, readOnlyHint: true, openWorldHint: true },
+  async ({ repos, type }) =>
+    authedCall("POST", "/scan", { repos, type: type || "all" }, (result) =>
+      JSON.stringify(result, null, 2)
+    )
 );
 
 // ── Tool: list_sessions ─────────────────────────────────────────────
@@ -237,21 +222,13 @@ server.tool(
     limit: z.number().int().min(1).max(100).optional().describe("Max sessions to return (default: 20)"),
     status: z.enum(["running", "completed", "error"]).optional().describe("Filter by session status"),
   },
+  { destructiveHint: false, readOnlyHint: true, openWorldHint: false },
   async ({ limit, status }) => {
-    if (!API_KEY) return noKeyError();
-    try {
-      let path = `/api/sessions?limit=${limit || 20}`;
-      if (status) path += `&status=${status}`;
-      const result = await request("GET", path);
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result.sessions || result, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
+    let path = `/api/sessions?limit=${limit || 20}`;
+    if (status) path += `&status=${status}`;
+    return authedCall("GET", path, undefined, (result) =>
+      JSON.stringify(result.sessions || result, null, 2)
+    );
   }
 );
 
@@ -261,20 +238,10 @@ server.tool(
   "list_playbooks",
   "List available playbooks — reusable workflow templates for common engineering tasks like bug triage, security remediation, test coverage, docs sync, and more.",
   {},
-  async () => {
-    if (!API_KEY) return noKeyError();
-    try {
-      const result = await request("GET", "/api/playbooks");
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
-  }
+  { destructiveHint: false, readOnlyHint: true, openWorldHint: false },
+  async () => authedCall("GET", "/api/playbooks", undefined, (result) =>
+    JSON.stringify(result, null, 2)
+  )
 );
 
 // ── Tool: run_playbook ──────────────────────────────────────────────
@@ -283,24 +250,15 @@ server.tool(
   "run_playbook",
   "Run a playbook (reusable workflow template) against a repository. Use list_playbooks to see available options. Built-in playbooks include: bug-triage, security-remediation, dependency-upgrade, docs-sync, test-coverage, code-migration, pr-review-cycle.",
   {
-    slug: z.string().describe("Playbook slug, e.g. 'bug-triage', 'security-remediation', 'test-coverage'"),
-    repo: z.string().describe("GitHub repo in owner/repo format"),
+    slug: z.string().min(1).describe("Playbook slug, e.g. 'bug-triage', 'security-remediation', 'test-coverage'"),
+    repo: repoSchema.describe("GitHub repo in owner/repo format"),
     inputs: z.record(z.string()).optional().describe("Additional inputs for the playbook template variables"),
   },
-  async ({ slug, repo, inputs }) => {
-    if (!API_KEY) return noKeyError();
-    try {
-      const result = await request("POST", `/api/playbooks/${encodeURIComponent(slug)}/run`, { repo, inputs });
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
-  }
+  { destructiveHint: true, readOnlyHint: false, openWorldHint: true },
+  async ({ slug, repo, inputs }) =>
+    authedCall("POST", `/api/playbooks/${encodeURIComponent(slug)}/run`, { repo, inputs }, (result) =>
+      JSON.stringify(result, null, 2)
+    )
 );
 
 // ── Tool: get_usage ─────────────────────────────────────────────────
@@ -311,20 +269,12 @@ server.tool(
   {
     days: z.number().int().min(1).max(365).optional().describe("Number of days to look back (default: all time)"),
   },
+  { destructiveHint: false, readOnlyHint: true, openWorldHint: false },
   async ({ days }) => {
-    if (!API_KEY) return noKeyError();
-    try {
-      const path = days ? `/api/usage?days=${days}` : "/api/usage";
-      const result = await request("GET", path);
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2),
-        }],
-      };
-    } catch (e) {
-      return { content: [{ type: "text", text: `Error: ${e.message}` }] };
-    }
+    const path = days ? `/api/usage?days=${days}` : "/api/usage";
+    return authedCall("GET", path, undefined, (result) =>
+      JSON.stringify(result, null, 2)
+    );
   }
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-cloud-agent",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "mcpName": "io.github.joepangallo/cloud-agent",
   "description": "MCP server for Cloud Agent — an AI software engineer that writes code, opens PRs, reviews code, generates tests, runs security scans, and answers codebase questions. Connect from any MCP client (Claude Code, Cursor, Windsurf) and delegate engineering tasks.",
   "bin": {
@@ -49,7 +49,9 @@
   "files": [
     "index.js",
     "README.md",
+    "LICENSE",
     "server.json",
+    "glama.json",
     "package.json"
   ],
   "devDependencies": {

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.joepangallo/cloud-agent",
-  "description": "AI software engineer — writes code, opens PRs, reviews code, generates tests, runs security scans, and answers codebase questions.",
+  "description": "AI software engineer — writes code, opens PRs, reviews code, generates tests, and more.",
   "repository": {
     "url": "https://github.com/joepangallo/mcp-server-cloud-agent",
     "source": "github"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "mcp-server-cloud-agent",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "transport": {
         "type": "stdio"
       },