TMHSDigital · TMHSDigital · May 24, 2026 · May 24, 2026
diff --git a/.env.example b/.env.example
@@ -0,0 +1,11 @@
+# GH_TOKEN is strongly recommended.
+# Unauthenticated GitHub requests are limited to 60 per hour per IP.
+# A single fleet call fans out to roughly 20-30 requests.
+# Generate a token at https://github.com/settings/tokens (no scopes needed for public repos).
+GH_TOKEN=
+
+# DEVTOOLS_META_ROOT is optional.
+# When set, registry.json, VERSION, and the drift config are read from this local
+# directory instead of GitHub. Useful for offline operation or iterating locally.
+# Must be the absolute path to a Developer-Tools-Directory checkout.
+DEVTOOLS_META_ROOT=
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [20, 22]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,30 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+          cache: npm
+
+      - run: npm install -g npm@latest
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
@@ -10,19 +10,16 @@ permissions:
   contents: read
 
 jobs:
-
-  validate-mcp-server:
-    name: Validate MCP server
+  validate-typescript:
+    name: Validate TypeScript
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-node@v6
         with:
-          python-version: "3.12"
-
-      - name: Install dependencies
-        run: pip install -r mcp-server/requirements.txt
+          node-version: 20
+          cache: npm
 
-      - name: Check Python syntax
-        run: python3 -m py_compile mcp-server/server.py
+      - run: npm ci
+      - run: npm run build
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,10 +4,14 @@ All notable changes to Developer Tools MCP will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
-## [0.1.0] - Unreleased
+## [0.1.0] - 2026-05-24
 
 ### Added
 
-- Initial project scaffold
-- CI/CD workflows (validate, release, pages, stale)
-- GitHub Pages documentation site
+- Initial scaffold at standards-version 1.10.0
+- Four read-only MCP tools: `devtools_getRegistry`, `devtools_getFleetStatus`, `devtools_checkDrift`, `devtools_inspectRepo`
+- GitHub REST API default mode with 5-minute in-memory cache; no token required for public repos
+- Optional local mode via `DEVTOOLS_META_ROOT` env var for offline meta-repo reads
+- `devtools_checkDrift` fetches drift policy from `standards/drift-checker.config.json` at runtime
+- CI workflows: `ci.yml` (build and test, Node 20 and 22), `drift-check.yml`, `stale.yml`, `publish.yml`
+- Tests for all four tools and utility layer, wired into CI via `npm test`
diff --git a/README.md b/README.md
@@ -1,40 +1,110 @@
 # 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 read 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)
 
+**v1 is read-only.** No write operations, no secrets, no tokens committed. The write roadmap is documented in [ROADMAP.md](ROADMAP.md).
+
+---
+
+## What it does
+
+This server gives any MCP-capable agent four read tools against the ecosystem:
+
+| Tool | Description |
+|------|-------------|
+| `devtools_getRegistry` | Return entries from `registry.json`, with optional filtering by type, status, or slug |
+| `devtools_getFleetStatus` | List all repos with registry version, latest release tag, and current/behind/ahead signal |
+| `devtools_checkDrift` | Return drift findings: standards-version mismatches and missing required workflows |
+| `devtools_inspectRepo` | Detailed view of one repo: GitHub metadata, open PRs, CI run status, standards-version |
+
+`devtools_checkDrift` fetches `standards/drift-checker.config.json` from the meta-repo at runtime and applies its thresholds and required-workflow lists. The canonical drift checker (`scripts/drift_check/cli.py` in the meta-repo) is authoritative; this tool is a convenience reader for agents that cannot run Python locally.
+
 ---
 
-MCP server exposing the TMHSDigital developer-tools ecosystem as agent-callable read tools
+## Running as an MCP server
 
-## Installation
+### Quick start with npx
 
 ```bash
-npm install developer-tools-mcp
+GH_TOKEN=your_token npx @tmhs/devtools-mcp
 ```
 
-## Project Structure
+### From source
 
+```bash
+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
 ```
-developer-tools-mcp/
-  src/                Source code
-  .github/            CI/CD workflows
+
+### Claude Desktop / Cursor config
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "devtools": {
+      "command": "npx",
+      "args": ["@tmhs/devtools-mcp"],
+      "env": {
+        "GH_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
 ```
 
-## Roadmap
+---
 
-See [ROADMAP.md](ROADMAP.md) for the full project roadmap.
+## Environment variables
 
-## Contributing
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GH_TOKEN` | Strongly recommended | GitHub personal access token. No scopes required for 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. |
+| `GITHUB_TOKEN` | Alternative | Accepted as a fallback if `GH_TOKEN` is not set. |
+| `DEVTOOLS_META_ROOT` | Optional | Absolute path to a local `Developer-Tools-Directory` checkout. When set, `registry.json`, `VERSION`, and the drift config are read from disk instead of GitHub. Useful for offline operation. |
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Copy `.env.example` to `.env` and fill in `GH_TOKEN` before running locally.
 
-## License
+---
+
+## Caching
+
+All GitHub API and raw file responses are cached in memory with a 5-minute TTL. Repeated tool calls within a session reuse cached data without additional API requests.
 
-CC-BY-NC-ND-4.0 -- see [LICENSE](LICENSE) for details.
+---
+
+## Public safety posture
+
+- Read-only. No tool modifies any repo, file, or GitHub resource.
+- No secrets are committed. Tokens come from environment variables only.
+- No hardcoded paths. All GitHub reads use the public API or raw content URLs.
+- Rate-limit errors name `GH_TOKEN` and link to how to get one.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Tests use vitest with mocked fetch responses. No live API calls are made in CI.
 
 ---
 
-**Built by TMHSDigital**
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+CC-BY-NC-ND-4.0 - see [LICENSE](LICENSE) for details.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -4,25 +4,30 @@
 
 **Current:** v0.1.0
 
-## Developer Tools MCP
+## v0.1.0 - Read-Only Core (shipped)
 
-### v0.1.x -- Foundation
+- Four read tools: `devtools_getRegistry`, `devtools_getFleetStatus`, `devtools_checkDrift`, `devtools_inspectRepo`
+- GitHub REST API default mode, optional local mode via `DEVTOOLS_META_ROOT`
+- `devtools_checkDrift` reads drift policy from the meta-repo at runtime
+- Tests for all tools wired into CI
 
-- [ ] Initial skills and rules
-- [ ] MCP server with core tools
-- [ ] CI/CD workflows
-- [ ] GitHub Pages documentation site
-- [ ] AGENTS.md and .cursorrules
+## v0.2.0 - Write Surface (not yet built)
 
-### v0.2.0 -- Content Expansion
+The following tools are planned and explicitly not implemented in v1. Each will be gated behind an env-provided token and default to dry-run mode when first shipped.
 
-- [ ] Additional skills
-- [ ] Additional rules
-- [ ] Additional MCP tools
-- [ ] Comprehensive documentation
+**Planned tools:**
 
-### v1.0.0 -- Stable Release
+| Tool (planned) | Description |
+|----------------|-------------|
+| `devtools_createTool` | Invoke the scaffold generator to produce a new tool repo from a name, description, and type. Requires a GitHub token with repo-creation scope. Dry-run by default. |
+| `devtools_bumpVersion` | Re-stamp the version in a tool repo's `package.json` or `plugin.json` and open a PR. Requires a token with push scope on the target repo. Dry-run by default. |
+| `devtools_syncRegistry` | Run the equivalent of `sync_from_registry.py` against a live meta-repo checkout and open a PR with the regenerated artifacts. Requires a token with push scope on the meta-repo. Dry-run by default. |
+| `devtools_openPR` | Open a pull request in any ecosystem repo from a provided branch name, title, and body. Requires a token with pull-request scope. Dry-run by default. |
 
-- [ ] Full test coverage
-- [ ] Marketplace listing
-- [ ] Complete documentation
+None of the above will be added until the read core is stable and the token-scoping and dry-run model are agreed. Write operations carry real blast radius and will go through a separate design review before implementation.
+
+## v1.0.0 - Stable
+
+- Full tool coverage for read and write surfaces
+- npm publish under `@tmhs/devtools-mcp`
+- Complete documentation and marketplace listing
diff --git a/mcp-tools.json b/mcp-tools.json
@@ -1 +1,22 @@
-[]
+[
+  {
+    "name": "devtools_getRegistry",
+    "description": "Return entries from the TMHSDigital developer-tools ecosystem registry. Optionally filter by type, status, or slug. Returns all entries when no filter is given.",
+    "category": "registry"
+  },
+  {
+    "name": "devtools_getFleetStatus",
+    "description": "List all tool repos in the ecosystem with their registry version, latest GitHub release tag, and a current/behind/ahead signal. Optionally include the standards-version from each repo's CLAUDE.md.",
+    "category": "fleet"
+  },
+  {
+    "name": "devtools_checkDrift",
+    "description": "Return drift findings across the ecosystem fleet: standards-version mismatches and missing required workflows. Drift policy is read from the meta-repo's standards/drift-checker.config.json at runtime.",
+    "category": "drift"
+  },
+  {
+    "name": "devtools_inspectRepo",
+    "description": "Return a detailed view of one ecosystem repo: GitHub metadata, open PR count, latest CI run statuses, and the standards-version from the repo's agent files.",
+    "category": "fleet"
+  }
+]