| name | managing-mcp-index |
| description | Builds and maintains templates/index.mcp.json for Comfy Cloud MCP tools. Covers deterministic sync from index.json, AI-generated English descriptions, model registry profiles, template cache, recommend/freshness overrides, and API node scanning. Use when asked to: sync MCP index, index.mcp.json, mcp sync, enhance MCP descriptions, AI template descriptions for MCP, models_registry, template_cache, recommend override, freshness, MCP pipeline, run mcp, mcp:ai, update MCP metadata, regenerate MCP copy, Use Cases MCP descriptions. NOT for site SEO (site/generate-ai) or hub i18n (sync:i18n / managing-translations). Triggers on: mcp index, index.mcp, mcp sync, template cache, models registry, mcp ai, recommend, MCP description. |
Managing MCP Index
What This Is
templates/index.mcp.json is a machine-oriented template index for Comfy Cloud MCP tools. It is separate from:
| System | File(s) | Purpose |
|---|
| MCP index (this skill) | index.mcp.json | English metadata for AI tool routing: description, io, capabilities, recommend |
| Hub manifest | index.json + index.{locale}.json | Human UI + 11-language titles/descriptions → skill: managing-translations |
| Site SEO | site/ AI pipeline | Long-form page copy → skill: regenerating-ai-content |
MCP descriptions are English only. There is no MCP translation step. Multi-language hub copy uses npm run i18n (sync_data.py), not the MCP pipeline.
Quick Commands (npm)
npm run mcp
npm run mcp:check
npm run mcp:ai
npm run mcp:models
npm run i18n
Prerequisites for AI steps: copy .env.example → .env, set AI_API_KEY, AI_BASE_URL, AI_MODEL. Optional: COMFYUI_REPO_PATH for API node dropdown scanning during npm run mcp.
Advanced flags (run Python directly): see scripts/mcp/docs/MCP_AI_ENHANCEMENT.md.
Pipeline Overview
templates/index.json
│
▼ npm run mcp (sync_index.py)
templates/index.mcp.json ◄── merge description/io from template_cache (hash match)
│
├── npm run mcp:models → scripts/data/mcp/models_registry.json
└── npm run mcp:ai → scripts/data/mcp/template_cache.json → merge back to index.mcp.json
| Step | Script | Writes |
|---|
| 1 Sync | scripts/mcp/sync_index.py | index.mcp.json, refreshes api_node_model_options.json |
| 2a Models | scripts/mcp/enhance_models_registry.py | models_registry.json |
| 2b Templates | scripts/mcp/enhance_descriptions.py | template_cache.json + merge → index.mcp.json |
Run 2a before 2b when both are needed. Run sync before AI after adding templates to index.json.
Data Files (scripts/data/mcp/)
| File | Role |
|---|
models_registry.json | Model profiles: summary, strengths, capabilities (AI context for descriptions) |
template_cache.json | Per-template description + io, versioned by source_hash (SHA-256 of templates/{name}.json) |
template_overrides.json | Manual recommend / freshness pins (survives sync) |
api_node_model_options.json | Scanned ComfyUI API node model dropdowns |
Do not mix layers: model copy goes in models_registry.json, template copy in template_cache.json.
Template Cache Versioning
- Each cache entry has
source_hash = hash of workflow JSON.
- Hash match → sync merges cached
description / io into index.mcp.json.
- Hash mismatch or missing entry →
npm run mcp:ai targets that template.
enhance_descriptions.py only updates description; it preserves existing io from cache or MCP entry.
Fields: Who Owns What
| Field | Set by | Notes |
|---|
name, title, task, model, usage | Sync from index.json | |
capabilities, io (default) | Sync | workflow from tags; model_options when single API model node |
freshness | Sync from date | Override via template_overrides.json |
recommend | Sync from usage tiers | Override via template_overrides.json |
description, io (polished) | template_cache.json | AI or manual; hash-gated |
description (AI only) | enhance_descriptions.py | English; references models_registry.json |
recommend tiers (from usage)
| Usage | Label |
|---|
| ≥ 2500 | highly_recommended |
| ≥ 1000 | top |
| ≥ 500 | high |
| ≥ 200 | medium |
| ≥ 50 | low |
| < 50 | not_recommended |
Use Cases category floor: never below low (no not_recommended).
Manual override example (template_overrides.json):
{
"schema_version": 1,
"templates": {
"image_krea2_turbo_t2i": { "recommend": "high" }
}
}
Common Workflows
After adding or editing templates in index.json
npm run mcp:check
npm run mcp
npm run mcp:ai
After editing a workflow JSON (templates/foo.json)
Hash changes → run npm run mcp:ai for that template (or all stale). Optionally:
python3 scripts/mcp/enhance_descriptions.py --template foo
Pin recommend / freshness for a template
Edit scripts/data/mcp/template_overrides.json, then npm run mcp.
Regenerate all MCP descriptions (expensive)
python3 scripts/mcp/enhance_descriptions.py --all
One-time: seed cache from existing MCP copy
python3 scripts/mcp/import_template_cache.py
Sync Exclusions
- Categories skipped: Node Basics, LLM, Getting Started
- Local-only templates:
includeOnDistributions: ["local"] only — not in MCP index
- Multi API model nodes:
model_options omitted (logged to scripts/.output/sync_index.log)
What NOT To Do
- Do not put model profiles in
template_cache.json.
- Do not expect
npm run i18n to update index.mcp.json.
- Do not hand-edit
index.mcp.json description without updating template_cache.json — next sync overwrites unless cache hash matches.
- Do not run
enhance_descriptions.py before enhance_models_registry.py when model context is missing for new models.
After Changes
npm run mcp — refresh structured fields and merge cache.npm run mcp:ai / npm run mcp:models — if AI copy needed.- Commit
index.mcp.json and relevant scripts/data/mcp/*.json files.
- Bump
pyproject.toml version if template assets changed (repo convention).
Reference Docs
- Full spec:
scripts/mcp/docs/MCP_AI_ENHANCEMENT.md
- Script layout:
scripts/mcp/README.md
- Data files:
scripts/data/mcp/README.md
