Start an agent workspace

The workspace keeps your brief, decisions and verification across agent sessions. Typeroll CMS keeps the actual Pages, Content types, templates and settings. You can use hosted MCP without a local folder; a workspace is useful for longer projects and agents that can read local files.

Version availability: this workflow is introduced in MCP 0.45.23. Hosted compact discovery and the Site Organization ID check require Core 0.2.27. Until those releases are installed, use the existing hosted connection. These are version requirements, not a promise that every Cloud or self-hosted portal has already upgraded.

A starter you can keep in your own repository

Start with the public Typeroll/site-starter GitHub template, or use typeroll init below to generate a local folder. Both contain the same released starter instructions and prompts. The template adds a GitHub introduction and maintenance files; it is generated from the published MCP package rather than maintained as a second set of instructions. This planning workspace is separate from the Typeroll-managed publication repository; never edit generated publishing source to change the website.

The starter has places for the owner’s wishes and rules, brand direction, content model, SEO strategy, migration plan, decisions, task routines and QA. The owner and agent can maintain these together. Current Pages, schema and settings remain in the CMS, not in duplicated local exports.

The expanded rules/SEO/routines scaffold requires MCP 0.45.77 or later. If that release is not installed yet, create those Markdown files yourself using the structure below; hosted MCP editing does not depend on the local scaffold. @latest selects the published starter version. The generated lock records it; client adapters pin their generated MCP version. Review upgrades explicitly.

Ask your agent to start a migration

In a new conversation, replace [website URL] and send:

Help me migrate [website URL] to Typeroll CMS using https://github.com/Typeroll/site-starter. Read its AGENTS.md and guide me through the migration interview before starting work.

This points the agent to the starter instead of duplicating its instructions. The interview records your choices for text and design/images independently. The agent can help with the workspace setup below; if it cannot read GitHub, provide the starter files through your client’s supported file access. See the WordPress migration guide for import requirements and review steps.

Create your repository from the GitHub template

1. Open Typeroll/site-starter.

2. Choose Use this template → Create a new repository.

3. Select the GitHub account or organization that should own the project and give it a name, such as my-site-workspace. Choose Private for customer projects, business plans or unpublished research. Copy only the default branch.

4. Choose Create repository from template. Your new repository is independent, with fresh history. A fork is not needed.

5. Open your new repository, choose Code, and copy its clone URL. Clone it in the environment where your agent works. Replace the placeholders:

   git clone https://github.com/YOUR-OWNER/YOUR-SITE.git
   cd YOUR-SITE

   Or open your repository in a GitHub Codespace or connect it to an agent’s cloud environment. Keep the workspace in your own repository so it is not tied to one computer. If the client only accepts uploaded project files, attach the relevant starter files; MCP cannot read a GitHub repository or local folder automatically.

6. Have the agent read AGENTS.md and use the guided start. The files are ready to read without installing Node.js. Node.js 20 or later is only needed for the optional CLI setup, update and doctor commands.

7. Connect MCP, select the correct Site and Version and fill typeroll.json as described below. Creating the GitHub repository does not create a Typeroll account, Site, hosting connection or deployment.

With an authenticated GitHub CLI, steps 1–5 can also be done with:

gh repo create YOUR-OWNER/YOUR-SITE --template Typeroll/site-starter --private --clone
cd YOUR-SITE

Use the template for new projects. For an existing workspace, use init --update; do not copy the template over your project or merge its history into your own.

The original template checks for stable MCP releases daily. Its maintenance workflows only run in Typeroll/site-starter, never in your copy. You may remove .github/ from your own repository. Updating the original does not update your project automatically. Keep typeroll.lock.json: it lets the CLI update unchanged starter files while preserving your own edits.

Start without a repository

1. Connect your agent to https://app.typeroll.com/api/mcp?tools=compact. Self-hosted installations use their own portal origin with the same path. Use the OAuth or private bearer-header setup in Connect your AI agent.
2. Ask the agent to discover list_sites and read the accessible sites.
3. Select a Site, or use create_site with an Organization-scoped key to create one. A site-scoped key cannot create another Site.
4. Read that Site’s capabilities and the relevant recipe. Create editable blocks, review a preview, and save within your agreed scope.

GitHub, Cloudflare and a domain are not required to start authoring or previewing. Publishing setup is required before deploying. Imports require verified Organization storage before importing any content; check get_import_readiness. This is distinct from ordinary new draft uploads.

Generate a local workspace instead

Use Node.js 20 or later for the standalone MCP package:

npx @typeroll/mcp-server@latest init ./my-site

This is a local filesystem operation: it creates no remote Site, repository, account, deployment or login, and needs no API key. Open the folder in your agent client and point it at AGENTS.md. Automatic instruction loading depends on the client; creating the folder does not guarantee that it reads the file.

If you later want to store this generated folder on GitHub, inspect its files for secrets or private exports, then initialize your own repository:

cd my-site
git init -b main
git add .
git commit -m "Start website workspace"
gh repo create YOUR-OWNER/YOUR-SITE --private --source=. --remote=origin --push

This alternative needs Git and an authenticated GitHub CLI. It creates and pushes your private workspace; it does not publish a website.

my-site/
├── AGENTS.md
├── README.md
├── typeroll.json
├── typeroll.lock.json
├── .gitignore
├── brief/
│   ├── site.md
│   ├── brand.md
│   ├── content-model.md
│   ├── migration.md
│   ├── interview.md
│   ├── rules.md
│   └── seo.md
├── workflows/
│   ├── README.md
│   ├── interview.md
│   ├── new-site.md
│   └── migration.md
├── decisions.md
├── sources/README.md
├── scripts/README.md
└── qa/checklist.md

• Brief: purpose, audience, languages, brand, editorial constraints, content authority, types/routes and desktop/mobile navigation intent.
• Owner rules: brief/rules.md records confirmed preferences, writing and design constraints, approval boundaries and exceptions, with dates and owners. Distinguish proposals from approved decisions. Local notes do not bypass permissions.
• SEO strategy: brief/seo.md records audiences, search intent, research evidence, topic coverage, page roles, URL/indexing policy, editorial standards and measurement. Actual metadata, canonicals and robots settings live in the CMS.
• Routines: workflows/README.md maps tasks to the relevant project files and on-demand MCP skills. workflows/migration.md includes a copyable kickoff prompt. Add your own routines with inputs, steps, acceptance checks and approval boundaries.
• Decisions: approved scope, design choices and deliberate deviations.
• Sources: research and proposals. Keep private extracts in ignored sources/private/. Do not store media libraries or current CMS content as a competing source of truth.
• QA: tested Site/Version, pages, viewports, interaction states, evidence and remaining issues. Screenshots/private reports go in ignored qa/reports/.
• Scripts: repeatable imports or checks using the REST API when useful.
• Lock: generator version and hashes of managed starter files. Commit it with the workspace. It does not pin the hosted CMS or its content.

The generated AGENTS.md also tells the agent where everyday help lives, so it does not depend on the portal’s optional built-in AI chat:

• tr-edit-site for page and preview links, images, menus, site-wide changes as shared blocks, settings and analytics.
• add_faq_schema, add_recipe_schema and add_event_schema for FAQ, recipe and event structured data (Pages tools).
• tr-starter-design for a blank Site or one that keeps the starter design.
• For migrations, read tr-migration-evidence before the source-specific recipe. Record independent text and design/image choices in brief/migration.md; see Choose your migration approach.
• When an AI workflow fails with ai_not_enabled, the agent does the same work itself with the matching recipe and says so (Workflows).

An existing workspace receives this text with init --update when its AGENTS.md is unchanged; an edited AGENTS.md is kept, so add the pointers yourself.

You may version this workspace in your own private Git repository. Keep it separate from the CMS-generated publication repository: changes to a site are made through Typeroll, not by editing exported build source.

Bind the Site and Version

Edit the generated typeroll.json after selecting or creating your Site:

{
  "schema_version": 1,
  "portal": "https://app.typeroll.com",
  "organization_id": "your-organization-id",
  "site_id": "your-site-id",
  "version": "main",
  "tool_mode": "compact"
}

Use IDs returned by Typeroll, not display names. get_site returns the Site’s organization_id on Core 0.2.27+. A new workspace has null IDs until you choose its target. portal is an origin, not an MCP URL; do not put a token in it. HTTPS is required except for local loopback development.

For substantial work on an existing Site, use create_branch, record the returned ID in version, and reconnect a local workspace MCP process. The workspace process supplies that Version on site API requests; an explicit tool Version takes precedence. Hosted MCP cannot read this local file: the agent must pass the chosen Site/Version in its calls.

Never put API keys, cookies or provider credentials in typeroll.json. Use private client settings or environment injection. .gitignore excludes .env, local client configurations and temporary/private output. Ignore rules cannot remove secrets that were already committed; inspect existing repositories.

Guided start

The detailed kickoff prompts and interview routines live in the generated starter:

• workflows/interview.md — the agent’s structured interview when you need guidance.
• workflows/new-site.md — the kickoff for a new website with a clear brief.
• workflows/migration.md — the kickoff for a migration with a clear brief.

The canonical Markdown sources are in the public repository’s workspace-templates directory and are shipped with MCP 0.45.77+. The starter generator uses those same files. Adapt your generated copies to your project; updates preserve your edits.

Open your workspace with your agent and have it read AGENTS.md. When guidance is needed or an important decision is missing, those instructions lead it into the interview. It asks one short question at a time, reuses answers already given and saves progress in brief/interview.md. You can pause and resume in another session; a complete brief skips the interview. It is an agent routine, not a portal wizard, and planning can start before connecting MCP.

The interview covers goals, target Site, text preservation, design and images, content/features, SEO, owner rules and acceptance. For a migration, you choose preserve or renew separately for text and for design/images. It also records image exceptions and metadata rules. The agent recaps confirmed decisions and open questions before dependent work. Silence is never approval, and approving the brief alone does not authorize publication, DNS changes or messages.

Keep prompts in your project alongside the brief, rules and QA evidence. Read only the relevant routine and load MCP recipes on demand. If your client cannot read local files, attach the relevant starter files to its project context; hosted MCP cannot read your folder automatically.

Optional local client configuration

Hosted MCP is sufficient. If your client launches local stdio processes, you can also generate a client configuration explicitly:

npx @typeroll/mcp-server@latest init ./my-site --client claude
npx @typeroll/mcp-server@latest init ./my-site --client cursor
npx @typeroll/mcp-server@latest init ./my-site --client vscode

Choose one command for your client. These generate .mcp.json, .cursor/mcp.json or .vscode/mcp.json, respectively, with a version-pinned invocation of workspace-mcp and this local folder’s absolute path. Existing edited client configurations are preserved; merge the desired connection through your client’s settings. Recreate a local configuration after moving/cloning the workspace. These adapters do not certify every client version; see Client compatibility.

Inject TYPEROLL_API_KEY into the launched process. The configuration contains no key and does not read .env automatically. If the client supports its own secret store, use it. Conflicting TYPEROLL_API_URL or TYPEROLL_SITE_ID environment values are rejected rather than silently switching to another Site.

typeroll.json is committed, so from MCP 0.45.83 its portal alone is trusted only when it is the hosted portal https://app.typeroll.com. For a self-hosted or other portal, also set TYPEROLL_API_URL to the same origin in your private client settings or environment. Without it, workspace-mcp, doctor and the Python helpers in scripts/typeroll/ refuse to send the API key, so a changed portal in a pull request cannot redirect your credential.

An unbound workspace-mcp process allows discovery and site creation only. After creation, fill the IDs in typeroll.json and reconnect before editing. For clients without an adapter, launch:

npx @typeroll/mcp-server@latest workspace-mcp ./my-site

Check the setup

npx @typeroll/mcp-server@latest doctor ./my-site --offline
npx @typeroll/mcp-server@latest doctor ./my-site --json

The online command uses the injected API key. It reads accessible sites, the selected Site/Version, its Organization and capabilities. It prints no credential values and performs no writes, uploads or deployments. Missing setup returns a nonzero exit status and an actionable check. Offline mode validates local setup only and marks remote checks as unverified.

Successful reads do not prove write permission, publishing readiness or app setup. Read the relevant readiness checks when starting those operations. The doctor does not fetch all app guides into your workspace; the agent loads them when needed.

Keep MCP context small

The full MCP mode advertises the complete tool catalog. Compact mode advertises only five tools regardless of the catalog’s size:

Tool	Purpose
search_tools	Search names and task descriptions; brief paginated results, no schemas.
describe_tool	Read one tool’s exact schema, full description and effect.
call_read_tool	Execute only read tools.
call_write_tool	Execute writes, including publishing, within user authorization.
call_admin_tool	Execute app administration/activation within user authorization.

For example, discover read_page, inspect its schema, then call:

{
  "name": "read_page",
  "arguments": {
    "site_id": "your-site-id",
    "page_id": "home",
    "version": "main"
  }
}

Pass this to call_read_tool; omit site_id for a fixed-site connection. Validation and underlying API authorization remain in force. A read wrapper cannot invoke a write tool. Discovery itself grants no permission. Client confirmation settings still need to cover write/admin wrappers; inspect the nested tool name and arguments before approving an operation.

Use read_guide with sections_only: true, then request the relevant section ID. Use list_skills and read only the task’s recipe. Load enabled app guidance through read_app_documentation when the task needs it. Private app docs stay behind authenticated discovery; do not copy them into public repositories.

Compact discovery reduces the initial schema payload, not the amount of content a later request can return. Paginate Page lists and request relevant fields; do not read an entire site’s content or llms-full.txt at every session. Clients with native deferred tool loading may already avoid much of the full-catalog cost. Actual context usage depends on the client and tokenizer.

Existing connections retain full mode. To select compact mode:

• Hosted: add ?tools=compact to /api/mcp; authentication and OAuth audience remain the canonical portal MCP resource.
• Workspace stdio: generated tool_mode is compact.
• Legacy stdio: set TYPEROLL_MCP_TOOL_MODE=compact.

Use tools=full, tool_mode: "full", or the corresponding environment value to restore the named-tool catalog if a client handles it better.

Update without losing project work

npx @typeroll/mcp-server@latest init ./my-site --update

An unchanged generated file can be upgraded. A user-edited file is reported as modified and preserved. typeroll.json remains user-owned. Review those files against current guidance manually; do not assume an update overwrote them. The GitHub template’s additional README introduction counts as an edit, so the updater preserves that README too. No fork, upstream merge or re-clone is needed. The updater does not merge client configurations or delete removed recipes. There is no destructive --force option for the workspace scaffold.

To update a generated client adapter’s pinned MCP version, include the same client option: init ./my-site --update --client cursor (or claude/vscode). Without --client, the updater leaves local client configurations alone.

Recipes are served by MCP by default. For offline reference, opt in:

npx @typeroll/mcp-server@latest init ./my-site --recipes
npx @typeroll/mcp-server@latest init ./my-site --recipes --update

They live in neutral typeroll-skills/ and follow the same hash-based update rules. They are Markdown references, not a guarantee of automatic client loading. Keep project-specific instructions in brief/, decisions.md and AGENTS.md. The runtime capabilities and resolved app versions take precedence over old copies.

MCP, CLI or API?

Use MCP for interactive agent work and the CLI for workspace setup/checks. For repeatable large imports and integration scripts, use the same authenticated REST API. The CLI also has Extension commands, but it is not a full site CRUD CLI. Both transports use the same CMS; changing transport does not make builds faster.

Repeatable migration QA tools

MCP 0.45.79 adds optional Python and Playwright helpers under scripts/typeroll/. Availability depends on the installed MCP starter version; check scripts/README.md in your generated workspace. The GitHub template only syncs released versions. Existing projects use init --update; edited scripts and owner instructions are preserved for manual reconciliation.

The tools check unsaved Pages/partials before deployment, migration URL chains and media after deployment, screenshots around breakpoints, whole-card targets, and preserved text against saved HTML or a WordPress REST record. They read the workspace binding, keep credentials outside files, and do not publish or switch DNS. Browser review still matters: automated output is not visual acceptance, and an unreachable URL is unverified rather than automatically broken.

See the starter’s workflows/migration.md, workflows/design.md, qa/checklist.md and scripts/README.md for the routines and commands. Keep platform findings in qa/typeroll-platform-feedback.md. Customer-specific conversion scripts are examples, not a universal automatic HTML-to-blocks pipeline.

Repository-only Page notes

The starter includes pages/README.md, workflows/page-notes.md and scripts/typeroll/page_notes.py. Keep sources, review dates, internal decisions and dated change logs per stable Page ID in the workspace. Read the note before editing and update it afterward. At each editorial review, inspect the rendered Page and its external links. Archive notes for confirmed removed Pages under pages/archived/; retain their history.

Run the helper from the workspace root with --dry-run first. It reads saved CMS content in batches and refreshes only generated facts and the review index. It never writes to the CMS, overwrites human sections, advances review dates or archives notes automatically. See the starter instructions for private credential injection and optional migration URL facts. Keep the workspace private when notes are private; these files must never enter public site output. Existing workspaces receive the files through the normal init --update flow, preserving local edits.