Add generated ARD catalog compatibility - #17
Conversation
There was a problem hiding this comment.
Pull request overview
Generates an ARD ingestion artifact from canonical catalog entries and verifies freshness in CI.
Changes:
- Adds deterministic catalog generation and validation.
- Documents regeneration steps.
- Adds pull-request freshness checks.
Show a summary per file
| File | Description |
|---|---|
scripts/generate_ai_catalog.py |
Generates and validates the aggregate catalog. |
ai-catalog.json |
Contains the generated ingestion catalog. |
.github/workflows/catalog.yml |
Checks aggregate freshness. |
README.md |
Documents the generated artifact. |
CONTRIBUTING.md |
Adds contributor regeneration steps. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/5 changed files
- Comments generated: 2
- Review effort level: Balanced
jeffreyhunter77
left a comment
jeffreyhunter77
left a comment
There was a problem hiding this comment.
Overall, I actually like this. What do you think about my idea to tweak the catalog workflow?
There was a problem hiding this comment.
I think we should make this workflow a little more robust. I think it would be better if we didn't have to rely on contributors to run the generate script at all.
I like the idea of a pull request trigger. If it's for a PR, could we have the workflow run the script and then add the generated catalog to that PR (commit + push)?
Could we then add a trigger for push to main? I'm thinking of this as a fallback. That would cause it to run on PR merge. Ideally, this would always just result in no changes. If it ever does result in a changed catalog file, though, could we have it then open a PR?
There was a problem hiding this comment.
Implemented. Same-repository PRs now regenerate and push ai-catalog.json back to the PR branch. Pushes to main regenerate as a fallback and create or update an automation/update-ai-catalog PR when needed. Fork workflows stay read-only for security; they validate the generator, and the main fallback handles any resulting drift after merge.
There was a problem hiding this comment.
Very much like the idea :D
Summary
This adds a generated ARD-compatible catalog without changing the contributor-managed layout consumed by the existing Agent Finder sync.
Canonical catalog remains unchanged
Files under
catalog/<publisher>/<name>.jsonremain the source of truth. The existing sync can continue reading those files unchanged, while the rootai-catalog.jsonserves consumers that discover only the ARD catalog envelope.Generated ARD compatibility layer
The stdlib generator validates and deterministically combines all local entries with identifiers missing from GitHub's live MCP catalog. Local entries take precedence. Generated copies temporarily adapt only the leading
urn:ai:prefix tourn:air:and add the ARD-requiredtypefield while preserving canonicalmediaTypevalues.The generated aggregate contains all 1,932 local entries and all 210 current live MCP identifiers, for 2,042 entries total. It remains within the ingestion service's 10,000-entry and 10 MiB limits.
Automated freshness
Same-repository pull requests regenerate
ai-catalog.jsonand commit changes back to the PR branch. Fork workflows validate safely without write credentials. A push-to-main fallback opens or updates an automation PR whenever regeneration changes the aggregate.Validation
python3 -m unittest discover -s testspython3 scripts/generate_ai_catalog.py --checkurn:air:identifiers, URL/data delivery rules, and unique identifier/version identities