@limeadelabs/clarabit-mcp 2.0.0

package/README.md

@@ -0,0 +1,135 @@
+# @limeadelabs/clarabit-mcp
+
+Clarabit 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 clarabit -- npx @limeadelabs/clarabit-mcp
+```
+
+Or add manually to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "clarabit": {
+      "command": "npx",
+      "args": ["@limeadelabs/clarabit-mcp"],
+      "env": {
+        "CLARABIT_API_KEY": "your-api-key",
+        "CLARABIT_URL": "https://app.clarabit.ai"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CLARABIT_API_KEY` | Yes | — | API key from Clarabit workspace settings |
+| `CLARABIT_URL` | No | `https://app.clarabit.ai` | Clarabit instance URL |
+| `CLARABIT_TIMEOUT_MS` | No | `10000` | Request timeout in milliseconds |
+
+The previous `LAUNCHPAD_API_KEY` / `LAUNCHPAD_URL` / `LAUNCHPAD_TIMEOUT_MS` variables are still read for one transition release; using them logs a deprecation warning. They will be removed in a future release.
+
+## Tools
+
+All tools use the `cla_` prefix (renamed from `lp_` in v2.0).
+
+| Tool | Description |
+|------|-------------|
+| `cla_bootstrap` | One-call onboarding — workspace, projects, tasks, conventions |
+| `cla_list_projects` | List projects with optional stage filter |
+| `cla_get_project` | Get project details + agent_instructions |
+| `cla_list_tasks` | List tasks with filters (project, status, priority, label, assignee) |
+| `cla_get_task` | Get full task context — description, comments, links |
+| `cla_create_task` | Create a new task |
+| `cla_update_task` | Update task status/fields (enforces workflow transitions) |
+| `cla_claim_task` | Claim a task before working on it |
+| `cla_release_task` | Release a claimed task |
+| `cla_heartbeat` | Keep a claim alive (expires after 30 min without heartbeat) |
+| `cla_add_comment` | Post a comment on a task |
+| `cla_log_time` | Track time spent on a task |
+| `cla_generate_prompt` | Generate a build-ready spec for a task |
+| `cla_list_pages` | List spec/doc pages for a project |
+| `cla_get_page` | Get a page's full content (`project_id` optional — sub-second when omitted via flat endpoint) |
+| `cla_create_page` | Create a new spec/doc page |
+| `cla_update_page` | Update a page; every MCP edit creates a new version (no debounce). `project_id` optional. Optional `change_summary` |
+| `cla_list_page_versions` | List version history for a page (`project_id` optional) |
+| `cla_get_page_version` | Read a specific historical version's full body (`project_id` optional) |
+| `cla_restore_page_version` | Restore a page to a previous version (`project_id` optional; pre-restore content is snapshotted) |
+| `cla_create_page_comment` | Post a comment on a page (supports threading + text anchors) |
+| `cla_update_page_comment` | Edit your own page comment (403 if you are not the author) |
+| `cla_resolve_page_comment` | Mark a page comment resolved (anyone with project access can resolve) |
+| `cla_unresolve_page_comment` | Reopen a previously resolved page comment |
+| `cla_get_workflow` | Get valid workflow states and transitions |
+| `cla_context_list` | List context entries with optional filters (project, type, search) |
+| `cla_context_get` | Fetch a context entry's full content by slug or ID |
+| `cla_context_package` | Get assembled context package for a task (org + project entries, specs, comments) |
+| `cla_context_update` | Update a context entry's content (requires write access) |
+
+## Resources
+
+- `clarabit://project/{id}/context` — Project instructions, conventions, and page summaries
+- `clarabit://task/{id}/spec` — Full generated task spec
+- `context://entries` — Browse all active context entries
+- `context://entries/{slug}` — Read a specific context entry
+
+### Resources vs Tools
+
+Resources are for **passive browsing** in the Claude Code resource panel. Tools are for **active agent invocation** during conversation. Both access the same underlying context registry API.
+
+## Prompts
+
+- `cla_start_task` — Guided workflow: find → claim → get spec → start building
+- `cla_submit_task` — Guided workflow: comment → update status → release claim
+
+## Example Usage
+
+In Claude Code:
+- "List my Clarabit tasks"
+- "Claim task #500 and show me the spec"
+- "What's the status of the Clarabit project?"
+
+## Troubleshooting
+
+**"CLARABIT_API_KEY environment variable is required"**
+Set your API key in the MCP server config. Get one from Clarabit workspace settings.
+
+**"Invalid CLARABIT_API_KEY"**
+Your API key is expired or incorrect. Generate a new one from Clarabit.
+
+**"Cannot reach Clarabit"**
+Check your `CLARABIT_URL` and network connectivity.
+
+**"Request timed out"**
+Clarabit may be slow. Increase `CLARABIT_TIMEOUT_MS` or try again.
+
+## Migration from `@limeadelabs/launchpad-mcp` v1.x
+
+v2.0 renames the package, env vars, tool names, resource URIs, and session file location. Migration steps:
+
+1. Update your `.mcp.json` (or claude_desktop_config.json):
+   - Server key: `"launchpad"` → `"clarabit"`
+   - Package: `@limeadelabs/launchpad-mcp` → `@limeadelabs/clarabit-mcp`
+   - Env vars: `LAUNCHPAD_API_KEY` → `CLARABIT_API_KEY`, etc.
+2. The old env var names are still honored in v2.0 with a deprecation warning. They will be removed in a future release.
+3. Active session state moves from `~/.launchpad/active-session.json` to `~/.clarabit/active-session.json`. Mid-task agents will need to re-claim once after upgrading; subsequent claims work normally.
+4. Tool names changed prefix `lp_*` → `cla_*` (e.g. `cla_create_task`).
+5. Resource URIs changed scheme `launchpad://` → `clarabit://`.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/bin/clarabit-mcp.js

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

package/dist/index.d.ts

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