feat: add index.mcp.json - MCP-readable template index with descriptions#932
feat: add index.mcp.json - MCP-readable template index with descriptions#932lin-bot23 wants to merge 22 commits into
Conversation
…ons and IO metadata Generates AI-friendly descriptions for all 526 templates (271 API + 255 Cloud), with refined input/output type specifications for MCP tool integration. - Adds templates/index.mcp.json replacing templates/templates-context.json - Each template now has: description, io.inputs, io.outputs - Cloud templates: end with 'This workflow runs on Comfy Cloud and executes quickly.' - API templates: end with 'This workflow calls a third-party API.' - 361 templates via AI-assisted batch generation - 165 templates via programmatic generation with model-specific knowledge
🔤 Spellcheck Results
|
…ex.json Aligns the MCP index structure with the original index.json: - 9 groups: Use Cases, Image, Video, Audio, 3D Model, LLM, Utility, Getting Started, Node Basics - Each group has moduleName, category, icon, title, type - Templates nested within their group
Automatically detects new/removed templates from index.json and updates index.mcp.json accordingly. Existing descriptions are preserved.
lin-bot23
force-pushed
the
feat/index-mcp-json
branch
from
fbaf53a to
20b0935
Compare
- New models_capabilities.json mapping ~47 major models to capability tags (e.g. text-to-image, t2v, lip-sync, controlnet) - sync-mcp-index.py: inject capabilities into index.mcp.json via resolve_model() lookup when syncing - index.mcp.json: 358/526 templates now have capabilities array
|
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughA new Python script ChangesMCP Index Sync Tooling
🚥 Pre-merge checks | ✅ 2✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
lin-bot23
force-pushed
the
feat/index-mcp-json
branch
from
bff1b13 to
cd665b1
Compare
- Expanded model coverage with detailed summaries and capabilities - Covers image generation, video generation, image enhancement, and video enhancement models - All entries include structured summary and capabilities arrays
sync_bundles.py requires all JSON files under templates/ to be assigned in bundles.json. These are index data files, not workflow templates — added to media-other bundle per validation requirement.
lin-bot23
force-pushed
the
feat/index-mcp-json
branch
from
cd665b1 to
c10c2e4
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@bundles.json`:
- Line 493: The bundle identifier "templates-context" in bundles.json at line
493 does not resolve to any existing template/manifest entry, causing the
validation pipeline to fail. Either replace "templates-context" with a correct
existing bundle identifier that matches an actual template/manifest entry, or
remove the "templates-context" entry entirely from the bundles.json file until
the corresponding manifest side is added and the identifier becomes valid.
In `@scripts/sync-mcp-index.py`:
- Line 21: The script has two Ruff linter violations that need to be fixed. On
line 21, the comma-separated import statement violates the E-rule for import
style; split the single import line with multiple modules (json, os, sys, time)
into separate import statements with one module per line. On line 307, there is
an unused local variable named name_l that violates the F-rule; remove this
unused variable assignment to eliminate the violation.
- Around line 33-37: The try-except block around the MODELS_CAP file loading is
catching all exceptions indiscriminately and defaulting to an empty dictionary,
which hides actual errors like malformed JSON or configuration issues. Replace
the broad `except Exception:` clause with a specific `except FileNotFoundError:`
to only catch and handle the case where the MODELS_CAP_FILE is missing, allowing
json.JSONDecodeError and other parsing errors to propagate and surface the
actual root cause during execution.
- Around line 386-387: The operator precedence in the model_info assignment at
line 386-387 is incorrect. The current expression is parsed as
`(MODELS_CAP.get(model) or MODELS_CAP.get(models[0])) if models else None`,
which means the entire assignment evaluates to None whenever models is empty,
losing any valid model_info from MODELS_CAP.get(model). Fix this by adding
parentheses to explicitly group the fallback logic: wrap the conditional
`MODELS_CAP.get(models[0]) if models else None` in parentheses so it becomes the
second operand of the or operator. This ensures that if models is empty, the
expression still returns the result from MODELS_CAP.get(model) if it exists.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 5621dc83-0284-49f0-9e62-5657076d0af2
📒 Files selected for processing (4)
bundles.jsonscripts/models_capabilities.jsonscripts/sync-mcp-index.pytemplates/index.mcp.json
- Remove 89 models not referenced in index.mcp.json - Add 69 models that are in index.mcp but were missing - Include pricing info (credits, time, quality rating, category) for 53 models - Fix \x08 backspace character in 'Depth Anything v2' model name - Total: 122 models = 120 unique models from index.mcp
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
scripts/models_capabilities.json (1)
262-277:⚠️ Potential issue | 🟠 MajorEliminate case-variant model key collisions and add missing pricing category.
Two fixable issues in the models registry:
Case-variant duplicate keys (
Kling O1/Kling o1,Kling O3/Kling o3):resolve_model()performs case-insensitive substring matching as a fallback when templates lack explicit models. If two keys collide on case-insensitive lookup, the tie-breaker is non-deterministic. Currently templates use correct casing and avoid collision, but this is a latent trap—same name, different hat is metadata mischief waiting to happen. Consolidate to a single canonical casing (suggest uppercaseO1/O3to match current template references).SeedVR2 missing
pricing.category: This is the only model in the registry without a category field. All other 52 models include it. Add"category"to SeedVR2's pricing object to match schema and align with PR objectives.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/models_capabilities.json` around lines 262 - 277, In the models registry, address two issues: first, consolidate case-variant model keys that cause non-deterministic matching in resolve_model() by finding all occurrences of Kling O1/Kling o1 and Kling O3/Kling o3, then retain only the uppercase canonical versions (Kling O1 and Kling O3) and remove the lowercase variants; second, locate the SeedVR2 model entry in the registry and add the missing "category" field to its pricing object to match the schema used by all other 52 models in the registry (specify an appropriate category value consistent with similar models).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/models_capabilities.json`:
- Around line 660-664: Add a missing `category` field to the SeedVR2.pricing
object in scripts/models_capabilities.json to maintain schema consistency with
the other 52 models that include pricing. The pricing object for SeedVR2
currently contains credits, estimated_seconds, and quality_rating fields, but
lacks the category field that all other pricing entries include (such as
"quality" or "legacy"). Add this field to the pricing object to match the
expected pricing schema.
---
Outside diff comments:
In `@scripts/models_capabilities.json`:
- Around line 262-277: In the models registry, address two issues: first,
consolidate case-variant model keys that cause non-deterministic matching in
resolve_model() by finding all occurrences of Kling O1/Kling o1 and Kling
O3/Kling o3, then retain only the uppercase canonical versions (Kling O1 and
Kling O3) and remove the lowercase variants; second, locate the SeedVR2 model
entry in the registry and add the missing "category" field to its pricing object
to match the schema used by all other 52 models in the registry (specify an
appropriate category value consistent with similar models).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 9988daba-2b43-4995-b7a2-20eaabe1d5b4
📒 Files selected for processing (2)
scripts/models_capabilities.jsontemplates/index.mcp.json
templates-context.json was an untracked file artifact, not tracked in git. Removed the bundle assignment and deleted the file to fix CI.
…ls_capabilities - Split comma-separated import into individual lines (Ruff E-rule) - Remove unused name_l variable at line 307 (Ruff F-rule) - Refine MODELS_CAP loading: only catch FileNotFoundError, fail on malformed JSON - Fix operator precedence in model_info lookup (capabilities dropping bug) - Add missing category field to SeedVR2.pricing
validate_templates.py scans all index*.json files against index.schema.json, but index.mcp.json has a different structure (MCP-specific format). Excluding it from the scan fixes the schema validation failure in CI.
There was a problem hiding this comment.
♻️ Duplicate comments (1)
scripts/sync-mcp-index.py (1)
21-24:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRemove unused imports to satisfy Ruff F-rules.
Line 22 (
os) and Line 24 (time) are imported but unused; tiny lint, tidy win — less clutter, less flutter.As per coding guidelines,
**/*.py: “Use Ruff linter with line-length 100 and target Python 3.12, selecting rules E and F for Python files.”💡 Suggested fix
import json -import os import sys -import time from pathlib import Path from typing import Any, Optional🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/sync-mcp-index.py` around lines 21 - 24, Remove the unused imports os and time from the import section at the top of the file. Keep only the imports that are actually used in the script (json and sys). This will satisfy Ruff's F-rules which flag unused imports and variables.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@scripts/sync-mcp-index.py`:
- Around line 21-24: Remove the unused imports os and time from the import
section at the top of the file. Keep only the imports that are actually used in
the script (json and sys). This will satisfy Ruff's F-rules which flag unused
imports and variables.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: ffe81575-a93f-4ca8-97da-2c0868dfb128
📒 Files selected for processing (3)
bundles.jsonscripts/models_capabilities.jsonscripts/sync-mcp-index.py
All 122 models had stale capabilities tags (e.g. text-to-image, photorealism, controlnet) that were unused and derived from a previous data extraction source. Cleared them.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
scripts/models_capabilities.json (1)
4-686:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftCapabilities registry is effectively disabled by empty arrays.
Line 4 and the same pattern across this file set
capabilitiesto[]for model entries, butscripts/sync-mcp-index.pyonly propagates capabilities when the array is non-empty. Net effect: generated MCP metadata cannot be refreshed from this registry for those models, and new entries may miss capability tags. Empty tags, empty brag—metadata takes the lag.Please either (a) repopulate non-empty capability arrays for models meant to drive MCP output, or (b) update sync logic to intentionally handle this “no capabilities” mode without silently dropping enrichment.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/models_capabilities.json` around lines 4 - 686, The capabilities registry in models_capabilities.json has empty arrays for all model entries, which prevents the sync-mcp-index.py script from propagating capability metadata since it only processes non-empty capability arrays. To fix this, either populate the empty capabilities arrays with actual capability tags for each model that should be reflected in MCP output (such as "text-to-image", "video-generation", "editing", etc.), or update the capability propagation logic in scripts/sync-mcp-index.py to explicitly handle and preserve models with empty capability arrays instead of silently skipping them during metadata enrichment. Choose the approach based on whether these models should have defined capabilities or if empty capabilities is an intentional state that should still be reflected in the generated MCP metadata.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@scripts/validate_templates.py`:
- Around line 613-617: The exclusion of index.mcp.json from index-schema
validation at line 616 leaves that file completely unchecked despite it being
shipped in bundles.json, creating a release gap. Keep the exclusion from the
schema validation but add a dedicated validation check in a separate branch that
validates templates/index.mcp.json with minimum checks: verify the file exists,
verify the JSON parses successfully, and verify the top-level structure matches
expected format. This ensures index.mcp.json receives baseline validation
coverage even though it is excluded from the schema validation loop.
---
Outside diff comments:
In `@scripts/models_capabilities.json`:
- Around line 4-686: The capabilities registry in models_capabilities.json has
empty arrays for all model entries, which prevents the sync-mcp-index.py script
from propagating capability metadata since it only processes non-empty
capability arrays. To fix this, either populate the empty capabilities arrays
with actual capability tags for each model that should be reflected in MCP
output (such as "text-to-image", "video-generation", "editing", etc.), or update
the capability propagation logic in scripts/sync-mcp-index.py to explicitly
handle and preserve models with empty capability arrays instead of silently
skipping them during metadata enrichment. Choose the approach based on whether
these models should have defined capabilities or if empty capabilities is an
intentional state that should still be reflected in the generated MCP metadata.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 0169d064-046e-4c01-84aa-22efb0daa646
📒 Files selected for processing (3)
scripts/models_capabilities.jsonscripts/validate_templates.pytemplates/index.mcp.json
| # Find all index*.json files (excluding schema and logo index) | ||
| index_files = [] | ||
| for file_path in templates_dir.glob('index*.json'): | ||
| if file_path.name not in ('index.schema.json', 'index_logo.json'): | ||
| if file_path.name not in ('index.schema.json', 'index_logo.json', 'index.mcp.json'): | ||
| index_files.append(file_path) |
There was a problem hiding this comment.
Exclusion removes all CI validation coverage for a shipped bundle artifact.
At Line 616, index.mcp.json is excluded from index-schema validation, which is fine for schema mismatch—but this script now provides no fallback validation for that file while bundles.json ships index.mcp. That creates a release gap where malformed templates/index.mcp.json can pass CI unnoticed.
Add a dedicated check for templates/index.mcp.json (at minimum: file exists, JSON parses, and top-level structure is expected) in a separate validation branch.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/validate_templates.py` around lines 613 - 617, The exclusion of
index.mcp.json from index-schema validation at line 616 leaves that file
completely unchecked despite it being shipped in bundles.json, creating a
release gap. Keep the exclusion from the schema validation but add a dedicated
validation check in a separate branch that validates templates/index.mcp.json
with minimum checks: verify the file exists, verify the JSON parses
successfully, and verify the top-level structure matches expected format. This
ensures index.mcp.json receives baseline validation coverage even though it is
excluded from the schema validation loop.
…nd add default descriptions - Added functionality to skip specific instructional categories: Node Basics, LLM, and Getting Started during MCP index export. - Introduced default English descriptions for various included MCP categories to improve clarity and usability.
…ex.mcp.json categories - Added a mapping from index.json group `title` to index.mcp.json `category` using INDEX_GROUP_TO_MCP_CATEGORY. - Updated the sync logic to ignore the `category` field in index.json and handle unmapped group titles with warnings. - Improved clarity in the output by reporting skipped unmapped titles during the sync process.
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
scripts/sync-mcp-index.py (3)
215-216: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winNarrow exception handling for better diagnostics.
The broad
except Exception:clause hides parse errors and unexpected data structures in workflow files. While failing gracefully here is appropriate (the sync continues with fallback inference), catching specific exceptions would surface template file issues during development.♻️ Proposed refinement
- except Exception: + except (json.JSONDecodeError, KeyError, TypeError) as exc: + # Workflow file missing, malformed, or unexpected structure; fall back to inference return []When exceptions are caught with precision and care, debugging becomes easier—a breath of fresh air!
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/sync-mcp-index.py` around lines 215 - 216, The bare `except Exception:` clause at lines 215-216 is too broad and masks parsing errors and unexpected data structures that would be useful for debugging workflow files during development. Replace this broad exception handler with specific exception catches (such as those related to JSON/YAML parsing, KeyError, TypeError, or AttributeError) that are actually expected from malformed or unexpected workflow data, keeping the graceful fallback of returning an empty list only for the anticipated failure modes while allowing other unexpected exceptions to surface for investigation.
212-212:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd explicit UTF-8 encoding for cross-platform file compatibility — a byte of prevention!
Several file operations omit the
encodingparameter, relying on Python's platform-dependent default. On Windows, this can triggerUnicodeDecodeErrorwhen reading JSON files with non-ASCII characters or produce incorrectly encoded output. Since JSON is UTF-8 by convention, specifyencoding="utf-8"explicitly.🔧 Proposed fix
- with open(wf_path) as f: + with open(wf_path, encoding="utf-8") as f:- with open(INDEX_FILE) as f: + with open(INDEX_FILE, encoding="utf-8") as f:- with open(OUTPUT_FILE) as f: + with open(OUTPUT_FILE, encoding="utf-8") as f:- with open(OUTPUT_FILE, "w") as f: + with open(OUTPUT_FILE, "w", encoding="utf-8") as f:As per coding guidelines, scripts must be cross-platform compatible; explicit encoding prevents locale-dependent failures.
Also applies to: 400-401, 406-407, 534-535
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/sync-mcp-index.py` at line 212, Add explicit UTF-8 encoding to all file open operations in the script to ensure cross-platform compatibility. At line 212 where `with open(wf_path) as f:` appears, add `encoding="utf-8"` as a parameter. Similarly, apply the same fix to all other file open operations throughout the script (specifically at lines 400-401, 406-407, and 534-535 as mentioned). This ensures JSON files and other text files are read and written with UTF-8 encoding consistently across all platforms, preventing UnicodeDecodeError on Windows systems.Source: Coding guidelines
464-464:⚠️ Potential issue | 🟡 MinorRemove the redundant substring check on stringified tags.
The condition
"API" in str(tpl.get("tags", ""))is unnecessary and unconventional. Data shows only the exact"API"tag exists—no variants like "API_ENDPOINT"—so the first check"API" in tagsalready covers all cases. The second check stringifies the list and performs substring matching (which would be a bug waiting to happen if such variants existed), but it's redundant when exact element matching suffices.Simplify to just
is_api = "API" in tagsand remove the convoluted fallback. No need to tag-along the extra condition—it's not adding up to better code.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@scripts/sync-mcp-index.py` at line 464, The is_api assignment contains a redundant condition that stringifies the tags list and performs substring matching with "API" in str(tpl.get("tags", "")). Since exact element matching with "API" in tags already covers all existing cases, remove the entire fallback condition (the or clause with the stringification and the openSource check). Simplify the line to just is_api = "API" in tags to use exact element matching only, making the code more conventional and removing the unnecessary substring check.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@scripts/sync-mcp-index.py`:
- Around line 215-216: The bare `except Exception:` clause at lines 215-216 is
too broad and masks parsing errors and unexpected data structures that would be
useful for debugging workflow files during development. Replace this broad
exception handler with specific exception catches (such as those related to
JSON/YAML parsing, KeyError, TypeError, or AttributeError) that are actually
expected from malformed or unexpected workflow data, keeping the graceful
fallback of returning an empty list only for the anticipated failure modes while
allowing other unexpected exceptions to surface for investigation.
- Line 212: Add explicit UTF-8 encoding to all file open operations in the
script to ensure cross-platform compatibility. At line 212 where `with
open(wf_path) as f:` appears, add `encoding="utf-8"` as a parameter. Similarly,
apply the same fix to all other file open operations throughout the script
(specifically at lines 400-401, 406-407, and 534-535 as mentioned). This ensures
JSON files and other text files are read and written with UTF-8 encoding
consistently across all platforms, preventing UnicodeDecodeError on Windows
systems.
- Line 464: The is_api assignment contains a redundant condition that
stringifies the tags list and performs substring matching with "API" in
str(tpl.get("tags", "")). Since exact element matching with "API" in tags
already covers all existing cases, remove the entire fallback condition (the or
clause with the stringification and the openSource check). Simplify the line to
just is_api = "API" in tags to use exact element matching only, making the code
more conventional and removing the unnecessary substring check.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 6f137ba0-44d2-45ee-87e5-2c34ca1fd8c5
📒 Files selected for processing (2)
scripts/sync-mcp-index.pytemplates/index.mcp.json
3 participants
Summary
Adds
templates/index.mcp.json— a machine-readable index of all 526 workflow templates enriched with descriptions and input/output metadata for MCP (Model Context Protocol) integration.This is generated from the existing
templates/templates-context.jsonskeleton, with AI-friendly descriptions and refined IO types added for every template.Changes
templates/index.mcp.json(526 templates, each with name, title, category, task, description, io.inputs, io.outputs)templates/templates-context.json(replaced byindex.mcp.json)What each template entry contains
{ "name": "template_xyz", "title": "Template Title", "category": "image", "task": "text-to-image", "model": "...", "tags": ["cloud", "flux"], "description": "AI-friendly English description of what the workflow does...", "io": { "inputs": [{"type": "image|text|video", "count": 1, "purpose": "..."}], "outputs": [{"type": "image|video|audio|model", "count": 1, "purpose": "..."}] }, "freshness": "...", "usage": 42, "recommend": 60 }Generation approach
Verification