Rastro MCP

MCP server for Rastro catalog operations. Exposes catalog, service, execution, and local visualization tools for use with Claude, Codex, or any MCP-compatible client.

Install

From PyPI (once published):

pip install rastro.ai
# or
uv add rastro.ai

From source:

git clone https://github.com/Rastro-AI/rastro-mcp
cd rastro-mcp
uv sync

Required Environment

export RASTRO_AUTH_TOKEN=<bearer-token>                # Preferred: user token or API key
# export RASTRO_USER_TOKEN=<user-jwt>                  # Equivalent user-token alias
# export RASTRO_API_KEY=rastro_pk_...                  # API-key alias
export RASTRO_BASE_URL=https://catalogapi.rastro.ai/api  # Production (default)
# export RASTRO_BASE_URL=http://127.0.0.1:8000/api       # Local dev
# export RASTRO_ORGANIZATION_ID=<uuid>                    # Recommended for user tokens; picks the target org

Run

# stdio transport (for MCP clients)
uv run python -m rastro_mcp.server

# or via CLI entry point (if installed from package)
rastro-mcp

Claude Code / Claude Desktop config

Add to .mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "rastro": {
      "command": "uv",
      "args": ["run", "python", "-m", "rastro_mcp.server"],
      "env": {
        "RASTRO_AUTH_TOKEN": "<bearer-token>",
        "RASTRO_ORGANIZATION_ID": "<org-uuid>",
        "RASTRO_BASE_URL": "https://catalogapi.rastro.ai/api"
      }
    }
  }
}

Tool Reference

Catalog Tools

#### catalog_list List all catalogs for the authenticated organization.

#### catalog_get Get a single catalog by ID, including metadata and item counts.

#### catalog_delete Delete a catalog (irreversible). Requires explicit confirmation phrase.

#### catalog_duplicate Duplicate a catalog schema and optionally copy source items.

#### catalog_schema_get Get catalog schema definition with field types, descriptions, scopes, and workflow metadata.

#### catalog_taxonomy_get Get catalog taxonomy with hierarchy, attributes, and inheritance.

#### catalog_update_quality_prompt Set the catalog's quality prompt used by the judge tool and readiness checks. Replaces the current prompt entirely.

#### catalog_items_query Query catalog items with pagination, text search, and field sorting.

#### catalog_item_get Get a single catalog item by ID with full data, entity type, and taxonomy attributes.

#### catalog_item_update Update a single catalog item's data directly. Disabled by default -- use catalog_activity_create_transform instead.

Enable with RASTRO_MCP_ENABLE_DIRECT_ITEM_UPDATE=true (break-glass only).

#### catalog_activity_list List activities for a catalog with optional status/type filters.

#### catalog_activity_get Get a single activity by ID with full metadata.

#### catalog_activity_get_staged_changes Get staged changes for a pending activity. Returns paginated before/after data pairs.

#### catalog_visualize_local Build a self-contained local HTML viewer for either a catalog or an activity's staged changes, then optionally open it in the default browser.

Outputs a bundle.json, a static viewer.html, and a localhost viewer_url. Prefer the viewer_url over opening viewer.html directly; the localhost path enables the local media proxy for remote images/documents. The artifact files are still usable when browser launch fails (for example in headless shells).

#### catalog_activity_create_transform Create a custom transform activity with staged changes, script provenance, and audit metadata. Validates the bundle, stages all changes into a single pending-review activity (chunked internally if needed), and opens the dashboard review URL.

#### catalog_activity_save_workflow Save an activity as a reusable workflow template.

#### catalog_snapshot_list List catalog snapshots for rollback/history.

#### catalog_snapshot_create Create a manual snapshot for rollback safety.

#### catalog_snapshot_restore Restore a catalog to a specific snapshot.

Service Tools

#### Enrichment API contract notes

The MCP package exposes catalog-aware helpers, but agents may still call /api/public/enrich through the client or backend. Keep these enrich shapes distinct:

• Taxonomy classification only: send taxonomy, predict_taxonomy: true, predict_taxonomy_attributes: false, and omit output_schema unless you also want normal fields extracted. Do not invent dummy fields such as empty.
• Taxonomy with attributes: keep predict_taxonomy_attributes omitted or true; results include taxonomy_attributes after classification.
• Requested attributes: send top-level attribute_sets and put attribute_set_id on each item. The output schema must request attribute_results_json; inline per-row requested_attributes / source_hints are rejected by public preflight.

#### service_map_to_catalog_schema Map source items to a target catalog schema using AI enrichment. Always runs with web_search=false.

#### service_judge_catalog_rows Judge catalog rows for data quality. When catalog_id is provided, automatically loads the catalog's schema and quality_prompt (from readiness_config).

#### service_image_run Submit an image editing job. Supports: generate, edit, inpaint, bg_remove, relight, upscale.

#### service_image_status Get status/progress/result of an image editing run.

#### service_image_list List image editing runs with optional filters.

Execution Tools (run locally)

#### execution_catalog_snapshot_pull Export catalog rows + schema to local files (parquet/csv) for Python transforms. Uses fast parallel pagination.

Snapshot pulls also write catalog_<id>_manifest.json with deterministic row/schema hashes. Reusing the cache skips the API pull and returns cache_hit=true; pass refresh=true before final staging when you need a fresh source.

#### execution_local_diff_compute Compute row/field diff between before/after local datasets. Outputs staged_changes.jsonl.

#### execution_bundle_validate Validate a transform bundle before activity creation. Checks file existence, schema compatibility, row counts, product-variant integrity, and policy rules.

#### execution_catalog_stage_dataset One-command staging: compute diff from before/after datasets, validate bundle (including product-variant integrity), and create one pending-review activity.

Prompts

#### master_prompt Single unified prompt guiding the agent through catalog operations, product-variant handling, safety rules, and key field matching. Loaded from rastro_mcp/prompts/master_prompt.md.

Typical Workflow

1. catalog_get / catalog_schema_get      -- understand the catalog
2. catalog_visualize_local               -- inspect catalog state or staged changes visually when useful
3. execution_catalog_snapshot_pull       -- pull data to local parquet
4. (your Python transform script)        -- modify the data
5. execution_catalog_stage_dataset       -- diff + validate + stage
6. Review in dashboard                   -- approve and apply

Large Catalog Behavior

• execution_catalog_snapshot_pull prefers raw catalog rows (product + variant) via /raw-items, then falls back to legacy /items.
• catalog_activity_create_transform stages large change sets into one activity by chunk-appending staged changes, then finalizes to pending_review.
• execution_catalog_stage_dataset computes diff + stages everything into one pending-review activity in a single command.

Safety Defaults

• `catalog_item_update` disabled -- backend PUT replaces full item data. Override: RASTRO_MCP_ENABLE_DIRECT_ITEM_UPDATE=true
• Programmatic approve/apply disabled -- review and apply from dashboard only.
• Activity-first workflow -- all writes go through staging for review.
• Bundle validation -- automatic schema, row count, and product-variant integrity checks.
• Path safety -- execution tools validate paths to prevent directory traversal.

Configuration