Quick Start
+GH_TOKEN=your_token npx @tmhs/devtools-mcpNo 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.jsAdd 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
+ +Return entries from registry.json with optional filtering. Use this to enumerate the ecosystem or look up a specific tool.
| Parameter | Type | Default | Description |
|---|---|---|---|
type | string | all | Filter by cursor-plugin or mcp-server |
status | string | all | Filter by lifecycle status: experimental, beta, active, maintenance, deprecated, archived |
slug | string | — | Return a single entry by its registry slug |
All parameters are optional. Called with no arguments, returns every entry in the registry.
+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.
| Parameter | Type | Default | Description |
|---|---|---|---|
include_standards_version | boolean | true | Include the meta-repo STANDARDS_VERSION in the response envelope |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
slug | string | all repos | Check a single repo instead of the full fleet |
verbose | boolean | false | Include per-file details alongside the summary |
Detailed view of a single repo: GitHub metadata, open PRs, recent CI workflow runs, and the standards-version marker read from CLAUDE.md.
| Parameter | Type | Required | Description |
|---|---|---|---|
slug | string | required | Registry slug of the repo to inspect (e.g. steam-mcp) |
Write Tools — require DEVTOOLS_META_ROOT and GH_TOKEN
+ apply=false. No network mutations happen without an explicit apply: true. Always verify the dry-run output before applying.
+ 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.
+| Parameter | Type | Default | Description |
|---|---|---|---|
slug | string | all repos | Restamp only this repo instead of the full fleet |
version | string | meta-repo STANDARDS_VERSION | Target standards version to stamp (default reads the current version from the meta-repo) |
apply | boolean | false | Set 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.
+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.
| Parameter | Type | Default | Description |
|---|---|---|---|
edit | object | — | 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. |
apply | boolean | false | Set true to write edits to disk, regenerate artifacts, and open a meta-repo PR |
Example edit: { "steam-mcp": { "status": "active", "version": "1.1.0" } }
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
name | string | required | Human-readable tool name (e.g. My Cursor Plugin) |
slug | string | auto-derived | URL-safe identifier. Defaults to a kebab-case slug derived from name. |
type | string | cursor-plugin | cursor-plugin or mcp-server |
description | string | required | One-sentence description used in the registry and scaffold README |
license | string | cc-by-nc-nd-4.0 | SPDX license identifier |
apply | boolean | false | Set true to execute creation (requires confirm=true) |
confirm | boolean | false | Safety 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
+| Variable | Status | Description |
|---|---|---|
GH_TOKEN |
+ Strongly recommended | +GitHub 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_TOKEN |
+ Alternative | +Accepted as a fallback if GH_TOKEN is not set. |
+
DEVTOOLS_META_ROOT |
+ Required for write tools | +Absolute 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 applyrequires bothapply=trueANDconfirm=trueplus a token with repo-creation scope.
+ - No secrets are committed. Tokens come from environment variables only. +
- Rate-limit errors name
GH_TOKENwith 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_syncRegistryis update-only; it cannot add new entries to the registry.
+ devtools_createTooldry-run scaffolds to a temp directory and cleans up; it never writes to the working tree.
+
Development
+npm install
+npm run build
+npm testTests use vitest with mocked fetch responses. No live API calls are made in CI. See CONTRIBUTING.md for guidelines.
+