@composer-app/mcp 0.0.1-beta.2 → 0.0.1-beta.4

package/dist/mcp.js

@@ -1,7 +1,7 @@
 import {
   startMcpHttpServer,
   startMcpServer
-} from "./chunk-SZ67UYAY.js";
+} from "./chunk-UVXQZ2TN.js";
 export {
   startMcpHttpServer,
   startMcpServer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composer-app/mcp",
-  "version": "0.0.1-beta.2",
+  "version": "0.0.1-beta.4",
   "description": "Composer MCP",
   "license": "MIT",
   "author": "Josh Philpott",

package/skill/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__composer-mcp__composer_create_room",
+      "mcp__composer-mcp__composer_join_room"
+    ]
+  }
+}

package/skill/SKILL.md

@@ -12,20 +12,79 @@ to create, join, monitor, or act in a Composer doc.
 
 ### 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.
+Action: call `composer_create_room({ ... })`.
+
+**First run only — ask the user what to call you.** If you have no saved
+name on this machine, the MCP returns an error instructing you to stop
+and ask. Offer one suggested default they can accept with a tap:
+
+- If you know the user's first name, suggest `"<FirstName>'s Agent"`
+  (e.g. `"Josh's Agent"`).
+- Otherwise suggest something playful that isn't a model family — `Monty`,
+  `Gerty`, `Rosie`, `Otto`, `Pip`. Do **not** suggest Claude, Gemini,
+  Sonnet, Opus, Haiku, GPT, or any other model name.
+
+Phrase it like: *"I'll go by Monty in Composer docs — sound good, or pick
+your own?"* Retry the tool call with their answer as `actingAs`. It
+persists to `~/.composer/user.json` and is reused forever.
+
+**On success** (first run or any subsequent run), the return gives you
+two ordered steps — the field names encode the order:
+
+1. `step1_sayToUser` — output this FIRST. It always starts with the
+   `browserUrl` because the user needs the link to open the doc; it
+   also carries the `@<your-name>` tagging hint. Relay it; you can
+   paraphrase lightly but do not drop the URL or the mention syntax.
+2. `step2_callTool` — a structured `{ tool, args, why }` directive for
+   the follow-up `composer_next_event` call. Execute it AFTER step 1,
+   before ending your turn.
+
+Skipping step 1 leaves the user without the URL — they have no way into
+the doc. Skipping step 2 leaves the room attached but silent; saying
+"I'm monitoring" without making the call is a lie, the agent will miss
+every mention.
+
+**Seeding — prefer a file path when one exists.** 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
+  whole document through the model. This is faster and avoids burning
+  tokens re-emitting content that already exists.
+- `seedMarkdown: "<inline string>"` — only when the content was generated
+  in this turn and isn't on disk yet.
+
+The seed file is read **once** at creation. Composer never writes back to
+it — edits made in the room stay in the room. Do not modify the source
+file while the user is working in Composer unless they explicitly ask you
+to sync changes back.
 
 ### 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.
+Action: extract the URL from the prompt and call `composer_join_room({ url })`.
+Same first-run rule as Create. On success, the return carries the same
+ordered pair: output `step1_sayToUser` first (confirms the URL the user
+just joined), then execute `step2_callTool`.
 
 ### 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.
+Action: call `composer_next_event({ roomId })` in a loop (default timeout
+is 10 minutes). **The loop is always-on.** Every return carries a
+structured directive — follow it without waiting for user input.
+
+On `mention`: handle the event (reply / suggestion / resolve as needed),
+output any user-facing text, then execute `requiredNextToolCall` — which
+is another `composer_next_event` call. Do not pause for the user to
+acknowledge. The doc is the conversation.
+
+On `timeout`: check `recentActivity`.
+- `recentActivity: true` → the return includes `requiredNextToolCall`.
+  Execute it — the user is still working, just not tagging you.
+- `recentActivity: false` → the return includes `userMessage` and
+  `instruction` but NO `requiredNextToolCall`. Say `userMessage`
+  EXACTLY ("I've left the document…") and stop calling
+  `composer_next_event` until the user asks you to rejoin. Do not
+  paraphrase — users recognize the line across sessions.
 
 On `mention`, the event contains everything you need to act in one turn:
 
@@ -49,22 +108,54 @@ 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.
+**The event only carries the triggering message.** If the thread already has
+replies (from the user, or from another agent), 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 and you
+need to catch up on what's already been said.
+
+**`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.
 
 ### 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.
+## Tools
+
+Read tools:
+- `composer_get_full_doc` — entire doc as markdown.
+- `composer_get_section` — one section by `headingId`.
+- `composer_get_thread` — full state of a thread (all replies, anchor,
+  containing section). Call this when `composer_next_event` surfaces a
+  mention on a thread that already has history — the event gives you
+  only the triggering message.
+
+Write tools:
+- `composer_add_comment` — NEW comment on any span in the doc. Use when
+  raising something outside the current thread's anchor.
+- `composer_add_suggestion` — propose a text replacement (lands as
+  pending). Can target any span — `fromThreadId` inherits the source
+  thread's anchor; `anchor` specifies a span elsewhere. Call it multiple
+  times in a turn to suggest in several spots.
+- `composer_reply_comment` / `composer_reply_suggestion` — reply on an
+  existing thread.
 - `composer_resolve_thread` — mark resolved.
 
 There is no "just edit" tool in v1. All text changes go through suggestions
@@ -120,6 +211,104 @@ 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.
 
+### Cross-span: reply and suggest anywhere in the doc
+
+A comment/reply thread is anchored to *one* span, but your response is
+not confined to that span. When the user's question (or your own
+judgment) points elsewhere:
+
+- **Suggest a change to different text.** Call `composer_add_suggestion`
+  with `anchor: { headingId, textToFind }` pointing at the target. You
+  can post multiple suggestions in one turn — e.g., the user says "the
+  flour amount is off and so is the bake time" → two suggestions, each
+  anchored to its own span.
+- **Open a new thread elsewhere.** Call `composer_add_comment` with
+  its own anchor. Useful for cross-references ("see also the
+  conclusion") or raising something the user didn't ask about but
+  should see.
+- **Still reply on the original thread too** if the user's question
+  deserves a direct answer — but only when the reply says something
+  the suggestion/new-comment doesn't already convey. Don't post
+  "see my suggestion"; the card IS the answer.
+
+Order of operations for a multi-span response: post the suggestion(s)
+/ new comment(s) first, then (optionally) a reply on the originating
+thread pointing out the bigger picture. That way the originating
+thread's reply can reference what you just did.
+
+### Suggest completely — accepting must leave the doc correct
+
+Goal: the user clicks Accept and is done. They should never have to
+hunt down downstream edits you forgot.
+
+**Load enough context before you suggest.** The event gives you
+`sectionMarkdown` for the containing section — usually enough for
+wording changes. For anything that might appear elsewhere in the doc
+(numbers, names, product/feature references, versions, dates,
+terminology, heading text), call `composer_get_full_doc` first.
+One extra read is much cheaper than shipping a broken doc.
+
+**Scan for ripples before posting.** Common ones:
+
+- **Counts and enumerations.** "The three examples below" / "three
+  things to remember" — if you add or remove an item, update the
+  count and any ordinal words ("first", "finally").
+- **Cross-references.** "As in section 2", "see the conclusion",
+  "per step 3 above". If your edit moves or renames the target,
+  update the reference too.
+- **Restated facts.** Recipes reference an ingredient twice; release
+  notes cite a version in both intro and body; specs quote a number
+  in a heading and a paragraph. One fact, multiple spans — cover
+  all of them.
+- **Subject/verb and pronoun agreement.** "X and Y are" → trim to
+  just X → "X is". Changing from plural to singular ripples.
+- **Neighboring flow.** Rewriting sentence 2 can break sentence 3
+  ("This is why..."). Fix the continuation.
+- **Heading changes.** If you change heading text, any prose that
+  says "see the Intro section" may need updating.
+
+**Post every ripple as its own suggestion, in the same turn.** Don't
+leave the user to hunt for companion edits. The tool accepts one
+anchor per call — call it multiple times. Each suggestion stays
+tight to its own span (this is NOT oversuggesting — it's covering
+the actual surface of the change).
+
+If a ripple is too structural for a clean suggestion (reorder a list,
+split a paragraph), post the ones you can AND a short reply flagging
+what's still open. The user shouldn't be surprised.
+
+**When in doubt about the scope of a ripple, fetch the full doc.**
+Don't guess.
+
+### Auto-suggest when the user confirms a concrete proposal
+
+When a user flags something qualitative ("this is too much flour", "this
+sentence is clunky", "this number feels off"), lead with a **concrete
+counter-proposal framed as a question** — then, if they confirm, post
+the suggestion immediately without waiting for a second "yes, go ahead".
+
+Two turns, not three:
+
+1. **Turn 1 (propose).** Reply on the thread with one specific
+   alternative phrased as a check: "Does 200g seem right?", "How about
+   'gently fold' instead of 'stir'?", "Would 45 minutes read better than
+   90?". Pick a real number / phrase — not "would you like me to
+   suggest a different amount?" (that's a question about your behavior,
+   not a proposal).
+2. **Turn 2 (commit on confirmation).** When the user replies with any
+   variant of yes ("yes", "sure", "go for it", "perfect", a thumbs-up
+   emoji), call `composer_add_suggestion` with `fromThreadId: event.threadId`
+   and the concrete replacement. Do NOT also post a comment reply — the
+   suggestion card IS your reply (see "Keep comment text terse" above).
+
+If the user says no / picks a different value / redirects, follow their
+lead — do not post the original proposal anyway.
+
+If you can't name a concrete alternative (e.g. the thread is too
+abstract to guess a number), ask a clarifying question instead. Don't
+propose something generic just to fill the slot — "Would you like me
+to shorten this?" is worthless without a target length.
+
 ## Anchors
 
 Write tools take:
@@ -128,9 +317,40 @@ 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.
+### Pick the right span — anchor = what gets deleted
+
+Your `textToFind` is literally cut out when the user accepts; your
+`replacementText` is inserted in its place. So:
+
+- **Anchor the whole unit you're changing.** Replacing a sentence →
+  include the terminal punctuation (`.`, `?`, `!`). Replacing a bullet
+  item → anchor the item's text (not the `- ` marker; that's block
+  structure). Replacing a paragraph → anchor the whole paragraph.
+- **Include any trailing punctuation you're changing.** Converting a
+  statement to a question? End the anchor at the `.` and end the
+  replacement with `?`. Don't anchor "the statement" alone and
+  replace with "the question?" — you'll end up with `the question?.`.
+- **Match your `replacementText`'s shape to the anchor's shape.** Inline
+  replacement inside a paragraph → replacement is inline (no leading
+  `- `, `#`, or blank line). Replacing a full list → replacement is a
+  full markdown list. Single-paragraph markdown is unwrapped to inline
+  on accept; multi-block markdown is inserted as blocks.
+- **Formatting is part of your replacement, not the anchor.** If the
+  original had `**bold**` or a link, the anchor's formatting is gone
+  on accept — your replacement must include the markdown syntax for
+  any formatting you want preserved.
+- **Anchor at token boundaries, not mid-word.** `textToFind: "istrat"`
+  to hit the middle of "administration" is fragile. Use whole words
+  or sentence boundaries. Use `occurrence` when the same phrase
+  appears multiple times.
+- **Mind the whitespace.** By default, do not include leading or
+  trailing whitespace in the anchor, and end `replacementText` at the
+  same boundary. If you include a trailing space in the anchor,
+  include one in the replacement too; otherwise words smash together.
+
+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