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.

Parameter	Type	Default	Description
limit	integer	50	Max results to return
offset	integer	0	Pagination offset

catalog_get

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID

catalog_delete

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
confirm	boolean	no	Must be true to execute
confirmation	string	no	Must exactly match DELETE <catalog_id>
expected_name	string	no	Safety check: must match catalog name

catalog_duplicate

Duplicate a catalog schema and optionally copy source items.

Parameter	Type	Required	Description
catalog_id	string	yes	Source catalog UUID
name	string	no	Name for the new catalog
description	string	no	Description for the new catalog
include_items	boolean	no	Copy items (default: false)

catalog_schema_get

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
version	string	no	Schema version (default: current)

catalog_taxonomy_get

Get catalog taxonomy with hierarchy, attributes, and inheritance.

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID

catalog_update_quality_prompt

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
prompt	string	yes	Quality prompt text (criteria for judging rows)

catalog_items_query

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
limit	integer	no	Max results (default: 50)
offset	integer	no	Pagination offset (default: 0)
search	string	no	Full-text search query
sort_field	string	no	Field to sort by
sort_order	string	no	asc or desc (default: asc)

catalog_item_get

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
item_id	string	yes	Item UUID (database ID)

catalog_item_update

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
item_id	string	yes	Item UUID
data	object	yes	Key-value pairs to update

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.

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
status	string	no	Filter: pending_review, completed, etc.
activity_type	string	no	Filter: custom_transform, etc.
limit	integer	no	Max results (default: 20)
offset	integer	no	Pagination offset (default: 0)

catalog_activity_get

Get a single activity by ID with full metadata.

Parameter	Type	Required	Description
activity_id	string	yes	Activity UUID

catalog_activity_get_staged_changes

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

Parameter	Type	Required	Description
activity_id	string	yes	Activity UUID
limit	integer	no	Max results per page (default: 50)
offset	integer	no	Pagination offset (default: 0)

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.

Parameter	Type	Required	Description
catalog_id	string	conditional	Catalog UUID to visualize
activity_id	string	conditional	Activity UUID to visualize
mode	string	no	auto, catalog, or activity (default: auto)
title	string	no	Custom title shown in the viewer
limit	integer	no	Max matching records to load (default: 500)
offset	integer	no	Offset into the matching records (default: 0)
search	string	no	Optional search filter passed to the backend
output_dir	string	no	Artifact output directory (default: ./work/visualizations)
open_browser	boolean	no	Best-effort browser open after artifact generation (default: true)

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.

Parameter	Type	Required	Description
catalog_id	string	yes	Target catalog UUID
activity_message	string	yes	Human-readable description
script	object	no	{filename, content, sha256} for audit
diff_summary	object	no	From execution_local_diff_compute
validation_report	object	no	From execution_bundle_validate
staged_changes_inline	array	no	Inline staged changes
staged_changes_file_path	string	no	Path to .jsonl/.json/.parquet file
schema_changes	object	no	Schema changes to apply
taxonomy_changes	object	no	Taxonomy changes to apply
attachments	array	no	Stored in activity_context.attachments
activity_context	object	no	Additional audit context
base_snapshot_id	string	no	Snapshot ID for audit trail
auto_open_review	boolean	no	Open dashboard URL (default: true)

catalog_activity_save_workflow

Save an activity as a reusable workflow template.

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
activity_id	string	yes	Activity UUID
workflow_name	string	yes	Name for the saved workflow
workflow_description	string	no	Description
python_code	string	no	Transform code
attachments	array	no	Attachment metadata
timeout_seconds	integer	no	Execution timeout (default: 120)

catalog_snapshot_list

List catalog snapshots for rollback/history.

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
snapshot_type	string	no	Filter by type
limit	integer	no	Max results (default: 20)
offset	integer	no	Pagination offset (default: 0)

catalog_snapshot_create

Create a manual snapshot for rollback safety.

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
reason	string	no	Reason (default: "Manual snapshot from MCP")

catalog_snapshot_restore

Restore a catalog to a specific snapshot.

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
snapshot_id	string	yes	Snapshot UUID to restore

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.

Parameter	Type	Required	Description
catalog_id	string	yes	Target catalog UUID
items	array	yes	Source items to map
prompt	string	no	Mapping instructions (default: "Map source fields to target catalog schema")
async_mode	boolean	no	Run asynchronously (default: false)
speed	string	no	fast, medium, or slow (default: medium)

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).

Parameter	Type	Required	Description
rows	array	yes	Rows to evaluate (max 500)
catalog_id	string	no	Catalog UUID (loads schema + quality_prompt automatically)
schema	object	no	Inline schema (only needed if no catalog_id)
prompt	string	no	Extra instructions (appended to catalog's quality_prompt)
model	string	no	Model preset (default: fast)
max_rows	integer	no	Max rows per request (default: 200)

service_image_run

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

Parameter	Type	Required	Description
tool	string	yes	generate, edit, inpaint, bg_remove, relight, upscale
image_url	string	conditional	Input image (required for edit/inpaint/bg_remove/relight/upscale)
mask_url	string	conditional	Mask image (required for inpaint)
prompt	string	conditional	Text prompt (required for generate/edit/inpaint)
provider	string	no	Model provider override
quality	string	no	high or low
size	string	no	Output size
num_options	integer	no	Number of results (default: 1)
catalog_id	string	no	Catalog ID for tracking
item_id	string	no	Item ID for tracking

service_image_status

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

Parameter	Type	Required	Description
run_id	string	yes	Run UUID

service_image_list

List image editing runs with optional filters.

Parameter	Type	Required	Description
catalog_id	string	no	Filter by catalog
item_id	string	no	Filter by item
status	string	no	Filter by status
tool	string	no	Filter by tool type
limit	integer	no	Max results (default: 20)
offset	integer	no	Pagination offset (default: 0)

Execution Tools (run locally)

execution_catalog_snapshot_pull

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID
output_dir	string	no	Output directory (default: ./work/snapshots)
format	string	no	parquet or csv (default: parquet)
sample_size	integer	no	Limit rows for sampling (null = all)
page_size	integer	no	Rows per page (default: 400)
max_concurrency	integer	no	Parallel fetch threads (default: 8)
prefer_raw	boolean	no	Use /raw-items for full fidelity (default: true)
use_cache	boolean	no	Reuse a local manifest-backed snapshot when available (default: true)
refresh	boolean	no	Force a live pull and update the local snapshot cache (default: false)

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.

Parameter	Type	Required	Description
before_path	string	yes	Path to before dataset (parquet/csv)
after_path	string	yes	Path to after dataset (parquet/csv)
key_field	string	no	Row matching column (default: __catalog_item_id). Null-key rows = new inserts. Use a business key (e.g. SKU) to match by that field.

execution_bundle_validate

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

Parameter	Type	Required	Description
catalog_id	string	yes	Catalog UUID for schema validation
before_path	string	no	Before dataset path
after_path	string	no	After dataset path
script_path	string	no	Transform script path
staged_changes_path	string	no	Staged changes file path
diff_summary	object	no	Diff summary from execution_local_diff_compute
schema_changes	object	no	Proposed schema changes
taxonomy_changes	object	no	Proposed taxonomy changes
rules.allow_row_deletes	boolean	no	Allow row deletions (default: false)
rules.max_change_ratio_warning	number	no	Warn above this change ratio (default: 0.2)

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.

Parameter	Type	Required	Description
catalog_id	string	yes	Target catalog UUID
before_path	string	yes	Before dataset path (parquet/csv)
after_path	string	yes	After dataset path (parquet/csv)
activity_message	string	yes	Human-readable review message
key_field	string	no	Row matching column (default: __catalog_item_id)
script_path	string	no	Python script path for audit provenance
schema_changes	object	no	Schema changes to apply
taxonomy_changes	object	no	Taxonomy changes to apply
attachments	array	no	Attachment metadata
activity_context	object	no	Additional audit context
base_snapshot_id	string	no	Optional source snapshot ID for audit trail
validate_only	boolean	no	Compute diff and validate without creating an activity
auto_open_review	boolean	no	Open dashboard URL (default: true)

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

Variable	Default	Description
RASTRO_AUTH_TOKEN	optional	Preferred bearer token env var. Supports user JWTs and API keys.
RASTRO_USER_TOKEN	optional	User JWT alias for RASTRO_AUTH_TOKEN.
RASTRO_API_KEY	optional	API key alias for RASTRO_AUTH_TOKEN.
RASTRO_BASE_URL	https://catalogapi.rastro.ai/api	API base URL
RASTRO_ORGANIZATION_ID	optional	Organization UUID override. Recommended when using a user token.
RASTRO_MCP_ENABLE_DIRECT_ITEM_UPDATE	false	Enable direct item PUT
RASTRO_MCP_STAGE_BATCH_SIZE	2000	Chunk size for staging large activities
RASTRO_MCP_STAGE_RETRIES	3	Retry count for staging chunks