目录操作服务器

Rastro MCP

用于Rastro目录操作的MCP服务器。公开目录、服务、执行和本地可视化工具，供Claude、Codex或任何兼容MCP的客户端使用。

安装

来自PyPI （一经发布）：

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

来源：

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

所需环境

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

跑

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

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

克劳德代码/克劳德桌面配置

添加 .mcp.json 或 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"
      }
    }
  }
}

工具参考

目录工具

catalog_list

列出已验证组织的所有目录。

catalog_get

按ID获取单个目录，包括元数据和项目计数。

catalog_delete

删除目录（不可逆）。需要明确的确认短语。

catalog_duplicate

复制目录架构，并可选择复制源项。

catalog_schema_get

获取包含字段类型、描述、范围和工作流元数据的目录架构定义。

catalog_taxonomy_get

获取具有层次结构、属性和继承的目录分类。

catalog_update_quality_prompt

设置评判工具和准备检查使用的目录质量提示。完全替换当前提示。

catalog_items_query

使用分页、文本搜索和字段排序查询目录项。

catalog_item_get

按ID获取具有完整数据、实体类型和分类属性的单个目录项。

catalog_item_update

直接更新单个目录项的数据。 默认情况下已禁用 --使用 catalog_activity_create_transform 相反。

启用 RASTRO_MCP_ENABLE_DIRECT_ITEM_UPDATE=true （仅限打碎玻璃）。

catalog_activity_list

使用可选的状态/类型筛选器列出目录的活动。

catalog_activity_get

按ID获取具有完整元数据的单个活动。

catalog_activity_get_staged_changes

获取待处理活动的阶段性更改。返回数据对前后分页的结果。

catalog_visualize_local

为目录或活动的阶段性更改构建一个自包含的本地HTML查看器，然后可以选择在默认浏览器中打开它。

输出a bundle.json，静态 viewer.html，以及本地主机 viewer_url.更喜欢 viewer_url 过度开放 viewer.html 直接；localhost路径为远程图像/文档启用本地媒体代理。当浏览器启动失败时（例如在无头shell中），工件文件仍然可用。

catalog_activity_create_transform

使用分阶段更改、脚本来源和审核元数据创建自定义转换活动。验证捆绑包，将所有更改分阶段到一个待处理的审核活动中（如果需要，在内部分块），并打开仪表板审核URL。

catalog_activity_save_workflow

将活动另存为可重用的工作流模板。

catalog_snapshot_list

列出回滚/历史记录的目录快照。

catalog_snapshot_create

为回滚安全创建手动快照。

catalog_snapshot_restore

将目录还原到特定快照。

维修工具

富集API合同注释

MCP包公开了目录感知帮助程序，但代理仍可能调用 /api/public/enrich 通过客户端或后端。保持这些丰富的形状不同：

• 仅分类： 发送 taxonomy, predict_taxonomy: true, predict_taxonomy_attributes: false，并省略 output_schema 除非您还希望提取普通字段。不要发明虚拟字段，例如 empty.
• 具有属性的分类学： 保持 predict_taxonomy_attributes 省略或 true；结果包括 taxonomy_attributes 分类后。
• 请求的属性： 发送顶级 attribute_sets 并把 attribute_set_id 在每个项目上。输出架构必须请求 attribute_results_json；每行内联 requested_attributes / source_hints 被公众预检拒绝。

service_map_to_catalog_schema

使用AI富集将源项映射到目标目录模式。始终与 web_search=false.

service_judge_catalog_rows

判断目录行的数据质量。当 catalog_id 提供，自动加载目录的模式和quality_prompt（来自readines_config）。

service_image_run

提交图像编辑作业。支持：生成、编辑、输入、bg_remove、重新点亮、升级。

service_image_status

获取图像编辑运行的状态/进度/结果。

service_image_list

使用可选过滤器运行列表图像编辑。

执行工具（在本地运行）

execution_catalog_snapshot_pull

将目录行+模式导出到本地文件（拼花/csv）以进行Python转换。使用快速并行分页。

快照拉取也会写入 catalog_<id>_manifest.json 使用确定性行/模式哈希。重用缓存将跳过API拉取并返回 cache_hit=true；通行证 refresh=true 在最终阶段之前，当你需要一个新的来源时。

execution_local_diff_compute

计算本地数据集前后的行/字段差异。输出 staged_changes.jsonl.

execution_bundle_validate

在创建活动之前验证转换包。检查文件是否存在、架构兼容性、行数、产品变体完整性和策略规则。

execution_catalog_stage_dataset

一个命令暂存：计算前后数据集的差异，验证捆绑包（包括产品变体完整性），并创建一个待处理的审查活动。

提示

master_prompt

单一统一提示，指导代理商完成目录操作、产品变体处理、安全规则和关键字段匹配。加载自 rastro_mcp/prompts/master_prompt.md.

典型工作流程

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

大目录行为

• execution_catalog_snapshot_pull 更喜欢原始目录行(product + variant)via /raw-items，然后回到传统 /items.
• catalog_activity_create_transform 将大型变更集分阶段进行 活动 通过块附加阶段性更改，然后最终确定为 pending_review.
• execution_catalog_stage_dataset 在一个命令中计算diff+阶段，将所有内容放入一个待处理的审查活动中。

安全默认值

• catalog_item_update 残疾的 --后端PUT替换完整的项目数据。以（权力）否决 RASTRO_MCP_ENABLE_DIRECT_ITEM_UPDATE=true
• 程序化批准/应用已禁用 --仅从仪表板查看和应用。
• 活动优先工作流 --所有的写作都要经过审阅。
• 捆绑验证 --自动模式、行计数和产品变体完整性检查。
• 路径安全 --执行工具验证路径以防止目录遍历。

配置