@composer-app/mcp 0.0.1-beta.5 → 0.0.2

package/dist/cli.js

@@ -4,7 +4,7 @@ import {
   logError,
   startMcpHttpServer,
   startMcpServer
-} from "./chunk-A5KBJAJW.js";
+} from "./chunk-GPFWLOYB.js";
 
 // src/setup.ts
 import * as fs from "fs/promises";

package/dist/mcp.js

@@ -2,14 +2,34 @@ import {
   __test_clearRooms,
   __test_dispatch,
   __test_setRoom,
+  _clearRoomsForTest,
+  _registerRoomForTest,
+  dispatchTool,
+  performAddComment,
+  performAddSuggestion,
+  performAgentStatus,
+  performDone,
+  performReplyComment,
+  performReplySuggestion,
+  performResolveThread,
   startMcpHttpServer,
   startMcpServer,
   teardownAllRooms
-} from "./chunk-A5KBJAJW.js";
+} from "./chunk-GPFWLOYB.js";
 export {
   __test_clearRooms,
   __test_dispatch,
   __test_setRoom,
+  _clearRoomsForTest,
+  _registerRoomForTest,
+  dispatchTool,
+  performAddComment,
+  performAddSuggestion,
+  performAgentStatus,
+  performDone,
+  performReplyComment,
+  performReplySuggestion,
+  performResolveThread,
   startMcpHttpServer,
   startMcpServer,
   teardownAllRooms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composer-app/mcp",
-  "version": "0.0.1-beta.5",
+  "version": "0.0.2",
   "description": "Composer MCP",
   "license": "MIT",
   "author": "Josh Philpott",
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "skill"
+    "skill",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "mcp",

package/skill/commenting/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: commenting
+description: Use when you're about to call `composer_reply_comment`, `composer_reply_suggestion`, or `composer_add_comment` — replying or commenting in a Composer thread. Covers terseness rules, when a suggestion replaces a reply, and the reply-vs-new-comment-vs-suggestion decision.
+---
+
+# Composer comments and replies
+
+Comment threads in Composer render in a narrow sidebar — think Figma's
+comment box, not a chat window. Long replies get unwieldy fast. The
+rules below keep threads readable.
+
+This skill is the full guide for any text reply or new comment. Load it
+when you're about to call a `composer_reply_*` or `composer_add_comment`
+tool.
+
+## Terseness
+
+- **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.
+- Never dump your reasoning or tool-call chatter into a comment.
+- 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. The sidebar is the
+  wrong shape for that content.
+
+Terse beats thorough. If the user wants more, they'll ask.
+
+## Don't double-post: a suggestion IS your reply
+
+If you post a suggestion in response to the thread, **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. The user
+gets a visible card; the agent's reasoning is in the suggestion's
+shape, not in a separate sentence.
+
+The only time to post both is when the reply says something the
+suggestion can't convey on its own — context, a follow-up question, an
+explicit flag that there are companion edits elsewhere. That's rare;
+default to suggestion-only.
+
+## Reply vs new comment vs suggestion — quick decision
+
+When the user's message in a thread asks for something, pick the shape
+of your response from this:
+
+| Shape | Use when |
+|---|---|
+| **Suggestion only** | The user asked for a text change ("rewrite this", "make it 200g", "tighten the wording"). The change IS the response. |
+| **Suggestion + new comment elsewhere** | The text change ripples to a different span. Suggest each span separately, then leave a comment on the originating thread saying *"also touched X"* — only if the ripples aren't otherwise obvious. |
+| **Reply only** | The user asked a question that has a textual answer ("when did we ship that?", "is Jesse still on this?"). No text change involved. Keep it short. |
+| **Suggestion + reply on origin thread** | You changed text AND need to say something the change can't convey alone (caveat, a follow-up question, "I changed two other places too"). |
+| **New comment elsewhere** | You're raising something the user didn't ask about but should see — a cross-reference, an inconsistency, a heads-up. Anchor it where it actually belongs, not on the thread you were called from. |
+
+For suggestion craft (anchoring, ripples, multi-span), load
+**`composer:suggesting`**.
+
+## Empty acknowledgements: don't
+
+Never post a reply that's just "👍", "got it", or "thanks". If the
+user's message doesn't actually need a response (a thank-you back to
+you, a stage direction, a note-to-self), stay silent. Posting an empty
+ack adds noise to the sidebar.

package/skill/create/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: create
+description: Use when the user wants to start a NEW Composer doc — pasting markdown to "send to Composer", asking to create/seed a Composer room from a file or inline content, or accepting your offer to put a draft into Composer. Covers first-run agent-name prompt, seed selection (file path vs inline), the ordered `step1_sayToUser` / `step2_callTool` return, and the monitor-subagent handoff.
+---
+
+# Composer — Create a doc
+
+Composer is a real-time collaborative markdown editor. `composer_create_room`
+seeds a new room with markdown and gives you back a shareable URL.
+
+## When to load this skill
+
+- The user asks to "send this to Composer", "make a Composer doc with
+  this", "create a Composer room with the plan".
+- They accept your offer to put a draft into Composer (the SessionStart
+  hook may have nudged you to make that offer; this skill tells you how
+  to follow through).
+
+If they pasted an existing `usecomposer.app/r/<id>` URL, they want to
+**join**, not create — load `composer:join` instead.
+
+## Steps
+
+### 1. First-run only — agree on a name
+
+If the MCP returns an "ask the user what to call you" error, no `actingAs`
+name is saved on this machine yet. Stop and ask. Suggest one default:
+
+- If you know the user's first name → `"<FirstName>'s Agent"` (e.g.
+  `"Josh's Agent"`).
+- Otherwise something playful that isn't a model family — `Monty`,
+  `Gerty`, `Rosie`, `Otto`, `Pip`. **Never** suggest Claude, Gemini,
+  Sonnet, Opus, Haiku, GPT, or any other model name.
+
+Phrase: *"I'll go by Monty in Composer docs — sound good, or pick your
+own?"* Retry the call with their answer as `actingAs`. The name persists
+to `~/.composer/user.json` and is reused forever.
+
+### 2. Pick the seed source
+
+Pick exactly one:
+
+- **`seedMarkdownPath: "<absolute path>"`** — preferred whenever the
+  markdown already lives in a file on disk (a plan, a journal entry, any
+  `.md` the user pointed at). The MCP reads the file itself, so you don't
+  stream the content through the model. Faster, cheaper.
+- **`seedMarkdown: "<inline string>"`** — only when the content was
+  generated this turn and isn't on disk yet.
+
+The seed is read **once**. Composer never writes back to the source
+file. If the user later wants the room contents back on disk, that's the
+`/composer:export` slash command — explicit, one-way overwrite.
+
+### 3. Call `composer_create_room`
+
+```
+composer_create_room({
+  seedMarkdownPath: "<absolute path>"   // OR seedMarkdown: "<inline>"
+})
+```
+
+### 4. Honor the ordered return
+
+Success returns two ordered steps. The field names encode the order:
+
+1. **`step1_sayToUser`** — output this **first**. It always starts with
+   the `browserUrl` so the user has a way into the doc, and carries the
+   `@<your-name>` tagging hint they'll need to mention you. Light
+   paraphrasing is fine; **do not drop the URL or the mention syntax**.
+2. **`step2_callTool`** — a structured `{ tool, args, why }` directive
+   pointing at `composer_next_event`. **Do not run it inline.** Spawn
+   the monitor subagent (next step), then end your turn.
+
+Skipping `step1_sayToUser` strands the user with no link. Skipping the
+subagent spawn leaves the room attached but silent — saying "I'm
+monitoring" without spawning the loop is a lie; every mention gets missed.
+
+### 5. Spawn the monitor subagent
+
+Use the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Composer monitor: <roomId>"`
+- `prompt`: tell the subagent to **invoke the `composer:monitor`
+  skill**, then run the loop on `{roomId}` as `{actingAs}`. Don't paste
+  the loop rules inline — the `composer:monitor` skill carries them
+  (spawn template, mention filtering, exit rules, event payload).
+
+Once spawned, **end your turn immediately**. Do not output any text
+after the spawn — no closing recap, no "monitor is running" status
+line, no restating the mention syntax. The host already shows a
+status indicator for the backgrounded `Agent` tool call; that's the
+user's confirmation. Anything you say after `step1_sayToUser` just
+duplicates it. The protocol is strict:
+
+1. Output `step1_sayToUser` (verbatim or lightly paraphrased).
+2. Spawn the `Agent`.
+3. End turn. No closing remark.
+
+Also: do **not** poll `composer_next_event` from the main thread —
+two listeners on the same room means duplicated replies.
+
+### When the monitor exits
+
+You'll get a notification when the background subagent finishes. Its
+final output line is the agent's goodbye — written in the agent's
+voice (idle timeout, server kick, reconnect aborted, etc., per the
+`composer:monitor` exit rules). **Relay that line verbatim to the user
+in the main thread** so they see why the agent left and how to bring
+it back. Don't paraphrase or wrap it in extra explanation; the
+goodbye line already carries the next step (`/composer:join` etc.).
+
+## Terminal-side asks after creation
+
+The main thread is also attached to the room. If the user later asks
+something in the terminal like *"add a summary to section 2"*, call the
+write tools from here and report back concisely. Don't hand terminal
+directives to the monitor subagent — the subagent handles in-doc
+mentions, the main thread handles in-terminal asks. They share the same
+MCP, so writes from either show up in the doc.
+
+For comment etiquette, load **`composer:commenting`**. For suggestion
+craft, load **`composer:suggesting`**.
+
+## Failure handling
+
+- **Setup not done** → `npx @composer-app/mcp@latest setup`, restart the CLI.
+- **Server kicked you (4403/4410) or reconnect aborted** → the agent
+  left the room. Run `/composer:join <url>` to bring it back. The kick
+  reason is in the error message.

package/skill/export/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: export
+description: Use when the user wants to dump a Composer doc's current contents to a local markdown file — running `/composer:export <path>`, asking to "save this Composer doc to disk", or to "export the room as markdown". This is ONE-WAY — Composer is the source of truth and the local file is overwritten on every export. There is no merge, no diff, no two-way sync.
+---
+
+# Composer — Export to a local file
+
+`composer_export_to_file` writes the current room contents to a local
+markdown file. **There is no merge, no diff, no two-way sync** —
+Composer is authoritative; whatever's at the path becomes a fresh
+snapshot on every export. **If a file already exists at the path, the
+export will overwrite it.** Always confirm with the user first when
+that's the case — see step 3 below.
+
+## Steps
+
+### 1. Resolve the room
+
+- If exactly one Composer room is attached this session, use it.
+- If multiple are attached, ask: *"Which doc — paste the URL or
+  roomId."* Stop. Do not guess.
+- If none are attached, ask the user to `/composer:join <url>` first,
+  then re-run.
+
+### 2. Resolve the path
+
+- The argument **must be an absolute path**. If it's relative, ask the
+  user for an absolute one (or resolve it against the current working
+  directory if unambiguous — but confirm before doing so).
+- The parent directory must already exist. The MCP will not create
+  directories.
+
+### 3. Check for an existing file and ask permission before overwriting
+
+Before calling the export tool, check whether anything is at the
+target path (use whatever read-only tool your host gives you — `ls`,
+`stat`, `Read`, etc.):
+
+- **File does not exist** — proceed straight to step 4. No confirmation
+  needed; nothing is at risk.
+- **File exists** — STOP and ask the user explicitly. Show them the
+  path and the consequence in one short line, e.g.:
+
+  > *`{path}` already exists. Exporting will overwrite it. Want me to
+  > go ahead?*
+
+  Wait for an affirmative answer (yes / sure / go ahead / 👍) before
+  calling the tool. If they say no or pick a different path, follow
+  their lead — do NOT call the tool with the original path.
+
+Do not silently overwrite. The user typing `/composer:export <path>`
+opts them into the export, not into clobbering arbitrary local files
+without warning.
+
+### 4. Call `composer_export_to_file`
+
+```
+composer_export_to_file({ roomId, path: "<absolute>" })
+```
+
+Returns `{ roomId, path, bytesWritten }`.
+
+### 5. Confirm in one short line
+
+> *"Exported to `{path}` ({bytes} bytes)."*
+
+End your turn. No follow-up call needed.

package/skill/join/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: join
+description: Use when the user wants to JOIN an existing Composer doc — pasting a `usecomposer.app/r/<id>` URL, running `/composer:join`, or otherwise asking you to attach to a room they already have. Covers first-run agent-name prompt, the `composer_join_room` call, the ordered `step1_sayToUser` / `step2_callTool` return, and the monitor-subagent handoff.
+---
+
+# Composer — Join a doc
+
+Composer is a real-time collaborative markdown editor. `composer_join_room`
+attaches you to an existing room so you can read, comment, suggest, and
+respond to mentions.
+
+## When to load this skill
+
+- The user pastes a `usecomposer.app/r/<id>` URL.
+- They run `/composer:join <url>` (the slash command delegates here).
+- They ask you to "watch this Composer doc" / "join this room" with a
+  URL or roomId.
+
+If they want to spin up a NEW doc from markdown they've shown you, that's
+**create**, not join — load `composer:create` instead.
+
+## Steps
+
+### 1. First-run only — agree on a name
+
+If the MCP returns an "ask the user what to call you" error, no
+`actingAs` name is saved on this machine yet. Stop and ask. Suggest one
+default:
+
+- If you know the user's first name → `"<FirstName>'s Agent"` (e.g.
+  `"Josh's Agent"`).
+- Otherwise something playful that isn't a model family — `Monty`,
+  `Gerty`, `Rosie`, `Otto`, `Pip`. **Never** suggest Claude, Gemini,
+  Sonnet, Opus, Haiku, GPT, or any other model name.
+
+Phrase: *"I'll go by Monty in Composer docs — sound good, or pick your
+own?"* Retry with their answer as `actingAs`. The name persists to
+`~/.composer/user.json` and is reused forever.
+
+### 2. Resolve the URL
+
+- If the user pasted a `https://usecomposer.app/r/<id>` URL, use it.
+- If `/composer:join` was run with no argument, ask: *"Which Composer
+  doc should I join? Paste the URL."* Stop. Do not guess.
+- A bare roomId (no `https://` prefix) is also acceptable.
+
+### 3. Call `composer_join_room`
+
+```
+composer_join_room({ url: "<the URL or roomId>" })
+```
+
+### 4. Honor the ordered return
+
+Success returns two ordered steps:
+
+1. **`step1_sayToUser`** — output this **first**. It confirms the URL
+   the user just joined and carries the `@<your-name>` tagging hint.
+   Light paraphrasing OK; don't drop the URL or the mention syntax.
+2. **`step2_callTool`** — a structured `{ tool, args, why }` directive
+   pointing at `composer_next_event`. **Do not run it inline.** Spawn
+   the monitor subagent (next step), then end your turn.
+
+### 5. Spawn the monitor subagent
+
+Use the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Composer monitor: <roomId>"`
+- `prompt`: tell the subagent to **invoke the `composer:monitor`
+  skill**, then run the loop on `{roomId}` as `{actingAs}`. Don't paste
+  the loop rules inline — the `composer:monitor` skill carries them
+  (spawn template, mention filtering, exit rules, event payload).
+
+Once spawned, **end your turn immediately**. Do not output any text
+after the spawn — no closing recap, no "monitor is running" status
+line, no restating the mention syntax. The host already shows a
+status indicator for the backgrounded `Agent` tool call; that's the
+user's confirmation. Anything you say after `step1_sayToUser` just
+duplicates it. The protocol is strict:
+
+1. Output `step1_sayToUser` (verbatim or lightly paraphrased).
+2. Spawn the `Agent`.
+3. End turn. No closing remark.
+
+Also: do **not** poll `composer_next_event` from the main thread —
+two listeners on the same room means duplicated replies.
+
+### When the monitor exits
+
+You'll get a notification when the background subagent finishes. Its
+final output line is the agent's goodbye — written in the agent's
+voice (idle timeout, server kick, reconnect aborted, etc., per the
+`composer:monitor` exit rules). **Relay that line verbatim to the user
+in the main thread** so they see why the agent left and how to bring
+it back. Don't paraphrase or wrap it in extra explanation; the
+goodbye line already carries the next step (`/composer:join` etc.).
+
+## Terminal-side asks after joining
+
+The main thread is also attached to the room. If the user asks something
+in the terminal like *"reply to that thread saying we'll ship Friday"*,
+call the write tools from here and report back concisely. Don't hand
+terminal directives to the monitor subagent — the subagent handles
+in-doc mentions, the main thread handles in-terminal asks. They share
+the same MCP, so writes from either show up in the doc.
+
+For comment etiquette, load **`composer:commenting`**. For suggestion
+craft, load **`composer:suggesting`**.
+
+## Failure handling
+
+- **Setup not done** → `npx @composer-app/mcp@latest setup`, restart the CLI.
+- **Server kicked you (4403/4410) or reconnect aborted** → the agent
+  left the room. Run `/composer:join <url>` to bring it back. The kick
+  reason is in the error message.

package/skill/monitor/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: monitor
+description: Use when you're running the Composer monitor loop — spawned as a subagent off `composer_create_room` / `composer_join_room`, or otherwise about to call `composer_next_event`. Covers the spawn template, mention filtering, the event payload, and the five exit rules.
+---
+
+# Composer monitor loop
+
+Composer's monitor loop is **always-on**: every return from
+`composer_next_event` carries a directive (a mention to handle, a
+timeout to noop on, or a goodbye to honor). You execute the directive
+and immediately call the tool again. The doc IS your conversation —
+do not narrate to the parent between ticks.
+
+This skill is for the agent **inside** the loop. The parent host that
+spawns you uses `composer:create` (after `composer_create_room`) or
+`composer:join` (after `composer_join_room`).
+
+## How the parent spawns you
+
+The parent skill tells the host to spawn an `Agent` with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Composer monitor: <roomId>"`
+- prompt: a short brief that includes the room's `{roomId}`, the
+  agent's `{actingAs}`, and the five exit rules below.
+
+## Exit rules
+
+When you exit, your **final output line is the user-visible goodbye** —
+the parent surfaces it back to the main thread. Voice: first-person,
+casual, the same agent saying goodbye. Not a system notification, not
+a stack trace. **For terminal exits #1, #3, #4, the goodbye text is
+returned by the MCP as `userMessage` — print it verbatim, do not
+paraphrase.** Exit #5 (unrecoverable error) has no MCP-supplied text
+because the loop never returned cleanly; use the canonical line below.
+
+> Exit and return when ANY of these happen:
+>
+> **1. Idle timeout.** `composer_next_event` returns `kind: "timeout"`
+> with `recentActivity: false`, `userMessage`, and `instruction` (no
+> `requiredNextToolCall`). The doc has been silent for the configured
+> quiet window. Do **not** post anything in the doc — awareness has
+> already cleared. Print `userMessage` verbatim to the terminal, then
+> exit.
+>
+> **2. Doc-side handoff.** A request inside the doc clearly needs the
+> parent terminal (a code change, a shell command, an external action
+> the parent would do). Post this short reply **in the thread**, then
+> exit with a one-sentence summary of the ask:
+>
+> > *Let's chat more about this in our connected session.*
+>
+> **3. Server kicked the client.** Close code `4403` (old MCP), `4410`
+> (kill switch), or HTTP 403 on upgrade. `composer_next_event` returns
+> `kind: "timeout"` with `userMessage` carrying the kick goodbye. Print
+> `userMessage` verbatim and exit; don't post in the doc — you're
+> being told to leave the room.
+>
+> **4. Reconnect aborted.** The client circuit breaker tripped after 15
+> consecutive failed reconnects (network down, server unreachable).
+> Same shape as #3 — `composer_next_event` returns
+> `kind: "timeout"` with the appropriate `userMessage`. Print verbatim
+> and exit.
+>
+> **5. Unrecoverable mid-loop error.** Auth lost, room destroyed, or
+> any other thrown error not covered above. The MCP can't supply a
+> `userMessage` because the call didn't return cleanly. Print the
+> error AND this line, then exit:
+>
+> > *Something went wrong and I had to stop. Try running
+> > `/composer:join` in a bit to bring me back.*
+
+Default `composer_next_event` timeout is 30s. Don't shorten it
+arbitrarily.
+
+## Inside the loop
+
+Every return carries a structured directive. Follow it without waiting
+for user input.
+
+### `kind: "mention"`
+
+Handle the event (reply / suggestion / resolve as needed), then execute
+`requiredNextToolCall` — which is another `composer_next_event` call.
+Do not pause to acknowledge.
+
+### `kind: "timeout"` with `recentActivity: true`
+
+The user was working in the doc recently — they just didn't tag you.
+The return includes `requiredNextToolCall`. Execute it. Stay in the
+loop.
+
+### `kind: "timeout"` without `requiredNextToolCall`
+
+The return has `userMessage` and `instruction`. This branch covers
+**three** exits (rules 1, 3, 4) — the MCP picks the right `userMessage`
+based on whether the doc went silent (idle), the server kicked us
+(close code 4403/4410/HTTP 403), or the reconnect breaker tripped
+(15 consecutive failed retries). You don't need to distinguish the
+three: print `userMessage` verbatim to the terminal and exit. Do not
+post in the doc.
+
+## The mention event payload
+
+```
+{
+  kind: "mention",
+  threadId: "...",
+  threadKind: "comment" | "suggestion",
+  threadText: "...",           // the exact message that triggered you
+  replyId?: "...",             // present when this is a reply on an existing thread
+  reason: "direct_mention" | "active_thread" | "solo_room",
+  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` is needed in the common case. Reach for
+`sectionMarkdown` to understand surrounding context before replying.
+
+**The event only carries the triggering message.** If the thread already
+has replies, call `composer_get_thread({ roomId, threadId })` before
+replying. The return has every reply with author and timestamp —
+essential when the user tagged you mid-conversation.
+
+## `reason` is your main filter
+
+- **`"direct_mention"`** — sidecar or text explicitly tagged you. Always
+  reply (unless the content is purely a thank-you that doesn't need an
+  answer — never emit empty acknowledgements).
+- **`"active_thread"`** — a plain reply on a thread you're already in.
+  Reply if the content invites one; skip if it's plainly addressed to
+  another person, is a thank-you, or is otherwise a conversational
+  dead-end.
+- **`"solo_room"`** — you're alone with one human who didn't tag anyone.
+  **Default to a helpful reply** — they almost certainly want your
+  input. Skip only when the text reads like:
+    - a **note-to-self** ("TODO: fix this later", "remember to check the
+      date"),
+    - a bare **acknowledgement** ("k", "got it", "done"),
+    - a stage direction / aside ("ugh", "hmm"),
+    - or anything that visibly isn't pointed at you (quoted text, drafts
+      they're jotting down).
+  When in doubt, reply — the user can always ignore you.
+
+## Where to go for richer rules
+
+- About to **reply on a thread** with text? Load **`composer:commenting`**
+  — terseness rules and the suggestion-replaces-reply pattern.
+- About to **post a suggestion**? Load **`composer:suggesting`** — span
+  scoping, ripple coverage, anchor mechanics.
+
+Don't try to reproduce those skills' rules from memory; load them when
+the situation matches.