@composer-app/mcp 0.0.1-beta.0

package/dist/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import {
+  loadOrCreateIdentity,
+  logError,
+  startMcpServer
+} from "./chunk-UPWB2QWR.js";
+
+// src/cli.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import fs from "fs/promises";
+import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
+var exec = promisify(execFile);
+async function main() {
+  const cmd = process.argv[2];
+  if (cmd === "mcp") return startMcpServer();
+  if (cmd === "setup") return setup();
+  console.log(`composer-mcp
+  setup   Register the MCP server with your agent
+  mcp     Run as an MCP server (invoked by the host CLI)`);
+}
+async function setup() {
+  const dir = path.join(os.homedir(), ".composer-mcp");
+  await loadOrCreateIdentity(dir);
+  const serverHost = process.env.COMPOSER_SERVER_HOST ?? "usecomposer.app";
+  const appBase = process.env.COMPOSER_APP_BASE ?? "https://usecomposer.app";
+  try {
+    await exec("claude", [
+      "mcp",
+      "add",
+      "--scope",
+      "user",
+      "composer-mcp",
+      "-e",
+      `COMPOSER_SERVER_HOST=${serverHost}`,
+      "-e",
+      `COMPOSER_APP_BASE=${appBase}`,
+      "--",
+      "npx",
+      "-y",
+      "@composer-app/mcp@latest",
+      "mcp"
+    ]);
+    console.log("\u2713 Registered composer-mcp with agent");
+  } catch (e) {
+    console.error(
+      "\u2717 Could not register with agent:",
+      e.message
+    );
+    process.exit(1);
+  }
+  const skillDir = path.join(os.homedir(), ".claude", "skills", "composer");
+  await fs.mkdir(skillDir, { recursive: true });
+  const pkgRoot = fileURLToPath(new URL("..", import.meta.url));
+  const skillSource = path.join(pkgRoot, "skill", "SKILL.md");
+  const skillContent = await fs.readFile(skillSource, "utf8");
+  await fs.writeFile(path.join(skillDir, "SKILL.md"), skillContent);
+  console.log(`\u2713 Wrote skill to ${skillDir}/SKILL.md`);
+  console.log(
+    "\nRestart your agent, then paste a share prompt from any Composer doc."
+  );
+}
+main().catch((e) => {
+  logError("cli main() rejected", e);
+  console.error(e);
+  process.exit(1);
+});

package/dist/mcp.js

@@ -0,0 +1,6 @@
+import {
+  startMcpServer
+} from "./chunk-UPWB2QWR.js";
+export {
+  startMcpServer
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@composer-app/mcp",
+  "version": "0.0.1-beta.0",
+  "description": "Composer MCP",
+  "license": "MIT",
+  "author": "Josh Philpott",
+  "type": "module",
+  "bin": {
+    "composer-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skill"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "composer",
+    "collaborative",
+    "markdown",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts src/mcp.ts --format esm --target node20 --out-dir dist --clean",
+    "dev": "tsup src/cli.ts src/mcp.ts --format esm --target node20 --out-dir dist --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "marked": "^14.1.0",
+    "nanoid": "^5.1.7",
+    "partysocket": "^1.1.16",
+    "ws": "^8.20.0",
+    "y-partyserver": "^2.1.4",
+    "yjs": "^13.6.30"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.3.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.3"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: composer
+description: Use when the user pastes a Composer share prompt, asks to "send this to Composer", wants to join a Composer doc, or says /composer. Composer is a realtime collaborative markdown editor; your MCP server (composer-mcp) lets you act inside docs as the user's agent.
+---
+
+# Composer
+
+You have access to a `composer-mcp` MCP server. Use it when the user asks
+to create, join, monitor, or act in a Composer doc.
+
+## Four modes
+
+### 1. Create
+Triggers: "send this markdown to Composer", "make a Composer doc with this".
+Action: call `composer_create_room({ name, seedMarkdown, actingAs: "<user's name>'s Agent" })`.
+Return the `browserUrl`. You are already attached; enter monitor mode.
+
+### 2. Join
+Triggers: a share prompt with a Composer URL, "/composer join <url>".
+Action: extract the URL and the acting-as name from the prompt. Call
+`composer_join_room({ url, actingAs })`. Announce the doc outline and enter
+monitor mode.
+
+### 3. Monitor
+Triggers: "watch this doc", or automatically after join/create.
+Action: call `composer_next_event({ roomId, timeoutSec: 300 })` in a loop.
+On `timeout`: loop again up to ~30 minutes, then ask the user if they want
+to keep watching.
+
+On `mention`, the event contains everything you need to act in one turn:
+
+```
+{
+  kind: "mention",
+  threadId: "...",
+  threadKind: "comment" | "suggestion",
+  threadText: "...",           // the exact message that triggered you
+  replyId?: "...",             // present when it's a reply on an existing thread
+  reason: "direct_mention" | "active_thread",
+  anchoredText?: "...",        // the doc text the thread is anchored to
+  headingId?: "...",           // the section's headingId (use with write tools)
+  headingText?: "...",
+  sectionMarkdown?: "..."      // full containing section as markdown
+}
+```
+
+Use `headingId` + `anchoredText` directly when calling `composer_add_suggestion`
+or `composer_add_comment` — no extra `composer_get_section` call is needed in
+the common case. Reach for `sectionMarkdown` to understand surrounding context
+before replying or suggesting.
+
+**Important:** `reason: "active_thread"` means the user replied on a thread
+the agent has already participated in — no explicit `@agent` was required.
+Decide whether to respond based on content, not just the trigger; if the
+reply is plainly addressed to another person, or is a thank-you that doesn't
+need an answer, it's fine to leave it alone (don't emit an empty reply just
+to acknowledge). If it clearly asks you something, answer it.
+
+### 4. Act
+Triggers: direct requests like "add a summary to section 2".
+Action: already attached; call the write tools and report back concisely.
+
+## Write tools
+
+- `composer_add_comment` — comment anchored to text.
+- `composer_add_suggestion` — propose a text replacement (lands as pending).
+- `composer_reply_comment` / `composer_reply_suggestion` — reply on a thread.
+- `composer_resolve_thread` — mark resolved.
+
+There is no "just edit" tool in v1. All text changes go through suggestions
+that a human accepts manually.
+
+### Keep comment text terse
+
+Comment threads render in a narrow sidebar (think Figma's comment box), not
+a chat window. Long replies get unwieldy fast. Rules:
+
+- Answer in 1–3 sentences. Prefer one.
+- Reply directly to the question asked — no preamble ("Great question!"),
+  no restating the ask, no trailing summary of what you just did.
+- **If you post a suggestion in response to the thread, the suggestion IS
+  your reply. Do not also post a comment reply.** The suggestion renders
+  as a Replace/With card in the sidebar already; a pointer comment ("see
+  the suggestion") just duplicates what the user can already see.
+  Silent suggestion-only responses are correct and expected.
+- If the answer genuinely needs structure (a list of 4+ items, code, a
+  table) and a suggestion isn't the right shape, post it as a suggestion
+  in the doc body instead of as a comment reply.
+- Never dump your reasoning or tool-call chatter into a comment.
+
+Terse beats thorough. If the user wants more, they'll ask.
+
+### Do not oversuggest — match the span to the request
+
+Before calling `composer_add_suggestion`, read the user's message and
+decide what span they're actually asking you to change:
+
+1. **Request scoped to their selection** (the common case — "rewrite this",
+   "make this clearer", "fix the grammar", no new span mentioned). Pass
+   `fromThreadId: <threadId>`. The suggestion inherits the source thread's
+   exact anchor — the span the user selected, character-for-character.
+
+   ```
+   composer_add_suggestion({
+     roomId, fromThreadId: event.threadId, replacementText: "…"
+   })
+   ```
+
+2. **Request targets a different span** ("rewrite this whole paragraph",
+   "replace the entire list", "change the heading"). Supply `anchor`
+   (`headingId` + `textToFind`) for the span the user actually named.
+   Do not pass `fromThreadId` in this case — you're no longer inheriting
+   the thread's span.
+
+3. **Proactive suggestion with no source thread**. Supply `anchor` and
+   keep `textToFind` tight — do not widen beyond what you're actually
+   replacing.
+
+Picking a broader `textToFind` than the user asked for (the whole sentence
+when they highlighted a phrase, the whole paragraph when they asked about
+one clause) is the main failure mode. When in doubt, default to path 1.
+
+## Anchors
+
+Write tools take:
+
+```
+{ headingId: "intro-0", textToFind: "the exact words to anchor on", occurrence?: 1 }
+```
+
+If you get `text_not_found`, the error message includes the current section
+text. Re-plan against the fresh text and retry. Never retry with stale
+content.
+
+## Discoverability
+
+On first Composer-related message in a session, tell the user:
+"You can say 'send this markdown to Composer' and I'll create a seeded doc
+with a link to open."
+
+## Failure handling
+
+- Setup not done → run `npx @composer-app/mcp@latest setup`, restart your CLI.
+- Anchor text not found → retry against the fresh section text returned in
+  the error.
+- Doc edited mid-turn → anchors re-resolve natively; just retry.