Skip to content
ComStack

MCP Examples

What this is

End-to-end examples showing how an AI assistant uses ComStack MCP tools — from reading project state through editing, approving, and publishing. Each example shows the user prompt, the tools called, and the expected outcome.

How it works

The assistant follows the page lifecycle: read state → draft edit → approve (translations run automatically) → publish dry run → publish confirm. All tool calls pass project_id; destructive calls also pass project_name (always call get-project-state first to get the correct value).

When to use it

Use these examples as a reference when building integrations, writing instructions for an AI assistant, or understanding the tool call sequence for a given workflow.

Parameters / fields / inputs

Key arguments used across examples:

ArgumentWhere usedNotes
project_idAll toolsRequired on every project-scoped tool call
project_nameDestructive toolsMust exactly match the stored project name
pathPage-level toolsThe Firestore doc id — use slug when you only have a URL
confirmation_tokenpublish-confirmSingle-use, 5-min TTL — call publish again if it expires

Example

Example 1 — Read: “Show me my drafts”

User: “What drafts do I have in my ComStack project?”

Tools called:

  1. list-my-projects → [{ project_id: "p8C98...", name: "Acme Real Estate", role: "manager" }]
  2. get-project-state with project_id: "p8C98..." → snapshot with draft_pages: [{ path: "guides/buying", title: "Buying Guide" }, { path: "guides/selling", title: "Selling Guide" }]

Assistant response: “You have 2 drafts: ‘Buying Guide’ and ‘Selling Guide’. Would you like to edit or publish them?”

Example 2 — Edit: “Update the homepage description”

User: “Change the homepage description to ‘Find your dream property on the Costa del Sol’.”

Tools called:

  1. get-project-state → confirms project and gets project_name: "Acme Real Estate"
  2. get-page-content with slug: "index" → current metadata and content
  3. update-page with slug: "index", metadata: { description: "Find your dream property on the Costa del Sol" } → { action: "draft_created_from_live", draft_id: "AbC...", next_step: "Present updated content to user for review" }

Assistant (presents the draft for user review): “Here’s the updated description. The live page stays up until we publish. Say ‘approve’ when ready — or let me know if you’d like to tweak the wording.”

Example 3 — Approve and publish: “Take it live”

User: “Looks good — take it live.”

Tools called:

  1. approve-page with the draft path → { status: "approved", next_action: "translating", locales_total: 2 }. Translations run in the background; the assistant informs the user they can keep working.
  2. (later, after translations complete) get-project-state → page is in ready_pages with next_action: "publish".
  3. publish with project_name: "Acme Real Estate" → manifest with the 3 ready pages (EN source + 2 translated variants) + confirmation_token.
  4. Assistant presents the manifest (titles, URLs, byte sizes before/after) to the user.
  5. publish-confirm with confirmation_token → { status: "running" }. Deploy is async.
  6. publish-status (poll until succeeded) → published_urls.

Assistant response: “Published! The pages are live at the URLs in the manifest. Here are the links: [lists published_urls].”

Example 4 — Create a new page

User: “Create a new guide page about buying property in Marbella.”

Tools called:

  1. get-project-state → gets available templates and confirms no slug collision
  2. get-doc-template with the relevant template id → receives metadata_example, markdown_template, and quick_checklist
  3. create-page with the composed content and metadata → validates everything at once. If validation fails, the response lists all issues with fix strings in one go.

Assistant (presents the new draft): “Here’s the draft ‘Buying in Marbella’. Let me know if you’d like any changes before we approve and publish.”

Common errors

ErrorCauseFix
Token expired at step 5More than 5 minutes elapsed since publishCall publish again for a fresh token
Manifest changed at publish-confirmA ready page changed between dry run and confirmCall publish again
approve-page refusesDraft has validation errorsThe response lists all issues; fix them and retry
Slug collision on create-pageAnother page already uses that slug + languageUse update-page with the existing page’s path, or choose a different slug

Last updated: