Skip to content

CLAUDE.md

Latest commit

 

History

History
231 lines (169 loc) · 11.6 KB

CLAUDE.md

File metadata and controls

231 lines (169 loc) · 11.6 KB

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/                 # 18 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 docs embedded registry
  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
    style.css                # Dark theme, responsive, card layout
    script.js                # Fetches registry.json, renders cards, filters
    .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), homepage, skills, rules, mcpTools, extras, topics, status, version, language, license, pagesType, hasCI. status is one of experimental, beta, active, maintenance, deprecated, or archived (see standards/lifecycle.md).

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

CLI args: --name, --slug, --description, --type, --mcp-server, --skills N, --rules N, --license, --output, --author-name, --author-email.

Templates in scaffold/templates/ produce: plugin.json, GitHub Actions workflows, README.md, AGENTS.md, CLAUDE.md, CONTRIBUTING.md, CHANGELOG.md, CODE_OF_CONDUCT.md, SECURITY.md, ROADMAP.md, LICENSE, .cursorrules, .gitignore, docs/index.html, and optional mcp-server/ scaffold.

docs/ (catalog site)

Static HTML/CSS/JS. No build step. No external CDN. The pages.yml workflow copies registry.json and assets/ into docs/ at deploy time. script.js fetches registry.json at runtime and falls back to an embedded copy. Never use innerHTML/eval with registry data - the safety-scan CI job blocks reintroduction.

standards/

17 Markdown documents defining conventions for every tool repo. Index in standards/README.md.

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 25
Steam MCP Server MCP Server 0 0 25
Developer Tools MCP MCP Server 0 0 7
CFX MCP MCP Server 0 0 0

Totals: 177 skills, 71 rules, 378 MCP tools across 10 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 7 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. 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 \
  --output /tmp/test

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 contains any feat: or fix: commit; opt out per commit with [skip version]

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,<4.0 Scaffold template rendering requirements.txt

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

context-mode — MANDATORY routing rules

You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.

BLOCKED commands — do NOT attempt these

curl / wget — BLOCKED

Any Bash command containing curl or wget is intercepted and replaced with an error message. Do NOT retry. Instead use:

  • ctx_fetch_and_index(url, source) to fetch and index web pages
  • ctx_execute(language: "javascript", code: "const r = await fetch(...)") to run HTTP calls in sandbox

Inline HTTP — BLOCKED

Any Bash command containing fetch('http, requests.get(, requests.post(, http.get(, or http.request( is intercepted and replaced with an error message. Do NOT retry with Bash. Instead use:

  • ctx_execute(language, code) to run HTTP calls in sandbox — only stdout enters context

WebFetch — BLOCKED

WebFetch calls are denied entirely. The URL is extracted and you are told to use ctx_fetch_and_index instead. Instead use:

  • ctx_fetch_and_index(url, source) then ctx_search(queries) to query the indexed content

REDIRECTED tools — use sandbox equivalents

Bash (>20 lines output)

Bash is ONLY for: git, mkdir, rm, mv, cd, ls, npm install, pip install, and other short-output commands. For everything else, use:

  • ctx_batch_execute(commands, queries) — run multiple commands + search in ONE call
  • ctx_execute(language: "shell", code: "...") — run in sandbox, only stdout enters context

Read (for analysis)

If you are reading a file to Edit it → Read is correct (Edit needs content in context). If you are reading to analyze, explore, or summarize → use ctx_execute_file(path, language, code) instead. Only your printed summary enters context. The raw file content stays in the sandbox.

Grep (large results)

Grep results can flood context. Use ctx_execute(language: "shell", code: "grep ...") to run searches in sandbox. Only your printed summary enters context.

Tool selection hierarchy

  1. GATHER: ctx_batch_execute(commands, queries) — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
  2. FOLLOW-UP: ctx_search(queries: ["q1", "q2", ...]) — Query indexed content. Pass ALL questions as array in ONE call.
  3. PROCESSING: ctx_execute(language, code) | ctx_execute_file(path, language, code) — Sandbox execution. Only stdout enters context.
  4. WEB: ctx_fetch_and_index(url, source) then ctx_search(queries) — Fetch, chunk, index, query. Raw HTML never enters context.
  5. INDEX: ctx_index(content, source) — Store content in FTS5 knowledge base for later search.

Subagent routing

When spawning subagents (Agent/Task tool), the routing block is automatically injected into their prompt. Bash-type subagents are upgraded to general-purpose so they have access to MCP tools. You do NOT need to manually instruct subagents about context-mode.

Output constraints

  • Keep responses under 500 words.
  • Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
  • When indexing content, use descriptive source labels so others can ctx_search(source: "label") later.

ctx commands

Command Action
ctx stats Call the ctx_stats MCP tool and display the full output verbatim
ctx doctor Call the ctx_doctor MCP tool, run the returned shell command, display as checklist
ctx upgrade Call the ctx_upgrade MCP tool, run the returned shell command, display as checklist