Skip to content

CLAUDE.md

Latest commit

 

History

History
184 lines (137 loc) · 10.2 KB

CLAUDE.md

File metadata and controls

184 lines (137 loc) · 10.2 KB
Raw

CLAUDE.md

Project documentation for Claude Code and AI assistants working on this repository.

Project Overview

Developer Tools Directory is a meta-repository that catalogs, standardizes, and scaffolds all TMHSDigital Cursor IDE plugins and MCP servers. It does not contain a plugin or MCP server itself.

License: CC-BY-NC-ND-4.0 outbound, DCO + broader inbound grant (see CONTRIBUTING.md) Author: TMHSDigital

Catalog site: https://tmhsdigital.github.io/Developer-Tools-Directory/

Architecture

Developer-Tools-Directory/
  registry.json              # Source of truth for all tool repos
  standards/                 # Convention docs (structure, CI/CD, testing, MCP, security, licensing, etc.)
  scaffold/
    create-tool.py           # Python repo generator (Jinja2)
    templates/               # Jinja2 templates for new repos
  scripts/
    sync_from_registry.py    # Regenerates README, CLAUDE.md, and the docs site from the registry
    validate_registry.py     # registry.json schema and consistency checks (CI + tests)
    check_fleet_about.py     # Report-only: GitHub About drift vs registry across the fleet
  site-template/
    build_site.py            # Builds GitHub Pages for tool repos from their metadata
    template.html.j2         # Shared HTML template with configurable branding
    fonts/                   # Self-hosted Inter + JetBrains Mono woff2
    SETUP-PROMPT.md          # Copy-paste prompt for applying template to a repo
  docs/
    index.html               # GitHub Pages catalog site (inline CSS and JS)
    search-index.json        # Skill/rule/MCP-tool names for search (aggregate_search.py)
    robots.txt, sitemap.xml  # Generated by sync_from_registry.py
    .well-known/security.txt # RFC 9116 security contact
    contributors/            # Worked examples for new contributors
  assets/
    logo.png                 # Directory logo
  .github/
    CODEOWNERS               # Review routing
    PULL_REQUEST_TEMPLATE.md
    ISSUE_TEMPLATE/          # Bug report, feature request, config
    workflows/               # Validate, sync, pages, release, stale, codeql, etc.
      README.md              # Action-pinning convention

Key Files

registry.json

Array of tool objects. Each entry has: name, repo, slug, description, type (cursor-plugin | mcp-server), category (catalog filter chip; allowed values in scripts/validate_registry.py), homepage, skills, rules, mcpTools, extras, topics, status, language, license, pagesType, hasCI. status is one of experimental, beta, active, maintenance, deprecated, or archived (see standards/lifecycle.md).

There is intentionally no per-tool version field. Tool repos auto-bump patch on every content merge, so a catalog-pinned patch version re-stales on each tool's next content PR; the catalog tracks tools by repo and homepage instead. Do not reintroduce it.

When updating, run python scripts/sync_from_registry.py to regenerate every derived artifact. The sync-check CI job blocks PRs that drift.

scripts/sync_from_registry.py

Pure-stdlib Python script that regenerates README tables and stats, CLAUDE.md cataloged tools and totals, and the embedded registry JSON in docs/index.html. Modes: no flag (write), --check (CI drift detection), --about (print the gh repo edit command for the GitHub About section, run locally).

scaffold/create-tool.py

Thin CLI over scaffold/generator.py (generate_repo). CLI args: --name, --slug, --description, --type (cursor-plugin | mcp-server), --mcp-server (cursor-plugin only: adds a Python MCP server), --deployed-service (mcp-server archetype without npm), --skills N, --rules N, --license, --output, --author-name, --author-email, --no-register, --registry-root. Run python scaffold/create-tool.py --help for the authoritative list.

Registration is on by default: without --no-register, the scaffold appends the new repo to registry.json and regenerates README, CLAUDE.md, and the docs site. Always pass --no-register for throwaway or test runs.

Templates in scaffold/templates/ produce: GitHub Actions workflows, README.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, CODE_OF_CONDUCT.md, SECURITY.md, ROADMAP.md, LICENSE, .cursorrules, .gitignore, .gitattributes, site.json, mcp-tools.json, and dependabot.yml. Cursor plugins also get .cursor-plugin/plugin.json (plus an optional Python mcp-server/); mcp-servers get package.json, a buildable TypeScript skeleton (src/, tsconfig.json, vitest test), and docs/index.html. Generated output must meet standards/born-green-contract.md.

docs/ (catalog site)

Static single page; all CSS and JS are inline in docs/index.html (there is no separate stylesheet or script file). No build step. No external CDN. sync_from_registry.py pre-renders the tool cards, filter chips, and hero stats so the page works without JavaScript; the inline script fetches registry.json at runtime (falling back to the embedded copy) and layers search and filtering on top. The pages.yml workflow copies registry.json and assets/ into docs/ and stamps the footer date at deploy time. Refresh search data with python site-template/aggregate_search.py --clone. Never use innerHTML/eval with registry data - the safety-scan CI job blocks reintroduction.

standards/

Markdown documents defining conventions for every tool repo. The index in standards/README.md is the authoritative list (and the catalog site renders a card per file).

Cataloged Tools

Tool Type Skills Rules MCP Tools
CFX Developer Tools Plugin 9 6 6
Unity Developer Tools Plugin 18 8 4
Docker Developer Tools Plugin 17 10 150
Home Lab Developer Tools Plugin 22 11 50
Mobile App Developer Tools Plugin 43 12 36
Plaid Developer Tools Plugin 17 7 30
Monday Cursor Plugin Plugin 21 8 45
Steam Cursor Plugin Plugin 30 9 26
Steam MCP Server MCP Server 0 0 26
Developer Tools MCP MCP Server 0 0 7
CFX MCP MCP Server 0 0 3
Blender Developer Tools Plugin 18 9 0
Local AI MCP MCP Server 0 0 16
Screencast MCP MCP Server 0 0 25
Tailscale MCP MCP Server 0 0 6
Godot Correctness MCP MCP Server 0 0 10
Bounty Radar MCP MCP Server 0 0 1

Totals: 195 skills, 80 rules, 441 MCP tools across 17 repos

Development Workflow

Contribution flow

main is protected by the main protection ruleset. Direct pushes, force pushes, and branch deletion are all blocked for every contributor including the repo owner (empty bypass list). All changes land via pull request with squash merge only.

Standard loop for any change, including single-file edits:

git checkout -b <type>/<short-description>
# edits
git add <paths>
git commit -s -m "<conventional subject>"
git push -u origin HEAD
gh pr create --base main
gh pr checks <number> --watch
gh pr merge <number> --squash --delete-branch

A PR cannot be merged until all 8 required status checks pass: Validate registry.json, Validate docs site, Validate scaffold, Registry sync check, Public-repo safety scan, feat/fix commits require VERSION bump, CodeQL, Run drift_check tests. Required approvals are 0 (solo maintainer). release.yml's Check VERSION vs latest tag is a post-merge guard, not a PR gate.

Prerequisites

pip install -r requirements.txt  # Jinja2

Testing the scaffold

python scaffold/create-tool.py \
  --name "Test Plugin" \
  --description "Automated test" \
  --mcp-server \
  --skills 2 \
  --rules 1 \
  --no-register \
  --output /tmp/test

--no-register keeps the throwaway repo out of registry.json.

Testing the docs site locally

Open docs/index.html in a browser. The script falls back to embedded registry data when not served from GitHub Pages.

CI validation

validate.yml runs on every PR and push to main:

  • Registry JSON syntax and schema validation
  • Docs file existence checks
  • Scaffold Python syntax check
  • Scaffold dry-run test (generates repo, verifies key files exist, scans for leaked business email)
  • sync-check job: runs python scripts/sync_from_registry.py --check and fails on drift
  • safety-scan job: blocks leaked business emails, drive-letter paths, unsafe DOM sinks (innerHTML/eval in docs/), and committed credential files
  • version-bump-check job (PR only): requires a VERSION bump when the PR title or any commit is feat: or fix: (the title matters because squash merges use it as the commit subject); opt out with [skip version]
  • test-drift-check job: runs the full pytest suite (required check Run drift_check tests)

Release workflow

release.yml runs on push to main and reads the VERSION file at the repo root. If VERSION is ahead of the latest git tag, it creates tag v<VERSION> and a GitHub Release. If VERSION equals the latest tag, the workflow no-ops. If VERSION is lower, the workflow fails. Release notes come from release-drafter's current draft body when present, otherwise from the commit log since the previous tag. The meta-repo uses VERSION-file-driven releases; tool repos use conventional-commit auto-bumps per standards/versioning.md.

Conventions

  • Conventional commits with DCO sign-off (git commit -s)
  • No em dashes, en dashes, or emoji - see standards/writing-style.md
  • No hardcoded credentials, business emails, or local filesystem paths anywhere
  • Public readership - all docs written for external consumption
  • Single branch - main only
  • Self-contained docs site - no CDN, no unsafe DOM sinks
  • registry.json is the single source of truth - README, CLAUDE.md, and docs/index.html embedded data are generated

Dependencies

Dependency Purpose Where
Jinja2 >=3.1.6,<4.0 Scaffold template rendering requirements.txt

The docs site has zero runtime dependencies. The sync script is pure stdlib.