@phenomenalorg/mcp 0.5.1 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phenomenalorg/mcp",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "description": "Phenomenal MCP bridge — connects a stdio-only MCP client to the Phenomenal MCP server over Streamable HTTP, with browser sign-in.",
   "license": "MIT",

package/skill/SKILL.md

@@ -8,7 +8,7 @@ description: Use when the user wants to manage a PTO, school or club in Phenomen
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
+_Tool surface: 47 tools · 170 actions · 5 prompts · fingerprint `d1014c5e`._
 
 You are connected to Phenomenal, the platform for this PTO's site, members, events, tickets, email, forms, store and money.
 

package/skill/references/mutations.md

@@ -3,7 +3,7 @@
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
+_Tool surface: 47 tools · 170 actions · 5 prompts · fingerprint `d1014c5e`._
 
 The curated tools in `references/tools.md` cover the work an officer does most days. Everything else Phenomenal can do is reachable by name:
 
@@ -15,7 +15,7 @@ Prefer a curated tool when one covers what you need: it is one call instead of t
 
 **(confirm)** marks an action that sends mail, moves money, publishes something publicly, deletes something, changes who can do what, or changes the organization's web address. Those change nothing until a person has said yes in words. Every action is subject to your role in the organization regardless; the confirm gate is about being asked, not about being allowed.
 
-Areas: account, brand, broadcasts, connections, domains, drive, email-preferences, events, forms, groups, knowledge, looks, media, meetings, members, money, orders, organization, pages, store, tasks, tickets.
+Areas: account, brand, broadcasts, connections, domains, drive, email-preferences, events, forms, groups, knowledge, looks, media, meetings, members, money, orders, organization, pages, reusable-content, store, tasks, tickets.
 
 ## account
 
@@ -227,6 +227,14 @@ Areas: account, brand, broadcasts, connections, domains, drive, email-preference
 - `unpublishPage` **(confirm)** — Prefer the `unpublish_page` tool. Take a page off the live site.
 - `updatePageDraft` — Prefer the `update_page_draft` tool. Replace a page draft with new blocks.
 
+## reusable-content
+
+- `deleteReusableContent` **(confirm)** — Remove reusable content at an exact expected policy version.
+- `prepareReusableContentCopy` — Prepare an idempotent, 30-minute copy of an authorized reusable revision into complete candidate blocks for one page, event or broadcast at its exact destination token and insertion index.
+- `saveReusableContentNew` — Save a new reusable composition and its first immutable revision from complete blocks, an initial-use audience and a per-operation idempotency key.
+- `saveReusableContentRevision` — Append an immutable complete-block revision using the exact current revision id and policy version plus a per-operation idempotency key.
+- `updateReusableContentPolicy` **(confirm)** — Change reusable-content ownership, metadata, initial-use audience and the complete grant set at an exact expected policy version.
+
 ## store
 
 - `createOrgProduct` — Add a product to the store from a catalog blank at a retail price.

package/skill/references/schema.md

@@ -3,7 +3,7 @@
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
+_Tool surface: 47 tools · 170 actions · 5 prompts · fingerprint `d1014c5e`._
 
 Two tools answer questions no curated tool anticipated.
 

package/skill/references/starting-doc.md

@@ -3,7 +3,7 @@
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
+_Tool surface: 47 tools · 170 actions · 5 prompts · fingerprint `d1014c5e`._
 
 Phenomenal runs a school's PTO: its public website, its member roster, its events and tickets, its email to families, its forms, its store and its money. It exposes all of that over the Model Context Protocol, so an assistant an officer already uses can do the work with them.
 

package/skill/references/tools.md

@@ -3,7 +3,7 @@
 <!-- Generated from the Phenomenal tool registry. Do not edit by hand: a drift
      gate fails when these files are not what the registry currently says. -->
 
-_Tool surface: 42 tools · 165 actions · 5 prompts · fingerprint `a8796891`._
+_Tool surface: 47 tools · 170 actions · 5 prompts · fingerprint `d1014c5e`._
 
 Every tool the Phenomenal MCP server offers, in the order a client lists them. `list_my_orgs` is first because every other tool needs an organization id from it.
 
@@ -116,7 +116,7 @@ Read the complete authorized page content, Looks appearance, revisions, actions
 
 ### `preview_page_changes`
 
-Validate complete page content and a Look together without writing. DRAFT previews edits; PUBLISH previews the exact stored draft.
+Validate complete page content, pending reusable-copy receipts and a Look together without writing. DRAFT previews edits; PUBLISH accepts no edits or pending copies and previews the exact stored draft.
 
 **Hints:** read-only, idempotent. **Confirm:** not required.
 
@@ -128,11 +128,12 @@ Validate complete page content and a Look together without writing. DRAFT previe
 - `expectedThemeRevision` (string, required) — Copy exactly from get_page_authoring_state; never infer or synthesize it.
 - `content` (object)
 - `lookChange` (any)
+- `pendingCopies` (array) — Exact pendingCopy receipt(s) from prepare_reusable_content_copy. cancelledRootIds may contain only deliberately removed inserted roots.
 - `effect` (string (DRAFT | PUBLISH)) — DRAFT by default. PUBLISH accepts no edits and previews stored state.
 
 ### `save_page_changes`
 
-Save one previously previewed complete page-and-Look DRAFT atomically. It remains private and never publishes or retries.
+Save one previously previewed complete page-and-Look DRAFT with the identical pending reusable-copy receipts atomically. It remains private and never publishes or retries.
 
 **Hints:** writes. **Confirm:** not required.
 
@@ -144,8 +145,82 @@ Save one previously previewed complete page-and-Look DRAFT atomically. It remain
 - `expectedThemeRevision` (string, required) — Copy exactly from get_page_authoring_state; never infer or synthesize it.
 - `content` (object)
 - `lookChange` (any)
+- `pendingCopies` (array) — Exact pendingCopy receipt(s) from prepare_reusable_content_copy. cancelledRootIds may contain only deliberately removed inserted roots.
 - `previewDigest` (string, required) — Copy exactly from the matching VALID DRAFT preview.
 
+### `list_reusable_content`
+
+List compact reusable-content summaries this actor may read, including exact revision, policy and distinct read/use/revise/administer facts. Use get_reusable_content for blocks and grants.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `limit` (integer)
+- `cursor` (string) — The prior page’s last returned content id.
+
+### `get_reusable_content`
+
+Read one authorized reusable composition and exact revision with complete blocks, grants and permission facts. An unavailable id reveals no metadata.
+
+**Hints:** read-only, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `contentId` (string, required)
+- `revisionId` (string) — Optional exact immutable revision id.
+
+### `save_reusable_content_new`
+
+Save a new private reusable-content identity from complete canonical blocks. It does not publish or insert content anywhere.
+
+**Hints:** writes, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `ownerGroupId` (any)
+- `name` (string, required)
+- `description` (string)
+- `blocks` (array, required) — The complete canonical Phenomenal block array, including every locale and child.
+- `initialUseAudience` (string, required) — public, members, or group:<uuid>.
+- `idempotencyKey` (string, required) — A caller-stable key for this exact input.
+
+### `save_reusable_content_revision`
+
+Append one immutable complete-block revision under exact revision and policy compare-and-swap values. Existing revisions remain unchanged.
+
+**Hints:** writes, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `contentId` (string, required)
+- `expectedRevisionId` (string, required)
+- `expectedPolicyVersion` (integer, required)
+- `blocks` (array, required) — The complete canonical Phenomenal block array, including every locale and child.
+- `idempotencyKey` (string, required) — A caller-stable key for this exact input.
+
+### `prepare_reusable_content_copy`
+
+Read source and destination state first, then create actor-bound 30-minute staging against the complete unsaved candidate and exact destination token. Inspect the returned complete blocks, source snapshot, fresh IDs and expiresAt. For a page, DRAFT preview and explicitly save with the identical pendingCopy, then read back canonical state; event and broadcast saves are also explicit and never publish or send. Copies are independent: source edits or revocation do not rewrite committed destinations, and restricted media keeps its policy. If latest was omitted, retry with the returned explicit source revision.
+
+**Hints:** writes, idempotent. **Confirm:** not required.
+
+**Arguments**
+
+- `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `contentId` (string, required)
+- `revisionId` (string) — Optional exact source revision. Reuse the returned source.revisionId on retry.
+- `destination` (object, required)
+- `expectedDestinationToken` (string, required)
+- `destinationAudience` (string, required) — public, members, or group:<uuid>.
+- `candidateBlocks` (array, required) — The complete canonical Phenomenal block array, including every locale and child.
+- `insertionIndex` (integer, required)
+- `idempotencyKey` (string, required) — A caller-stable key for this exact prepare.
+
 ### `draft_page`
 
 Draft content for a Phenomenal page from a plain-language instruction and return the blocks. It SAVES NOTHING — show the result to the person, then save it with update_page_draft. This counts against the organization's AI budget, exactly as drafting from the admin app does.
@@ -194,13 +269,14 @@ Take a page off the live Phenomenal site. The draft is kept, but every link anyo
 
 ### `list_events`
 
-The events on a Phenomenal organization's calendar, soonest first, with whether each one is published.
+List compact event summaries on a Phenomenal organization's calendar, soonest first. Pass eventId alone to read one complete authorized event including pageBlocks.
 
 **Hints:** read-only, idempotent. **Confirm:** not required.
 
 **Arguments**
 
 - `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `eventId` (string) — Read one complete authorized event. Cannot be combined with from or to.
 - `from` (string) — Only events starting on or after this date (YYYY-MM-DD).
 - `to` (string) — Only events starting on or before this date (YYYY-MM-DD).
 
@@ -222,7 +298,7 @@ Create an event in Phenomenal. It starts UNPUBLISHED — nobody outside the orga
 
 ### `update_event`
 
-Change an event in Phenomenal — its title, time, place or description. Only the fields you pass are changed. If the event is already published, the site changes at once.
+Change an event in Phenomenal — its title, time, place or description. Only the fields you pass are changed. A prepared copy requires complete pageBlocks, the exact revision and pendingCopies together. If the event is already published, the site changes at once.
 
 **Hints:** writes, idempotent. **Confirm:** not required.
 
@@ -235,6 +311,9 @@ Change an event in Phenomenal — its title, time, place or description. Only th
 - `endsAt` (string) — A new end, ISO 8601.
 - `location` (string) — A new location.
 - `description` (string) — A new description.
+- `pageBlocks` (array) — The complete prepared event-page candidate. Live data bindings are not supported here.
+- `expectedRevision` (string) — Exact revision read from list_events and used for preparation.
+- `pendingCopies` (array) — Exact pendingCopy receipt(s) from prepare_reusable_content_copy. cancelledRootIds may contain only deliberately removed inserted roots.
 
 ### `set_event_published`
 
@@ -273,28 +352,33 @@ Who is in one Phenomenal group, with each person's relation to it (member, stewa
 
 ### `list_broadcasts`
 
-The email broadcasts of a Phenomenal organization — drafts and sent ones — with how many people each reached.
+List compact broadcast summaries for a Phenomenal organization. Pass broadcastId to read one complete authorized draft including localized subject and body.
 
 **Hints:** read-only, idempotent. **Confirm:** not required.
 
 **Arguments**
 
 - `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
+- `broadcastId` (string) — Read one complete authorized broadcast by id.
 - `status` (string) — Only broadcasts in this state, e.g. "draft" or "sent".
 
 ### `draft_broadcast`
 
-Write an email broadcast draft for a Phenomenal organization and choose who it would go to. SENDS NOTHING — it creates a draft and tells you how many people it would reach.
+Create an email broadcast draft, or explicitly save complete prepared bodyBlocks into an existing draft with its exact revision and pendingCopies. SENDS NOTHING in either mode.
 
 **Hints:** writes. **Confirm:** not required.
 
 **Arguments**
 
 - `orgId` (string) — The organization to act for — an id from list_my_orgs. Never invent one; if you are unsure which, ask the person.
-- `subject` (string, required) — The subject line families will see.
-- `body` (string, required) — The message, in Markdown. Write it the way a parent would want to read it — short, warm, and clear about dates and what to do.
-- `audience` (object) — Who it goes to. Leave it out entirely to address every member of the organization.
+- `broadcastId` (string) — Existing draft id. Omit to create a new markdown draft.
+- `subject` (string) — The subject line families will see.
+- `body` (string) — The message, in Markdown. Write it the way a parent would want to read it — short, warm, and clear about dates and what to do.
+- `audience` (object) — Who it goes to. Omission selects every member for a new draft, but preserves the stored audience when saving an existing draft.
 - `replyTo` (string) — Where replies go. Optional — the organization's contact address is used otherwise.
+- `bodyBlocks` (array) — Complete prepared block-body candidate for existing-draft mode only.
+- `expectedRevision` (string) — Exact revision used to prepare this existing broadcast draft.
+- `pendingCopies` (array) — Exact pendingCopy receipt(s) from prepare_reusable_content_copy. cancelledRootIds may contain only deliberately removed inserted roots.
 
 ### `send_broadcast_test`
 
@@ -473,7 +557,7 @@ Every action Phenomenal can take that the curated tools do not already cover, as
 
 **Arguments**
 
-- `area` (string (account | brand | broadcasts | connections | domains | drive | email-preferences | events | forms | groups | knowledge | looks | media | meetings | members | money | orders | organization | pages | store | tasks | tickets)) — Only actions in this part of Phenomenal.
+- `area` (string (account | brand | broadcasts | connections | domains | drive | email-preferences | events | forms | groups | knowledge | looks | media | meetings | members | money | orders | organization | pages | reusable-content | store | tasks | tickets)) — Only actions in this part of Phenomenal.
 - `search` (string) — Only actions whose name or summary contains this word.
 
 ### `describe_mutation`