Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions .github/workflows/catalog.yml

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very much like the idea :D

Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
name: Catalog

on:
pull_request:
paths:
- "catalog/*/*.json"
- "ai-catalog.json"
- "scripts/generate_ai_catalog.py"
- "tests/test_generate_ai_catalog.py"
- ".github/workflows/catalog.yml"
push:
branches:
- main
workflow_dispatch:

permissions:
actions: write
contents: write
pull-requests: write

jobs:
update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
ref: ${{ github.event.pull_request.head.ref || github.ref }}
- run: python3 -m unittest discover -s tests
- run: python3 scripts/generate_ai_catalog.py
- name: Update pull request
if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
env:
GH_TOKEN: ${{ github.token }}
HEAD_REF: ${{ github.event.pull_request.head.ref }}
run: |
git diff --quiet -- ai-catalog.json && exit 0
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
git add ai-catalog.json
git commit -m "Update generated ARD catalog"
git push origin "HEAD:$HEAD_REF"
if gh workflow view catalog.yml >/dev/null 2>&1; then
gh workflow run catalog.yml --ref "$HEAD_REF"
fi
- name: Open fallback pull request
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
env:
GH_TOKEN: ${{ github.token }}
run: |
git diff --quiet -- ai-catalog.json && exit 0
branch=automation/update-ai-catalog
git config user.name github-actions[bot]
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
git switch -c "$branch"
git add ai-catalog.json
git commit -m "Update generated ARD catalog"
git push --force origin "$branch"
if [ "$(gh pr list --head "$branch" --state open --json number --jq length)" = 0 ]; then
gh pr create \
--base main \
--head "$branch" \
--title "Update generated ARD catalog" \
--body "Regenerates \`ai-catalog.json\` from the canonical entries and live MCP catalog."
fi
gh workflow run catalog.yml --ref "$branch"
10 changes: 8 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,17 +61,23 @@ Create a file at `catalog/<your-publisher>/<augment-name>.json` with the followi

### 4. Validate your JSON

Make sure your file is valid JSON:
Make sure your file is valid JSON, then regenerate and check the ARD ingestion catalog:

```bash
python -m json.tool catalog/<your-publisher>/<augment-name>.json
python3 scripts/generate_ai_catalog.py
python3 scripts/generate_ai_catalog.py --check
```

Files under `catalog/<publisher>/` remain the source of truth for contributor-managed entries. The root `ai-catalog.json` is generated for ARD ingestion, supplemented with missing entries from GitHub's public MCP catalog, and should not be edited by hand.

The pull request workflow regenerates `ai-catalog.json` automatically for branches in this repository. Fork workflows validate the catalog but cannot push changes; the main-branch fallback opens a follow-up pull request if regeneration is needed after merge.

### 5. Open a pull request

```bash
git checkout -b add-<augment-name>
git add catalog/
git add catalog/ ai-catalog.json
git commit -m "Add <augment-name> to catalog"
git push origin add-<augment-name>
gh pr create --title "Add <augment-name>" --body "Adds <augment-name> to the agentfinder catalog."
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ catalog/

Each augment is a single JSON file under the publisher's directory. The publisher name matches the GitHub organization or username that owns the resource.

These per-entry files are the source of truth for contributor-managed entries. The root `ai-catalog.json` is a generated Agentic Resource Discovery (ARD) ingestion artifact that also includes missing entries from GitHub's public MCP catalog. Do not edit it by hand; regenerate it with `python3 scripts/generate_ai_catalog.py`.

## Contributing

Want to list your skill or MCP server in the catalog? See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide, including the JSON schema, validation steps, and PR process.
Expand Down
Loading
Loading