From 5144ec93ef52740cb6f99fbf004a6eda3130e5bd Mon Sep 17 00:00:00 2001 From: fOuttaMyPaint Date: Sun, 24 May 2026 17:30:08 -0400 Subject: [PATCH] fix: pages deploy, release workflow, docs site, and v0.2.0 version markers - Replace pages.yml cursor-plugin build_site.py with direct docs/ deploy - Remove release-doc-sync@v1 step; add package.json version bump to release.yml - Create docs/index.html with full 7-tool reference, quick start, env var docs - Move CHANGELOG [Unreleased] to [0.2.0] - 2026-05-24 (includes restampRepo entry) - Update ROADMAP Current to v0.2.0 - Pre-set README version badge to 0.2.0 Signed-off-by: fOuttaMyPaint --- .github/workflows/pages.yml | 25 +- .github/workflows/release.yml | 16 +- CHANGELOG.md | 4 + README.md | 4 +- ROADMAP.md | 2 +- docs/index.html | 517 ++++++++++++++++++++++++++++++++++ 6 files changed, 535 insertions(+), 33 deletions(-) create mode 100644 docs/index.html diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 9e94fdd..8c5739e 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -4,11 +4,7 @@ on: push: branches: [main] paths: - - "skills/**" - - "rules/**" - - "mcp-tools.json" - - "site.json" - - ".cursor-plugin/plugin.json" + - "docs/**" - "assets/**" workflow_dispatch: @@ -21,8 +17,7 @@ concurrency: cancel-in-progress: true jobs: - build-and-deploy: - + deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} @@ -30,22 +25,6 @@ jobs: steps: - uses: actions/checkout@v6 - - name: Checkout site template - uses: actions/checkout@v6 - with: - repository: TMHSDigital/Developer-Tools-Directory - sparse-checkout: site-template - path: _template - - - uses: actions/setup-python@v6 - with: - python-version: "3.12" - - - run: pip install Jinja2 - - - name: Build site - run: python _template/site-template/build_site.py --repo-root . --out docs - - uses: actions/configure-pages@v6 - uses: actions/upload-pages-artifact@v5 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 5c853ba..ebec0ff 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -116,14 +116,16 @@ jobs: ) with open(readme, 'w') as f: f.write(content) - " - - name: Sync release docs - if: steps.check.outputs.skip == 'false' - uses: TMHSDigital/Developer-Tools-Directory/.github/actions/release-doc-sync@v1 - with: - plugin-version: ${{ steps.new.outputs.version }} - previous-version: ${{ steps.current.outputs.version }} + pkg = 'package.json' + if os.path.exists(pkg): + with open(pkg) as f: + data = json.load(f) + data['version'] = new_version + with open(pkg, 'w') as f: + json.dump(data, f, indent=2) + f.write('\n') + " - name: Commit version bump to branch and open PR id: pr diff --git a/CHANGELOG.md b/CHANGELOG.md index 628d86e..1eec248 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,11 +6,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/). ## [Unreleased] +## [0.2.0] - 2026-05-24 + ### Added +- `devtools_restampRepo`: preview or apply a standards-version restamp across fleet repos. Dry-run calls the canonical drift checker (`scripts/drift_check/cli.py`) to discover drifted files. Apply stamps files via Phase 1 Python scripts, opens per-repo branches and PRs, and squash-merges when CI passes. Requires `DEVTOOLS_META_ROOT` and `GH_TOKEN`. - `devtools_syncRegistry`: preview or apply `registry.json` field edits and regenerate derived artifacts (README.md, CLAUDE.md, docs/index.html). Update-only boundary: rejects slugs not already in the registry. Dry-run runs `sync_from_registry.py --check` against the edited registry without committing. Apply writes edits, regenerates, verifies with `--check`, and opens a meta-repo PR that is squash-merged when CI passes. Requires `DEVTOOLS_META_ROOT` and `GH_TOKEN`. - `devtools_createTool`: plan or execute creation of a new ecosystem tool repo. Dry-run validates inputs, runs `scaffold/create-tool.py` to a temp dir, lists generated files, reports the would-be registry entry and `STANDARDS_VERSION` at birth. Apply creates a real public GitHub repo (guarded by `confirm=true` and token with repo-creation scope), scaffolds, bootstraps, applies branch protection matching the type, and registers via meta-repo PR. Requires `DEVTOOLS_META_ROOT`. - `.gitattributes` with `text=auto` and `*.ts eol=lf` to eliminate CRLF phantom changes in git status. +- GitHub Pages documentation site at `docs/index.html` covering all 7 tools, quick start, and environment variable reference. ## [0.1.0] - 2026-05-24 diff --git a/README.md b/README.md index 3101aa0..82e4d6d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Developer Tools MCP -MCP server exposing the TMHSDigital developer-tools ecosystem as agent-callable read tools. +MCP server exposing the TMHSDigital developer-tools ecosystem as agent-callable tools. ![License: CC-BY-NC-ND-4.0](https://img.shields.io/badge/license-CC--BY--NC--ND--4.0-green) -![Version](https://img.shields.io/badge/version-0.1.0-blue) +![Version](https://img.shields.io/badge/version-0.2.0-blue) **v0.2.0 adds a write surface.** Three write tools ship alongside the four read tools. All write tools default to dry-run and require `DEVTOOLS_META_ROOT` and `GH_TOKEN`. The write surface is now complete; see [ROADMAP.md](ROADMAP.md). diff --git a/ROADMAP.md b/ROADMAP.md index 610533a..91cc6a6 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -2,7 +2,7 @@ # Roadmap -**Current:** v0.1.0 +**Current:** v0.2.0 ## v0.1.0 - Read-Only Core (shipped) diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..da4d7bb --- /dev/null +++ b/docs/index.html @@ -0,0 +1,517 @@ + + + + + + Developer Tools MCP + + + + +
+
+ + +
+
+ +
+
v0.2.0
+

Developer Tools MCP

+

MCP server exposing the TMHSDigital developer-tools ecosystem as agent-callable tools. Read and write the fleet from any MCP-enabled agent.

+
+
4Read tools
+
3Write tools
+
0Auth needed for reads
+
5 minCache TTL
+
+
+ Quick Start + View on GitHub +
+
+ +
+ + +
+

Quick Start

+
+ + + +
+
+ 
GH_TOKEN=your_token npx @tmhs/devtools-mcp
+

No install required. Pulls the latest published version. GH_TOKEN is optional for read tools against public repos.

+
+
+ 
git clone https://github.com/TMHSDigital/Developer-Tools-MCP.git
+cd Developer-Tools-MCP
+npm install
+npm run build
+GH_TOKEN=your_token node dist/index.js
+
+
+

Add to your Claude Desktop, Cursor, or other MCP client config:

+ 
{
+  "mcpServers": {
+    "devtools": {
+      "command": "npx",
+      "args": ["@tmhs/devtools-mcp"],
+      "env": {
+        "GH_TOKEN": "your_token_here",
+        "DEVTOOLS_META_ROOT": "/path/to/Developer-Tools-Directory"
+      }
+    }
+  }
+}
+

DEVTOOLS_META_ROOT is only required for write tools (restampRepo, syncRegistry, createTool).

+
+
+ + +
+

Tools

+ +

Read Tools — no token required for public repos

+ +
+
+ devtools_getRegistry + Read +
+

Return entries from registry.json with optional filtering. Use this to enumerate the ecosystem or look up a specific tool.

+ + + + + + + +
ParameterTypeDefaultDescription
typestringallFilter by cursor-plugin or mcp-server
statusstringallFilter by lifecycle status: experimental, beta, active, maintenance, deprecated, archived
slugstring—Return a single entry by its registry slug
+

All parameters are optional. Called with no arguments, returns every entry in the registry.

+
+ +
+
+ devtools_getFleetStatus + Read +
+

List all repos with their registry version, latest GitHub release tag, and a version-signal field showing whether each repo is current, behind, or ahead of the fleet standards version.

+ + + + + +
ParameterTypeDefaultDescription
include_standards_versionbooleantrueInclude the meta-repo STANDARDS_VERSION in the response envelope
+
+ +
+
+ devtools_checkDrift + Read +
+

Return drift findings for one or all repos: standards-version mismatches and missing required workflows. Fetches the drift policy from standards/drift-checker.config.json in the meta-repo at runtime, so it always uses the current policy without a local clone.

+
+

The canonical drift checker (scripts/drift_check/cli.py) is authoritative. This tool is a convenience reader for agents that cannot run Python locally. For write operations on drift, use devtools_restampRepo.

+
+ + + + + + +
ParameterTypeDefaultDescription
slugstringall reposCheck a single repo instead of the full fleet
verbosebooleanfalseInclude per-file details alongside the summary
+
+ +
+
+ devtools_inspectRepo + Read +
+

Detailed view of a single repo: GitHub metadata, open PRs, recent CI workflow runs, and the standards-version marker read from CLAUDE.md.

+ + + + + +
ParameterTypeRequiredDescription
slugstringrequiredRegistry slug of the repo to inspect (e.g. steam-mcp)
+
+ +

Write Tools — require DEVTOOLS_META_ROOT and GH_TOKEN

+
+
+ Dry-run by default. All write tools default to apply=false. No network mutations happen without an explicit apply: true. Always verify the dry-run output before applying. +
+
+ +
+
+ devtools_restampRepo + Write + Dry-run safe +
+

Preview or apply a standards-version restamp across fleet repos. Dry-run delegates to the canonical Python drift checker to discover which files need stamping. Apply creates per-repo branches, commits via the GitHub API, opens PRs, and squash-merges each one when CI passes.

+ + + + + + + +
ParameterTypeDefaultDescription
slugstringall reposRestamp only this repo instead of the full fleet
versionstringmeta-repo STANDARDS_VERSIONTarget standards version to stamp (default reads the current version from the meta-repo)
applybooleanfalseSet true to open real PRs and merge them
+

Dry-run output: list of repos with drifted files and the planned stamp value. Apply output: per-repo PR numbers and merge status.

+
+ +
+
+ devtools_syncRegistry + Write + Dry-run safe +
+

Preview or apply registry.json field edits and regenerate all derived artifacts (README.md, CLAUDE.md, docs/index.html). Apply opens a meta-repo PR that is squash-merged when CI passes.

+
+

Update-only boundary. This tool rejects slugs that are not already in registry.json. To add a new entry, use devtools_createTool.

+
+ + + + + + +
ParameterTypeDefaultDescription
editobject—Map of { slug: { field: value, ... } } describing the edits to apply. Omit to run a no-op dry-run that verifies the registry is in sync.
applybooleanfalseSet true to write edits to disk, regenerate artifacts, and open a meta-repo PR
+

Example edit: { "steam-mcp": { "status": "active", "version": "1.1.0" } }

+
+ +
+
+ devtools_createTool + Write + Irreversible on apply +
+

Plan or execute creation of a new ecosystem tool repo. Dry-run scaffolds the full file tree to a temp directory, reports the 22-file plan and the would-be registry entry, then cleans up. Apply creates a real public GitHub repo.

+
+

Double-confirm guard. apply=true alone is refused. You must also pass confirm=true. The gh repo create step creates a live public repo and cannot be undone. Read the dry-run output carefully before confirming.

+
+ + + + + + + + + + + +
ParameterTypeDefaultDescription
namestringrequiredHuman-readable tool name (e.g. My Cursor Plugin)
slugstringauto-derivedURL-safe identifier. Defaults to a kebab-case slug derived from name.
typestringcursor-plugincursor-plugin or mcp-server
descriptionstringrequiredOne-sentence description used in the registry and scaffold README
licensestringcc-by-nc-nd-4.0SPDX license identifier
applybooleanfalseSet true to execute creation (requires confirm=true)
confirmbooleanfalseSafety gate: must be true alongside apply=true to proceed
+

Apply steps: create public GitHub repo, scaffold 22 files, git init + push, apply branch protection, open meta-repo PR to register the new entry.

+
+
+ + +
+

Environment Variables

+ + + + + + + + + + + + + + + + + + + + + +
VariableStatusDescription
GH_TOKENStrongly recommendedGitHub personal access token. No scopes required for read tools against public repos. Without it, GitHub limits unauthenticated requests to 60 per hour per IP. A single full fleet call fans out to 20-30 requests. Required for all write tools.
GITHUB_TOKENAlternativeAccepted as a fallback if GH_TOKEN is not set.
DEVTOOLS_META_ROOTRequired for write toolsAbsolute path to a local Developer-Tools-Directory checkout. When set, registry.json, STANDARDS_VERSION, and the drift config are read from disk instead of GitHub. Required for all write tools: restampRepo, syncRegistry, createTool.
+

Copy .env.example to .env and fill in GH_TOKEN before running locally.

+
+ + +
+

Safety Posture

+
+
+

Network safety

+
    +
  • Write tools default to apply=false. No network mutations without explicit opt-in.
    • +
  • createTool apply requires both apply=true AND confirm=true plus a token with repo-creation scope.
    • +
  • No secrets are committed. Tokens come from environment variables only.
    • +
  • Rate-limit errors name GH_TOKEN with instructions on how to obtain one.
    • +
+
+
+

Data safety

+
    +
  • No hardcoded paths. All GitHub reads use the public API or raw content URLs.
    • +
  • All GitHub API and raw file responses are cached in memory with a 5-minute TTL.
    • +
  • devtools_syncRegistry is update-only; it cannot add new entries to the registry.
    • +
  • devtools_createTool dry-run scaffolds to a temp directory and cleans up; it never writes to the working tree.
    • +
+
+
+
+ + +
+

Development

+ 
npm install
+npm run build
+npm test
+

Tests use vitest with mocked fetch responses. No live API calls are made in CI. See CONTRIBUTING.md for guidelines.

+
+ +
+ + + + + + +