MCP and CLI

VegaStack exposes two agent surfaces over the same contract: a Model Context Protocol (MCP) JSON-RPC endpoint and a TypeScript CLI published on npm as @vegastack/cli (binary vegastack).

MCP

The MCP server lives at /mcp and authenticates via either an OAuth bearer token (default) or a static token in VEGASTACK_MCP_STATIC_TOKEN (development only). The tool surface is fixed by the @vegastack/mcp package and includes 24 tools:

fetch, search, wait_for_review, whoami, create_page, update_page, edit_page, restore_page_version, move_page, delete_page, restore_page, list_trash, list_comments, create_comment, update_thread, delete_thread, set_resource_public, grant_access, create_template, update_template, render_template, upload_attachment, invite_workspace_member, validate_page_source.

edit_page is the surgical multi-edit primitive — literal find/replace ops applied top-to-bottom with uniqueness + overlap checks. Use it instead of update_page for narrow changes; it concurrent-merges with non-overlapping edits and uses fewer tokens. list_comments returns the page's threads with anchor-text quotes and current reanchor_status, so an agent can drive the comment loop without polling review events directly.

Every tool except whoami requires workspace_id. Tools that create or move pages also require space_id — there is no default-space fallback on any surface (API, MCP, or CLI). The full schema is generated into docs/specs/mcp-tools.md from the contract package; do not hand-edit it.

OAuth device flow

Agents authenticate via the OAuth device flow. vegastack login requests a device code from /oauth/device, then opens /oauth/device/verify for the user to approve. After approval the CLI receives an access token and stores it locally.

vegastack CLI

Install with npm i -g @vegastack/cli (or npx @vegastack/cli). The CLI binary is named vegastack. Commands are noun-then-verb:

vegastack pages create --workspace wks_… --space sp_… --title "…"
vegastack pages get pg_…
vegastack pages edit pg_… --edit '[{"find":"old","replace":"new"}]' --base-seq 42
vegastack pages move --workspace wks_… --space sp_… --page pg_…
vegastack comments resolve thr_…
vegastack share public --resource-type page --resource-id pg_… --access view
vegastack share grant --resource-type page --resource-id pg_… --subject-type user --subject-id usr_… --role viewer
vegastack workspaces list
vegastack search "billing"
vegastack validate path/to/page.md
vegastack doctor
vegastack whoami

The CLI reads VEGASTACK_BASE_URL, VEGASTACK_ACCESS_TOKEN, and VEGASTACK_WORKSPACE_ID. vegastack --help enumerates the full command tree; vegastack completions prints every contract-mapped command.

Static tokens for development

In development with VEGASTACK_DEPLOYMENT_MODE=development, you can set VEGASTACK_MCP_STATIC_TOKEN plus VEGASTACK_MCP_STATIC_WORKSPACE_ID to skip OAuth. Workspace tools reject mismatched workspace IDs.

Review wait

wait_for_review blocks until a matching review_event arrives. This is how agents implement the human-in-the-loop pattern: update a page, request review, wait, then resolve threads or make the page public based on the outcome.