App Development

This reference is auto-generated from the registered MCP tool providers in perspectapiworkers. It reflects the tools exposed by the per-site Perspect MCP server.

Connection

Use the per-site MCP endpoint:

https://perspect.com/mcp/{siteName}

Authenticate with OAuth or an MCP API key using Authorization: Bearer sk_mcp_....

Tools

app_build_status

Title: Check Build Status

Check the status of the most recent build for this site. Returns status (pending, deploying, deployed, failed) and any error details. Avoid rapid loops: check no more than once every 30-60 seconds while deploying. Server enforces poll throttling while deploying. Build logs are compact by default; request full logs only when needed. Pass build_id from release_deploy when available.

Required permission: app.read

Parameters

Parameter	Type	Required	Default	Description
build_id	string	No	—	Optional build ID from release_deploy to read a specific build log key directly
include_full_log	boolean	No	false	When true, return the entire build log (can be large). Default: false
tail_lines	number	No	60	Number of log lines to return when include_full_log=false (default: 60, max: 200)
force_log_refresh	boolean	No	false	Force an immediate status+log read even if polled recently. Default: false

Example call

{
  "tool": "app_build_status",
  "arguments": {
    "include_full_log": false,
    "tail_lines": 60,
    "force_log_refresh": false
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_cancel_build

Title: Cancel Build

Cancel in-flight build(s) for this site. With build_id, cancels that build; otherwise cancels ALL queued/running builds. Cancellation flags the build(s) in the ledger (so they will not deploy) and destroys their build containers. Safety guard: cancellations are blocked while a build is fresh (<10 minutes) unless force=true is provided. After canceling, fix issues and use the security-gated release flow again.

Required permission: app.deploy

Parameters

Parameter	Type	Required	Default	Description
build_id	string	No	—	Optional specific build to cancel (from app_build_status). If omitted, cancels all in-flight builds for the site.
force	boolean	No	false	Override cancellation safety guard for emergency aborts. Default: false
reason	string	No	—	Optional cancellation reason recorded in deployment status/logs

Example call

{
  "tool": "app_cancel_build",
  "arguments": {
    "force": false
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_check

Title: Check App

Run deterministic app validation after a coherent change set. fast runs route registration checks plus SDK misuse scans without full TypeScript compilation. release runs fast checks plus React Router typegen/local TypeScript and a workspace diff summary against the current R2 source checkpoint.

Required permission: app.read

Parameters

Parameter	Type	Required	Default	Description
level	string	No	"fast"	Validation depth. Default: fast. Allowed: fast, release.
diff_max_chars	number	No	60000	Maximum diff characters to include when level=release. Default: 60000.

Example call

{
  "tool": "app_check",
  "arguments": {
    "level": "fast",
    "diff_max_chars": 60000
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_delete_file

Title: Delete App File

Delete one existing app source file. Read the file with app_read_file before deleting it, then pass the returned read_token or metadata.sha256 so stale deletes are rejected. Only deletes regular files, not directories or symlinks. The tool returns a removal diff and rolls the sandbox file back if durable source checkpointing fails.

Required permission: app.write

Parameters

Parameter	Type	Required	Default	Description
path	string	Yes	—	File path relative to workspace root (e.g., 'app/routes/old.tsx')
read_token	string	No	—	read_token returned by app_read_file for this path. Required unless expected_sha256 is supplied.
expected_sha256	string	No	—	metadata.sha256 returned by app_read_file. May be used instead of read_token for staleness checking.
dry_run	boolean	No	false	When true, validate and return the deletion diff without deleting. Default false.

Example call

{
  "tool": "app_delete_file",
  "arguments": {
    "path": "string",
    "dry_run": false
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_edit_file

Title: Edit App File

Perform one targeted exact-string replacement in an app source file. Read the file with app_read_file before editing existing files, then pass the returned read_token or metadata.sha256. old_string must match the normalized file content exactly and uniquely unless replace_all=true. Use old_string="" only to create a missing file or fill an empty file. The tool rejects stale reads, ambiguous matches, notebooks, binary content, symlinks, unsupported paths, and no-op edits; it writes the updated full file after validation and returns a diff.

Required permission: app.write

Parameters

Parameter	Type	Required	Default	Description
path	string	Yes	—	File path relative to workspace root (e.g., 'app/routes/home.tsx')
old_string	string	Yes	—	Exact text to replace from app_read_file output. Use an empty string only when creating a missing file or filling an empty file.
new_string	string	Yes	—	Replacement text.
replace_all	boolean	No	false	When true, replace every occurrence. Default false requires old_string to be unique.
read_token	string	No	—	read_token returned by app_read_file for this path. Required for existing files unless expected_sha256 is supplied.
expected_sha256	string	No	—	metadata.sha256 returned by app_read_file. May be used instead of read_token for staleness checking.
dry_run	boolean	No	false	When true, validate and return the diff without writing. Default false.

Example call

{
  "tool": "app_edit_file",
  "arguments": {
    "path": "string",
    "old_string": "string",
    "new_string": "string",
    "replace_all": false,
    "dry_run": false
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_exec

Title: Run Shell Command

Run a shell command in the sandbox workspace. Use only for tasks not covered by dedicated tools: sandbox dependency installation/verification, package diagnostics, or package scripts. Do not use for reading files, listing files, searching, or writing files; use app_read_file, app_list_files, app_search, app_edit_file, and app_write_file instead. app_exec does not persist source-file mutations: shell commands that change app source files are rejected and rolled back. Only add dependencies that are compatible with React Router v7 on Cloudflare Workers; avoid Node-only/general-purpose runtime tooling. Commands run in the /workspace directory. Default timeout is 120 seconds; set timeout_seconds for longer operations.

Required permission: app.write

Parameters

Parameter	Type	Required	Default	Description
command	string	Yes	—	Shell command to execute (e.g., 'npm ls', 'ls -la build/')
timeout_seconds	number	No	—	Timeout in seconds (default: 120, max: 600)

Example call

{
  "tool": "app_exec",
  "arguments": {
    "command": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_git_status

Title: Git Integration Status

Check if git integration is enabled and view sync status. Returns repo URL, branch, last synced commit, and sync direction. Read-only — does not modify anything.

Required permission: app.read

Parameters

This tool accepts no arguments.

Example call

{
  "tool": "app_git_status",
  "arguments": {}
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_init

Title: Initialize App Workspace

Optionally call upfront to prefetch the file list and common context files (app/routes.ts, app/root.tsx, package metadata, and .perspect scaffold state). Other app_* tools initialize the workspace automatically on first use — call app_init only when you want this context returned explicitly at the start of a session. NOT required for CMS tools (page_*, product_*, category_*, media_*) — those work independently.

Required permission: app.read

Parameters

This tool accepts no arguments.

Example call

{
  "tool": "app_init",
  "arguments": {}
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_list_files

Title: List App Files

List all files in the app workspace. Returns paths relative to the workspace root. Use to explore the project structure before reading or writing files.

Required permission: app.read

Parameters

Parameter	Type	Required	Default	Description
directory	string	No	—	Subdirectory to list (e.g., 'app/routes'). Defaults to root.

Example call

{
  "tool": "app_list_files",
  "arguments": {}
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_read_file

Title: Read App File

Read the contents of a file in the app workspace. Returns normalized UTF-8 file content, metadata, and a read_token required for safe edits or overwrites of existing files.

Required permission: app.read

Parameters

Parameter	Type	Required	Default	Description
path	string	Yes	—	File path relative to workspace root (e.g., 'app/routes/home.tsx')

Example call

{
  "tool": "app_read_file",
  "arguments": {
    "path": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_scaffold_feature

Title: Scaffold Feature Routes

Generate ready-to-use React Router routes wired to perspectapi-ts-sdk for common features. Supported features: blog, newsletter, page. Also updates app/routes.ts to register generated routes and the Perspect webhook route, and ensures the shared Perspect SDK client/cache wiring files are present (including PERSPECT_CACHE-backed caching support).

Required permission: app.write

Parameters

Parameter	Type	Required	Default	Description
feature	string	Yes	—	Feature to scaffold Allowed: blog, newsletter, page.
overwrite	boolean	No	false	When true, overwrite existing generated route files and managed platform files
allow_rerun	boolean	No	false	When true, allow re-running scaffold after the feature has already been scaffolded. Existing files are still preserved unless overwrite=true.

Example call

{
  "tool": "app_scaffold_feature",
  "arguments": {
    "feature": "blog",
    "overwrite": false,
    "allow_rerun": false
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_search

Title: Search Code

Search across all source files using ripgrep. Fast, regex-capable code search. Returns matching lines with file paths and line numbers. Automatically excludes node_modules, build output, and .react-router directories.

Required permission: app.read

Parameters

Parameter	Type	Required	Default	Description
pattern	string	Yes	—	Search pattern (regex supported, e.g., 'import.*useState', 'TODO|FIXME')
glob	string	No	—	File glob filter (e.g., '.tsx', '.css', 'app/routes/**')
case_sensitive	boolean	No	—	Case-sensitive search (default: false)
max_results	number	No	—	Maximum number of matching lines to return (default: 100)

Example call

{
  "tool": "app_search",
  "arguments": {
    "pattern": "string"
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_typecheck

Title: Typecheck App

Run React Router type generation when available, then TypeScript type-checking using the project's local binaries in the sandbox workspace. Call this once after a coherent set of source changes, before requesting Security Auditor review and Release Manager deployment. Returns errors if any, or confirms the code is clean.

Required permission: app.read

Parameters

This tool accepts no arguments.

Example call

{
  "tool": "app_typecheck",
  "arguments": {}
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_workspace_diff

Title: Workspace Diff

Show changed files and a unified diff between the current workspace and the current R2 source checkpoint. Use this as the source of truth for changed file summaries and release handoffs.

Required permission: app.read

Parameters

Parameter	Type	Required	Default	Description
max_chars	number	No	60000	Maximum diff characters to include. Default: 60000, max: 200000.

Example call

{
  "tool": "app_workspace_diff",
  "arguments": {
    "max_chars": 60000
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

app_write_file

Title: Write App File

Create or replace a complete app source file. Use this for new files or intentional full-file replacement; prefer app_edit_file for targeted changes to existing files. For existing files, pass overwrite=true plus the read_token or metadata.sha256 from app_read_file so stale writes are rejected. The tool rejects notebooks, binary content, symlinks, oversized files, unsupported paths, and unguarded overwrites; it returns a diff after validation.

Required permission: app.write

Parameters

Parameter	Type	Required	Default	Description
path	string	Yes	—	File path relative to workspace root (e.g., 'app/routes/home.tsx')
content	string	Yes	—	Complete final UTF-8 file content.
overwrite	boolean	No	false	Required and must be true when replacing an existing file. Ignored for new files.
read_token	string	No	—	read_token returned by app_read_file for this path. Required for existing files unless expected_sha256 is supplied.
expected_sha256	string	No	—	metadata.sha256 returned by app_read_file. May be used instead of read_token for staleness checking.
dry_run	boolean	No	false	When true, validate and return the diff without writing. Default false.

Example call

{
  "tool": "app_write_file",
  "arguments": {
    "path": "string",
    "content": "string",
    "overwrite": false,
    "dry_run": false
  }
}

Output schema

{
  "type": "object",
  "additionalProperties": true
}

---

This page is generated from the registered MCP tool providers. Do not edit it by hand.