rhythmic-mcp 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# rhythmic-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes Rhythmic to coding agents
+(Claude Code, Cursor, Claude Desktop, …) as typed tools. It's a thin wrapper over the
+authenticated `/api/v1` HTTP API — all auth, tenant-scoping, and validation live there.
+
+> Rhythmic is in **free public beta**.
+
+## Quick start
+
+1. In Rhythmic, open **Settings → API keys** and create a key (the secret is shown once).
+2. Register the server with your agent using `npx` — no install or build step needed.
+
+The key can be passed as a `--api-key` flag (recommended for `mcpServers` JSON) or via the
+`RHYTHMIC_API_KEY` environment variable. A flag wins over the env var.
+
+### Claude Desktop / Cursor (`mcpServers` JSON)
+
+```json
+{
+  "mcpServers": {
+    "rhythmic": {
+      "command": "npx",
+      "args": ["-y", "rhythmic-mcp", "--api-key", "rhy_xxxxx"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add rhythmic -- npx -y rhythmic-mcp --api-key rhy_xxxxx
+```
+
+Or keep the key out of the command with an env var:
+
+```bash
+claude mcp add rhythmic -e RHYTHMIC_API_KEY=rhy_xxxxx -- npx -y rhythmic-mcp
+```
+
+## Configuration
+
+| Flag | Env var | Default | |
+|------|---------|---------|--|
+| `--api-key`, `-k` | `RHYTHMIC_API_KEY` | — | API key from Settings → API keys (required) |
+| `--url`, `--api-url` | `RHYTHMIC_API_URL` | `https://rhythmicapp.dev` | Rhythmic base URL |
+| `--help`, `-h` | | | Print usage |
+| `--version`, `-v` | | | Print version |
+
+Pointing at a local dev server? Use `--url http://localhost:3000`.
+
+## Local development
+
+From the monorepo, run against `src` without building:
+
+```bash
+pnpm --filter rhythmic-mcp dev -- --api-key rhy_xxxxx --url http://localhost:3000
+```
+
+Or build and run the compiled output:
+
+```bash
+pnpm --filter rhythmic-mcp build
+node packages/mcp/dist/index.js --api-key rhy_xxxxx --url http://localhost:3000
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List projects in the workspace |
+| `get_project` | Project (by key) + its cycles |
+| `list_issues` | Issues, filtered by project/status/assignee/cycle (paginated) |
+| `get_issue` | Full issue detail incl. comments + dependency edges |
+| `create_issue` | Create an issue |
+| `update_issue` | Update status/priority/title/description/assignee/cycle |
+| `comment_issue` | Comment on an issue (as the key's user) |
+| `set_work_status` | Toggle the live "agent is working" spinner on an issue |
+| `link_issues` | Create a dependency (source blocks target) |
+| `list_cycles` | Cycles with progress |
+| `list_members` | Workspace members (resolve assignees) |
+
+Every tool acts as the user who created the API key, scoped to that user's workspace.
+
+## Publishing
+
+The package is configured for public npm publishing (`publishConfig.access: public`,
+`prepublishOnly` builds `dist`). To release:
+
+```bash
+cd packages/mcp
+npm publish
+```

package/dist/index.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
+import { z } from "zod";
+// Rhythmic MCP server — exposes the /api/v1 surface to coding agents as typed tools.
+// Configure with `--api-key` / `--url` flags or the RHYTHMIC_API_KEY / RHYTHMIC_API_URL
+// env vars (flags win). Create a key in Rhythmic under Settings → API keys.
+//
+//   npx rhythmic-mcp --api-key rhy_xxx
+const VERSION = createRequire(import.meta.url)("../package.json")
+    .version;
+// Minimal flag parser: supports `--flag value` and `--flag=value` (and -k for the key).
+function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const eq = arg.indexOf("=");
+        const [flag, inlineVal] = eq === -1 ? [arg, undefined] : [arg.slice(0, eq), arg.slice(eq + 1)];
+        const take = () => inlineVal ?? argv[++i];
+        if (flag === "--api-key" || flag === "-k")
+            out.apiKey = take();
+        else if (flag === "--url" || flag === "--api-url")
+            out.url = take();
+    }
+    return out;
+}
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(`rhythmic-mcp v${VERSION} — MCP server for Rhythmic\n\n` +
+        `Usage: rhythmic-mcp [--api-key <key>] [--url <baseUrl>]\n\n` +
+        `Options:\n` +
+        `  -k, --api-key <key>   Rhythmic API key (or set RHYTHMIC_API_KEY)\n` +
+        `      --url <baseUrl>   Rhythmic base URL (or set RHYTHMIC_API_URL;\n` +
+        `                        default https://rhythmicapp.dev)\n` +
+        `  -h, --help            Show this help\n` +
+        `  -v, --version         Show version`);
+    process.exit(0);
+}
+if (argv.includes("--version") || argv.includes("-v")) {
+    console.log(VERSION);
+    process.exit(0);
+}
+const flags = parseArgs(argv);
+const BASE = (flags.url ?? process.env.RHYTHMIC_API_URL ?? "https://rhythmicapp.dev").replace(/\/$/, "");
+const KEY = flags.apiKey ?? process.env.RHYTHMIC_API_KEY ?? "";
+async function api(path, init = {}) {
+    const res = await fetch(`${BASE}/api/v1${path}`, {
+        method: init.method ?? "GET",
+        headers: { "x-api-key": KEY, "content-type": "application/json" },
+        body: init.body ? JSON.stringify(init.body) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}: ${text || res.statusText}`);
+    return text ? JSON.parse(text) : null;
+}
+function qs(args) {
+    const p = new URLSearchParams();
+    for (const [k, v] of Object.entries(args)) {
+        if (v !== undefined && v !== null && v !== "")
+            p.set(k, String(v));
+    }
+    const s = p.toString();
+    return s ? `?${s}` : "";
+}
+const ok = (data) => ({
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});
+const fail = (e) => ({
+    content: [{ type: "text", text: `Error: ${e.message}` }],
+    isError: true,
+});
+const server = new McpServer({ name: "rhythmic", version: VERSION });
+server.tool("list_projects", "List all projects in the workspace.", {}, async () => {
+    try {
+        return ok(await api("/projects"));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("get_project", "Get a project by key (e.g. AUTH) with its cycles.", { key: z.string().describe("Project key or id") }, async ({ key }) => {
+    try {
+        return ok(await api(`/projects/${encodeURIComponent(key)}`));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("list_issues", "List issues, optionally filtered by project/status/assignee/cycle. Paginated.", {
+    project: z.string().optional().describe("Project key or id"),
+    status: z
+        .enum(["backlog", "todo", "in_progress", "done", "canceled"])
+        .optional(),
+    assignee: z.string().optional().describe("Assignee user id"),
+    cycle: z.string().optional().describe("Cycle id"),
+    limit: z.number().int().min(1).max(200).optional(),
+    offset: z.number().int().min(0).optional(),
+}, async (args) => {
+    try {
+        return ok(await api(`/issues${qs(args)}`));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("get_issue", "Get full detail for an issue by key (e.g. AUTH-12): fields, comments, and dependency edges.", { key: z.string().describe("Issue key or id") }, async ({ key }) => {
+    try {
+        return ok(await api(`/issues/${encodeURIComponent(key)}`));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("create_issue", "Create a new issue in a project.", {
+    project: z.string().describe("Project key or id"),
+    title: z.string(),
+    description: z.string().optional(),
+    status: z
+        .enum(["backlog", "todo", "in_progress", "done", "canceled"])
+        .optional(),
+    priority: z.enum(["none", "low", "medium", "high", "urgent"]).optional(),
+    assigneeId: z.string().optional(),
+    cycleId: z.string().optional(),
+}, async (args) => {
+    try {
+        return ok(await api("/issues", { method: "POST", body: args }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("update_issue", "Update fields on an issue (status, priority, title, description, assignee, cycle).", {
+    key: z.string().describe("Issue key or id"),
+    status: z
+        .enum(["backlog", "todo", "in_progress", "done", "canceled"])
+        .optional(),
+    priority: z.enum(["none", "low", "medium", "high", "urgent"]).optional(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    assigneeId: z.string().nullable().optional(),
+    cycleId: z.string().nullable().optional(),
+}, async ({ key, ...patch }) => {
+    try {
+        return ok(await api(`/issues/${encodeURIComponent(key)}`, {
+            method: "PATCH",
+            body: patch,
+        }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("comment_issue", "Add a comment to an issue (authored by the API key's user).", { key: z.string().describe("Issue key or id"), body: z.string() }, async ({ key, body }) => {
+    try {
+        return ok(await api(`/issues/${encodeURIComponent(key)}/comments`, {
+            method: "POST",
+            body: { body },
+        }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("set_work_status", "Show or hide the live 'agent is working' spinner on an issue. Call with working:true right " +
+    "before you start working on an issue, and working:false when you finish — your teammates " +
+    "watch it move in real time. It auto-clears if left on, and any edit/comment you make keeps " +
+    "it alive.", {
+    key: z.string().describe("Issue key or id"),
+    working: z.boolean().describe("true = start working, false = done"),
+}, async ({ key, working }) => {
+    try {
+        return ok(await api(`/issues/${encodeURIComponent(key)}/work`, {
+            method: "POST",
+            body: { running: working },
+        }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("link_issues", "Create a dependency: source blocks target (issues referenced by key).", {
+    source: z.string().describe("Blocking issue key"),
+    target: z.string().describe("Blocked issue key"),
+    type: z.enum(["blocks", "relates"]).optional(),
+}, async (args) => {
+    try {
+        return ok(await api("/dependencies", { method: "POST", body: args }));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("list_cycles", "List cycles (sprints) with progress, optionally for one project.", { project: z.string().optional().describe("Project key or id") }, async (args) => {
+    try {
+        return ok(await api(`/cycles${qs(args)}`));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+server.tool("list_members", "List workspace members (for resolving assignees).", {}, async () => {
+    try {
+        return ok(await api("/members"));
+    }
+    catch (e) {
+        return fail(e);
+    }
+});
+async function main() {
+    if (!KEY) {
+        console.error("No API key set — pass --api-key <key> or set RHYTHMIC_API_KEY. Tool calls will fail with 401.");
+    }
+    await server.connect(new StdioServerTransport());
+    console.error(`Rhythmic MCP server ready (API: ${BASE})`);
+}
+main().catch((e) => {
+    console.error("Fatal:", e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "rhythmic-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Rhythmic — exposes your spatial project board to coding agents (Claude Code, Cursor, Claude Desktop) as typed tools.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "rhythmic-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "rhythmic",
+    "claude",
+    "cursor",
+    "agents",
+    "project-management"
+  ],
+  "homepage": "https://github.com/stevegrehan/rhythmic/tree/main/packages/mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevegrehan/rhythmic.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/stevegrehan/rhythmic/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  }
+}