@limeadelabs/launchpad-mcp 1.0.0

package/README.md

@@ -0,0 +1,99 @@
+# @limeadelabs/launchpad-mcp
+
+LaunchPad MCP server for Claude Code — manage tasks, pull project context, and track work directly from your coding environment.
+
+## Quick Start
+
+```bash
+# Install via Claude Code CLI
+claude mcp add launchpad -- npx @limeadelabs/launchpad-mcp
+```
+
+Or add manually to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "launchpad": {
+      "command": "npx",
+      "args": ["@limeadelabs/launchpad-mcp"],
+      "env": {
+        "LAUNCHPAD_API_KEY": "your-api-key",
+        "LAUNCHPAD_URL": "https://launchpad.limeadelabs.co"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `LAUNCHPAD_API_KEY` | Yes | — | API key from LaunchPad workspace settings |
+| `LAUNCHPAD_URL` | No | `https://launchpad.limeadelabs.co` | LaunchPad instance URL |
+| `LAUNCHPAD_TIMEOUT_MS` | No | `10000` | Request timeout in milliseconds |
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `lp_bootstrap` | One-call onboarding — workspace, projects, tasks, conventions |
+| `lp_list_projects` | List projects with optional stage filter |
+| `lp_get_project` | Get project details + agent_instructions |
+| `lp_list_tasks` | List tasks with filters (project, status, priority, label, assignee) |
+| `lp_get_task` | Get full task context — description, comments, links |
+| `lp_create_task` | Create a new task |
+| `lp_update_task` | Update task status/fields (enforces workflow transitions) |
+| `lp_claim_task` | Claim a task before working on it |
+| `lp_release_task` | Release a claimed task |
+| `lp_heartbeat` | Keep a claim alive (expires after 30 min without heartbeat) |
+| `lp_add_comment` | Post a comment on a task |
+| `lp_log_time` | Track time spent on a task |
+| `lp_generate_prompt` | Generate a build-ready spec for a task |
+| `lp_list_pages` | List spec/doc pages for a project |
+| `lp_get_page` | Get a page's full content |
+| `lp_get_workflow` | Get valid workflow states and transitions |
+
+## Resources
+
+- `launchpad://project/{id}/context` — Project instructions, conventions, and page summaries
+- `launchpad://task/{id}/spec` — Full generated task spec
+
+## Prompts
+
+- `lp_start_task` — Guided workflow: find → claim → get spec → start building
+- `lp_submit_task` — Guided workflow: comment → update status → release claim
+
+## Example Usage
+
+In Claude Code:
+- "List my LaunchPad tasks"
+- "Claim task #500 and show me the spec"
+- "What's the status of the LaunchPad project?"
+
+## Troubleshooting
+
+**"LAUNCHPAD_API_KEY environment variable is required"**
+Set your API key in the MCP server config. Get one from LaunchPad workspace settings.
+
+**"Invalid LAUNCHPAD_API_KEY"**
+Your API key is expired or incorrect. Generate a new one from LaunchPad.
+
+**"Cannot reach LaunchPad"**
+Check your `LAUNCHPAD_URL` and network connectivity.
+
+**"Request timed out"**
+LaunchPad may be slow. Increase `LAUNCHPAD_TIMEOUT_MS` or try again.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/bin/launchpad-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,590 @@
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/client.ts
+var LaunchPadError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = "LaunchPadError";
+  }
+  statusCode;
+};
+var LaunchPadClient = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.timeoutMs = config.timeoutMs ?? 1e4;
+  }
+  async request(method, path, body) {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        "Authorization": `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: body ? JSON.stringify(body) : void 0,
+      signal: AbortSignal.timeout(this.timeoutMs)
+    });
+    if (!res.ok) {
+      const error = await res.json().catch(() => ({ error: res.statusText }));
+      throw new LaunchPadError(
+        `${method} ${path}: ${res.status} \u2014 ${error.error || res.statusText}`,
+        res.status
+      );
+    }
+    return res.json();
+  }
+  bootstrap() {
+    return this.request("GET", "/agent/bootstrap");
+  }
+  listProjects(params) {
+    const query = params?.stage ? `?stage=${encodeURIComponent(params.stage)}` : "";
+    return this.request("GET", `/projects${query}`);
+  }
+  getProject(id) {
+    return this.request("GET", `/projects/${id}`);
+  }
+  listTasks(params) {
+    const searchParams = new URLSearchParams();
+    if (params.project_id !== void 0) searchParams.set("project_id", String(params.project_id));
+    if (params.status) searchParams.set("status", params.status);
+    if (params.assignee_id !== void 0) searchParams.set("assignee_id", String(params.assignee_id));
+    if (params.priority) searchParams.set("priority", params.priority);
+    if (params.label) searchParams.set("label", params.label);
+    const query = searchParams.toString();
+    return this.request("GET", `/tasks${query ? `?${query}` : ""}`);
+  }
+  getTaskContext(id) {
+    return this.request("GET", `/tasks/${id}/context`);
+  }
+  createTask(data) {
+    return this.request("POST", "/tasks", data);
+  }
+  updateTask(id, data) {
+    return this.request("PATCH", `/tasks/${id}`, data);
+  }
+  claimTask(id) {
+    return this.request("POST", `/tasks/${id}/claim`);
+  }
+  releaseTask(id) {
+    return this.request("POST", `/tasks/${id}/release`);
+  }
+  heartbeat(id) {
+    return this.request("POST", `/tasks/${id}/heartbeat`);
+  }
+  addComment(taskId, body) {
+    return this.request("POST", `/tasks/${taskId}/comments`, { comment: { body } });
+  }
+  generatePrompt(id) {
+    return this.request("POST", `/tasks/${id}/generate_prompt`);
+  }
+  logTime(taskId, durationMinutes, description) {
+    return this.request("POST", `/tasks/${taskId}/time_entries`, {
+      duration_minutes: durationMinutes,
+      ...description !== void 0 && { description }
+    });
+  }
+  listPages(projectId) {
+    return this.request("GET", `/projects/${projectId}/pages`);
+  }
+  getPage(projectId, pageId) {
+    return this.request("GET", `/projects/${projectId}/pages/${pageId}`);
+  }
+  getWorkflow(projectId) {
+    return this.request("GET", `/projects/${projectId}/workflow`);
+  }
+};
+
+// src/tools/shared.ts
+function handleError(error, timeoutMs2) {
+  const message = error instanceof DOMException && error.name === "TimeoutError" ? `Request timed out after ${timeoutMs2}ms. LaunchPad may be slow or unreachable.` : `Error: ${error.message}`;
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+// src/tools/bootstrap.ts
+function registerBootstrapTool(server2, client2) {
+  server2.tool(
+    "lp_bootstrap",
+    "One-call onboarding: returns workspace identity, projects, available tasks, and conventions",
+    {},
+    async () => {
+      try {
+        const result = await client2.bootstrap();
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/projects.ts
+import { z } from "zod";
+function registerProjectTools(server2, client2) {
+  server2.tool(
+    "lp_list_projects",
+    "List all accessible LaunchPad projects with metadata",
+    {
+      stage: z.string().optional().describe("Filter by stage: idea, greenlit, building, shipped, killed")
+    },
+    async (params) => {
+      try {
+        const result = await client2.listProjects(params.stage ? { stage: params.stage } : void 0);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "lp_get_project",
+    "Get project details including agent_instructions",
+    {
+      project_id: z.number().describe("Project ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.getProject(params.project_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/tasks.ts
+import { z as z2 } from "zod";
+function registerTaskTools(server2, client2) {
+  server2.tool(
+    "lp_list_tasks",
+    "List tasks from LaunchPad with optional filters (project, status, priority, label, assignee)",
+    {
+      project_id: z2.number().optional().describe("Filter by project ID"),
+      status: z2.string().optional().describe("Filter by status: todo, ready, in_progress, review, done"),
+      priority: z2.string().optional().describe("Filter by priority: low, medium, high"),
+      label: z2.string().optional().describe("Filter by label name"),
+      assignee_id: z2.number().optional().describe("Filter by assignee user ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.listTasks(params);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "lp_get_task",
+    "Get full task context \u2014 description, comments, links, specs",
+    {
+      task_id: z2.number().describe("Task ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.getTaskContext(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "lp_create_task",
+    "Create a new task in LaunchPad",
+    {
+      project_id: z2.number().describe("Project ID to create the task in"),
+      title: z2.string().describe("Task title"),
+      description: z2.string().optional().describe("Task description"),
+      status: z2.string().optional().describe("Initial status: todo, ready, in_progress, review, done"),
+      priority: z2.string().optional().describe("Priority: low, medium, high")
+    },
+    async (params) => {
+      try {
+        const result = await client2.createTask(params);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "lp_update_task",
+    "Update task status and/or fields. LaunchPad enforces workflow transitions \u2014 use lp_get_workflow to check valid transitions before changing status.",
+    {
+      task_id: z2.number().describe("Task ID"),
+      status: z2.string().optional().describe("New status (must be a valid workflow transition)"),
+      priority: z2.string().optional().describe("New priority: low, medium, high"),
+      assignee_id: z2.number().optional().describe("Assignee user ID"),
+      title: z2.string().optional().describe("New title"),
+      description: z2.string().optional().describe("New description")
+    },
+    async (params) => {
+      try {
+        const { task_id, ...data } = params;
+        const result = await client2.updateTask(task_id, data);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/claims.ts
+import { z as z3 } from "zod";
+function registerClaimTools(server2, client2) {
+  server2.tool(
+    "lp_claim_task",
+    "Claim a task before working on it. Prevents other agents from picking it up.",
+    {
+      task_id: z3.number().describe("Task ID to claim")
+    },
+    async (params) => {
+      try {
+        const result = await client2.claimTask(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "lp_release_task",
+    "Release a claimed task so others can pick it up",
+    {
+      task_id: z3.number().describe("Task ID to release")
+    },
+    async (params) => {
+      try {
+        const result = await client2.releaseTask(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "lp_heartbeat",
+    "Send a heartbeat for a claimed task to keep the claim alive. Claims expire after 30 minutes without a heartbeat.",
+    {
+      task_id: z3.number().describe("Task ID to heartbeat")
+    },
+    async (params) => {
+      try {
+        const result = await client2.heartbeat(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/comments.ts
+import { z as z4 } from "zod";
+function registerCommentTools(server2, client2) {
+  server2.tool(
+    "lp_add_comment",
+    "Post a comment on a task (progress updates, notes, questions)",
+    {
+      task_id: z4.number().describe("Task ID to comment on"),
+      body: z4.string().describe("Comment body text")
+    },
+    async (params) => {
+      try {
+        const result = await client2.addComment(params.task_id, params.body);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/time.ts
+import { z as z5 } from "zod";
+function registerTimeTools(server2, client2) {
+  server2.tool(
+    "lp_log_time",
+    "Track time spent on a task",
+    {
+      task_id: z5.number().describe("Task ID"),
+      duration_minutes: z5.number().positive().describe("Duration in minutes"),
+      description: z5.string().optional().describe("Description of work done")
+    },
+    async (params) => {
+      try {
+        const result = await client2.logTime(params.task_id, params.duration_minutes, params.description);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/prompts.ts
+import { z as z6 } from "zod";
+function registerPromptTools(server2, client2) {
+  server2.tool(
+    "lp_generate_prompt",
+    "Generate a build-ready prompt/spec for a task with full context, conventions, and acceptance criteria",
+    {
+      task_id: z6.number().describe("Task ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.generatePrompt(params.task_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/tools/pages.ts
+import { z as z7 } from "zod";
+function registerPageTools(server2, client2) {
+  server2.tool(
+    "lp_list_pages",
+    "List spec/doc pages for a project",
+    {
+      project_id: z7.number().describe("Project ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.listPages(params.project_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "lp_get_page",
+    "Get a page's full content",
+    {
+      project_id: z7.number().describe("Project ID"),
+      page_id: z7.number().describe("Page ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.getPage(params.project_id, params.page_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+  server2.tool(
+    "lp_get_workflow",
+    "Get valid workflow states and transitions for a project",
+    {
+      project_id: z7.number().describe("Project ID")
+    },
+    async (params) => {
+      try {
+        const result = await client2.getWorkflow(params.project_id);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return handleError(error, client2.timeoutMs);
+      }
+    }
+  );
+}
+
+// src/resources/project-context.ts
+function registerProjectContextResource(server2, client2) {
+  server2.resource(
+    "project-context",
+    "launchpad://project/{project_id}/context",
+    {
+      description: "Project agent_instructions, conventions, and active spec summaries"
+    },
+    async (uri) => {
+      const match = uri.pathname.match(/^\/\/project\/(\d+)\/context$/);
+      if (!match) {
+        throw new Error(`Invalid URI: ${uri.href}`);
+      }
+      const projectId = parseInt(match[1], 10);
+      const project = await client2.getProject(projectId);
+      const pages = await client2.listPages(projectId);
+      const parts = [];
+      parts.push(`# ${project.project.name}`);
+      if (project.project.description) {
+        parts.push(`
+${project.project.description}`);
+      }
+      if (project.project.agent_instructions) {
+        parts.push(`
+## Agent Instructions
+
+${project.project.agent_instructions}`);
+      }
+      if (pages.pages.length > 0) {
+        parts.push(`
+## Pages
+`);
+        for (const page of pages.pages) {
+          parts.push(`- **${page.title}** (updated ${page.updated_at})`);
+        }
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: parts.join("\n")
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/resources/task-spec.ts
+function registerTaskSpecResource(server2, client2) {
+  server2.resource(
+    "task-spec",
+    "launchpad://task/{task_id}/spec",
+    {
+      description: "Full task spec generated by LaunchPad"
+    },
+    async (uri) => {
+      const match = uri.pathname.match(/^\/\/task\/(\d+)\/spec$/);
+      if (!match) {
+        throw new Error(`Invalid URI: ${uri.href}`);
+      }
+      const taskId = parseInt(match[1], 10);
+      const result = await client2.generatePrompt(taskId);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: result.prompt
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/prompts/start-task.ts
+import { z as z8 } from "zod";
+function registerStartTaskPrompt(server2) {
+  server2.prompt(
+    "lp_start_task",
+    "Guided workflow: find a task, claim it, get context, start working",
+    {
+      project_id: z8.string().optional().describe("Optional project ID to filter tasks")
+    },
+    async (args) => {
+      const projectLine = args.project_id ? ` Project ID: ${args.project_id}.` : "";
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `I want to start working on a LaunchPad task.${projectLine}
+
+Please:
+1. Call lp_bootstrap to see available projects and tasks
+2. Show me the available tasks (status: ready) and let me pick one
+3. Once I pick a task, call lp_claim_task to claim it
+4. Call lp_get_task to get the full context
+5. Call lp_generate_prompt to get the build spec
+6. Present the spec and let's start building
+
+IMPORTANT: If this task takes more than 20 minutes, call lp_heartbeat every 20 minutes to keep the claim alive. Claims expire after 30 minutes without a heartbeat.`
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/prompts/submit-task.ts
+import { z as z9 } from "zod";
+function registerSubmitTaskPrompt(server2) {
+  server2.prompt(
+    "lp_submit_task",
+    "Guided workflow: mark task done, add summary comment, release claim",
+    {
+      task_id: z9.string().describe("Task ID to submit"),
+      summary: z9.string().describe("Summary of what was completed")
+    },
+    async (args) => {
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `I've finished working on LaunchPad task #${args.task_id}.
+
+Summary of what was done: ${args.summary}
+
+Please:
+1. Call lp_add_comment with a summary of what was completed
+2. Call lp_update_task to move the task to "review" status (check lp_get_workflow first to confirm valid transitions)
+3. Call lp_release_task to release the claim
+4. Confirm everything is done`
+            }
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/index.ts
+var apiKey = process.env.LAUNCHPAD_API_KEY;
+if (!apiKey) {
+  console.error("Error: LAUNCHPAD_API_KEY environment variable is required.");
+  console.error("Get an API key from your LaunchPad workspace settings.");
+  process.exit(1);
+}
+var baseUrl = process.env.LAUNCHPAD_URL || "https://launchpad.limeadelabs.co";
+var timeoutMs = parseInt(process.env.LAUNCHPAD_TIMEOUT_MS || "10000", 10);
+var client = new LaunchPadClient({ baseUrl, apiKey, timeoutMs });
+try {
+  const bootstrap = await client.bootstrap();
+  console.error(`LaunchPad MCP: Connected as "${bootstrap.agent?.name}" (${bootstrap.projects?.length || 0} projects)`);
+} catch (err) {
+  if (err instanceof LaunchPadError && err.statusCode === 401) {
+    console.error("Error: Invalid LAUNCHPAD_API_KEY. Get a valid key from LaunchPad workspace settings.");
+  } else {
+    console.error(`Error: Cannot reach LaunchPad at ${baseUrl}. Check LAUNCHPAD_URL. (${err.message})`);
+  }
+  process.exit(1);
+}
+var server = new McpServer({
+  name: "launchpad",
+  version: "1.0.0"
+});
+registerBootstrapTool(server, client);
+registerProjectTools(server, client);
+registerTaskTools(server, client);
+registerClaimTools(server, client);
+registerCommentTools(server, client);
+registerTimeTools(server, client);
+registerPromptTools(server, client);
+registerPageTools(server, client);
+registerProjectContextResource(server, client);
+registerTaskSpecResource(server, client);
+registerStartTaskPrompt(server);
+registerSubmitTaskPrompt(server);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@limeadelabs/launchpad-mcp",
+  "version": "1.0.0",
+  "description": "LaunchPad MCP server for Claude Code — AI-native project management integration",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "launchpad-mcp": "bin/launchpad-mcp.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["mcp", "launchpad", "claude", "project-management", "ai-agents"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ]
+}