claudenv 1.0.2 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudenv",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "One command to integrate Claude Code into any project — installs /claudenv command for AI-powered documentation generation",
   "type": "module",
   "bin": {

package/scaffold/.claude/commands/setup-mcp.md

@@ -0,0 +1,115 @@
+---
+description: Recommend and configure MCP servers based on project analysis
+allowed-tools: Read, Write, Glob, Grep, Bash(curl:*), Bash(find:*), Bash(cat:*)
+disable-model-invocation: true
+argument-hint: [--force]
+---
+
+# MCP Server Setup
+
+You are configuring MCP servers for this project. Analyze the tech stack, search the official MCP Registry, verify trust signals, and generate `.mcp.json`.
+
+## Step 1: Analyze the Project
+
+Understand what this project uses:
+
+**Read existing documentation:**
+- Read CLAUDE.md if it exists — it contains the tech stack summary
+- Read _state.md if it exists
+
+**Check for existing MCP config:**
+- Read `.mcp.json` if it exists — you will merge new entries, not overwrite
+
+**Scan manifest files:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "requirements.txt" \) -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/vendor/*" 2>/dev/null | head -20`
+
+**Scan framework and tooling configs:**
+!`find . -maxdepth 2 \( -name "tsconfig*.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "docker-compose.*" -o -name "Dockerfile" -o -name ".env*" -o -name "prisma" -o -name "drizzle.config.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+Read the manifest files you found. Identify:
+- Programming languages and frameworks
+- Databases (PostgreSQL, MongoDB, Redis, etc.)
+- Cloud services (AWS, GCP, Azure)
+- External APIs (Stripe, Sentry, etc.)
+- Dev tools (Docker, GitHub Actions, etc.)
+
+## Step 2: Search the MCP Registry
+
+Read the MCP server reference for search and evaluation guidance:
+@.claude/skills/doc-generator/templates/mcp-servers.md
+
+For each major technology in the project, search the official MCP Registry API:
+```bash
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=<tech>&version=latest&limit=10'
+```
+
+For each candidate server with an npm package, verify trust by checking monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package>'
+```
+
+Optionally check GitHub stars for additional trust signal:
+```bash
+curl -s 'https://api.github.com/repos/<owner>/<repo>'
+```
+
+**Filtering rules:**
+- Remove servers with <100 monthly npm downloads
+- Rank by: npm downloads (primary) + GitHub stars (secondary) + description relevance
+- When multiple servers exist for the same technology, pick the one with the highest downloads
+
+## Step 3: Present Recommendations
+
+Group your recommendations into three tiers:
+
+**Essential** — servers that directly support the project's core technologies (e.g., PostgreSQL server for a project using PostgreSQL)
+
+**Recommended** — servers that enhance the development workflow (e.g., Context7 for library docs, GitHub for repo management)
+
+**Optional** — servers that could be useful but aren't critical (e.g., Fetch for web content, Docker if Docker is used occasionally)
+
+For each recommendation, explain:
+- **What it does** and why it's relevant to THIS project
+- **Monthly npm downloads** (trust signal)
+- **Environment variables required** and whether they need secrets
+
+Ask the user which servers to configure.
+
+If `$ARGUMENTS` includes `--force`, auto-select all Essential and Recommended servers.
+
+## Step 4: Generate .mcp.json
+
+Build the `.mcp.json` file with the selected servers following the format in the MCP server reference.
+
+**If `.mcp.json` already exists:**
+- Read it and parse the existing `mcpServers` entries
+- Merge new servers into the existing config — do NOT remove or overwrite existing entries
+- If a server key already exists, skip it (preserve the user's existing config)
+
+**Key rules:**
+- Use `${ENV_VAR}` placeholders for ALL secret environment variables — NEVER literal values
+- Non-secret env vars can use literal values when appropriate
+- Use `npx -y <package>@latest` for stdio/npm servers
+- Use the `type` and `url` from remotes for HTTP/SSE servers
+
+Write the `.mcp.json` file.
+
+## Step 5: Update CLAUDE.md
+
+If CLAUDE.md exists, add or update an `## MCP Servers` section listing the configured servers and what they do. Keep it concise — one line per server.
+
+If CLAUDE.md doesn't exist, skip this step and suggest running `/claudenv` first.
+
+## Step 6: Environment Variables
+
+List all required environment variables and how to configure them:
+
+```
+To configure secrets, run:
+  claude config set env.VAR_NAME "your-value"
+
+Required environment variables:
+  VAR_NAME — Description of what this is and where to get it
+```
+
+Remind the user that `.mcp.json` is safe to commit — it only contains placeholders, not actual secrets.

package/scaffold/.claude/commands/update-docs.md

@@ -34,6 +34,7 @@ Compare the current state against the existing documentation:
 - **New directories** not covered in Architecture section
 - **Stale references** to files or directories that no longer exist
 - **Missing conventions** based on new config files (e.g., new linter added)
+- **Missing or outdated `.mcp.json`** — if `.mcp.json` doesn't exist, or if new technologies have been added that could benefit from MCP servers, suggest running `/setup-mcp`
 
 ## Step 4: Propose Updates
 

package/scaffold/.claude/skills/doc-generator/SKILL.md

@@ -12,6 +12,7 @@ allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(node:*)
 - New files detected that change the tech stack (new framework, test runner, etc.)
 - After major refactoring that changes directory structure
 - When CLAUDE.md references files or directories that no longer exist
+- When `.mcp.json` is missing and the project has significant external dependencies
 
 ## Process
 
@@ -28,6 +29,7 @@ If CLAUDE.md already exists, read it and identify:
 
 ### 3. Generate or Update
 - For new documentation: generate CLAUDE.md, _state.md, .claude/rules/code-style.md, .claude/rules/testing.md, .claude/rules/workflow.md
+- For MCP configuration: suggest running `/setup-mcp` to search the MCP Registry and generate `.mcp.json`
 - For updates: propose specific changes and wait for user approval
 - Always present generated content for review before writing
 - NEVER create .md files beyond the ones listed above unless the user explicitly asks
@@ -54,3 +56,4 @@ Generated CLAUDE.md should follow this structure:
 Additionally generate:
 - `_state.md` — project state tracking (decisions, focus, known issues)
 - `.claude/rules/workflow.md` — Claude Code workflow best practices
+- `.mcp.json` — MCP server configuration (via `/setup-mcp`)

package/scaffold/.claude/skills/doc-generator/templates/mcp-servers.md

@@ -0,0 +1,168 @@
+# MCP Server Reference — Registry Search & Configuration
+
+## 1. How to Search the Registry
+
+The official MCP Registry API provides a searchable catalog of MCP servers. No authentication required.
+
+**Endpoint**: `GET https://registry.modelcontextprotocol.io/v0.1/servers`
+
+**Parameters**:
+- `search=<term>` — case-insensitive substring match on server names and descriptions
+- `version=latest` — return only the latest version of each server
+- `limit=<n>` — max results per page (default ~100)
+
+**Search strategy**:
+1. Analyze the project's tech stack from manifest files, configs, and source code
+2. Extract key technology names (languages, frameworks, databases, cloud services, tools)
+3. Search each technology individually — specific terms yield better results
+
+**Example searches**:
+```bash
+# Database
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=postgres&version=latest&limit=10'
+
+# Cloud provider
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=aws&version=latest&limit=10'
+
+# Monitoring
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=sentry&version=latest&limit=10'
+
+# Version control
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=github&version=latest&limit=10'
+```
+
+## 2. How to Evaluate and Trust Results
+
+### Primary trust signal: npm download counts
+
+For each candidate server that has an npm package, check monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package-name>'
+# Returns: { "downloads": N, "package": "...", ... }
+```
+
+- **Filter out** servers with <100 monthly downloads — likely unmaintained or experimental
+- **Prefer** servers with 10,000+ monthly downloads — well-established and community-trusted
+- **Strong signal** at 100,000+ downloads — widely adopted
+
+### Secondary trust signal: GitHub stars
+
+If the server has a repository URL, check GitHub stars:
+```bash
+curl -s 'https://api.github.com/repos/<owner>/<repo>'
+# Check the "stargazers_count" field
+```
+
+- Prefer repos with 100+ stars
+- Stars indicate community interest but downloads are a stronger usage signal
+
+### Additional evaluation criteria
+
+- **Prefer `packages` (npm/stdio) over `remotes` (hosted)** — stdio runs locally with no external dependency
+- **Prefer well-known namespaces**: `io.modelcontextprotocol/*`, `io.github.modelcontextprotocol/*` are official
+- **Read descriptions carefully** — pick servers that match the project's actual use case
+- **Skip** servers that appear to be forks, test entries, or clearly unmaintained
+- **When multiple servers exist for the same tech**, pick the one with highest npm downloads
+- **Check `environmentVariables`** — servers requiring many complex env vars may be harder to set up
+
+## 3. How to Build .mcp.json
+
+The `.mcp.json` file configures MCP servers for a project. It lives in the project root.
+
+**Root structure**:
+```json
+{
+  "mcpServers": {
+    "server-name": { ... }
+  }
+}
+```
+
+### stdio servers (npm packages)
+
+For servers with a `packages` entry of `registryType: "npm"`:
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "<package-identifier>@latest"],
+      "env": {
+        "VAR_NAME": "${VAR_NAME}"
+      }
+    }
+  }
+}
+```
+
+- Add any `packageArguments` with `type: "positional"` to the `args` array after the package name
+- Map `environmentVariables` to the `env` object
+- Use `${ENV_VAR}` placeholders for all variables with `isSecret: true`
+- Non-secret env vars can use literal values when the value is project-specific and non-sensitive
+
+### HTTP/SSE servers (remote)
+
+For servers with a `remotes` entry:
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "type": "streamable-http",
+      "url": "https://example.com/mcp"
+    }
+  }
+}
+```
+
+Use the `type` and `url` from the remote entry directly. Add `headers` if authentication is needed:
+```json
+{
+  "type": "streamable-http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${API_KEY}"
+  }
+}
+```
+
+## 4. Well-Known Servers
+
+These are hints to help find the best option when search results are noisy. Always verify via the registry API — these names and packages may change.
+
+| Technology | Search term | Known namespace | Notes |
+|---|---|---|---|
+| Library docs | `context7` | `io.github.upstash/context7` | Up-to-date docs for any library; useful for most projects |
+| GitHub | `github` | `io.github.modelcontextprotocol/github` | Repo management, PRs, issues |
+| PostgreSQL | `postgres` | `io.github.modelcontextprotocol/postgres` | Database queries; prefer read-only config |
+| Filesystem | `filesystem` | `io.github.modelcontextprotocol/filesystem` | Scoped file access |
+| Fetch | `fetch` | `io.github.modelcontextprotocol/fetch` | Web content retrieval |
+| Sentry | `sentry` | — | Error tracking integration |
+| Stripe | `stripe` | — | Payment API |
+| Docker | `docker` | — | Container management |
+| AWS | `aws` | — | Cloud services |
+| Redis | `redis` | — | Cache and data store |
+| MongoDB | `mongodb` | — | Document database |
+| Slack | `slack` | — | Team communication |
+| Linear | `linear` | — | Issue tracking |
+
+## 5. Security Rules
+
+### Secrets management
+- **NEVER** put actual secret values in `.mcp.json` — use `${ENV_VAR}` placeholders
+- Secret values go in `~/.claude.json` (user-level config, not committed to version control)
+- Tell the user how to configure each secret:
+  ```
+  claude config set env.VAR_NAME "actual-value"
+  ```
+
+### Safe to commit
+- `.mcp.json` is safe to commit to version control — it contains only placeholders, never real secrets
+- Add `.mcp.json` to the git commit alongside other Claude Code config files
+
+### Database safety
+- Prefer read-only database connection strings
+- If read-write access is needed, document this clearly in the recommendation
+
+### Principle of least privilege
+- Only recommend servers that the project actually needs
+- Prefer servers with narrow, well-defined capabilities over general-purpose ones

package/scaffold/global/.claude/commands/claudenv.md

@@ -1,6 +1,6 @@
 ---
 description: Set up Claude Code documentation for this project — analyze tech stack, generate CLAUDE.md, rules, hooks, commands, and skills
-allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(mkdir:*), Bash(cp:*), Bash(chmod:*)
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(mkdir:*), Bash(cp:*), Bash(chmod:*), Bash(curl:*)
 disable-model-invocation: true
 argument-hint: [--force]
 ---
@@ -105,13 +105,52 @@ cp ~/.claude/skills/claudenv/scaffold/.claude/commands/validate-docs.md .claude/
 cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/SKILL.md .claude/skills/doc-generator/SKILL.md
 cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/scripts/validate.sh .claude/skills/doc-generator/scripts/validate.sh
 cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/detection-patterns.md .claude/skills/doc-generator/templates/detection-patterns.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/mcp-servers.md .claude/skills/doc-generator/templates/mcp-servers.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/commands/setup-mcp.md .claude/commands/setup-mcp.md
 cp ~/.claude/skills/claudenv/scaffold/.claude/agents/doc-analyzer.md .claude/agents/doc-analyzer.md
 chmod +x .claude/skills/doc-generator/scripts/validate.sh
 ```
 
 If any file already exists, **skip it** unless `$ARGUMENTS` includes `--force`.
 
-## Phase 5: Validate
+## Phase 5: MCP Server Configuration
+
+Configure MCP servers for this project by searching the official MCP Registry.
+
+Read the MCP server reference:
+@~/.claude/skills/claudenv/templates/mcp-servers.md
+
+**5.1 Identify technologies to search for:**
+Based on your Phase 1 analysis, list the key technologies that might have MCP servers (databases, cloud services, APIs, dev tools).
+
+**5.2 Search the registry:**
+For each technology, query the MCP Registry API:
+```bash
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=<tech>&version=latest&limit=10'
+```
+
+**5.3 Verify trust:**
+For each candidate with an npm package, check monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package>'
+```
+Filter out servers with <100 monthly downloads.
+
+**5.4 Present recommendations:**
+Group as Essential / Recommended / Optional. For each, explain why it's relevant and show download counts.
+
+Ask the user which to configure. If `$ARGUMENTS` includes `--force`, auto-select Essential + Recommended.
+
+**5.5 Generate `.mcp.json`:**
+Write `.mcp.json` with selected servers using `${ENV_VAR}` placeholders for secrets. Follow the format in the MCP server reference.
+
+**5.6 List environment variables:**
+Tell the user how to configure required secrets:
+```
+claude config set env.VAR_NAME "your-value"
+```
+
+## Phase 6: Validate
 
 Run the validation script:
 ```bash
@@ -120,7 +159,7 @@ bash .claude/skills/doc-generator/scripts/validate.sh 2>&1 || true
 
 Fix any errors found.
 
-## Phase 6: Summary
+## Phase 7: Summary
 
 Print a summary of everything created:
 ```
@@ -136,15 +175,19 @@ Created:
   + .claude/commands/init-docs.md
   + .claude/commands/update-docs.md
   + .claude/commands/validate-docs.md
+  + .claude/commands/setup-mcp.md
   + .claude/skills/doc-generator/
   + .claude/agents/doc-analyzer.md
+  + .mcp.json (if MCP servers were configured)
 
 Available commands:
   /init-docs      — Regenerate documentation from scratch
   /update-docs    — Update docs when project changes
   /validate-docs  — Check documentation completeness
+  /setup-mcp      — Add or update MCP server configuration
 
 Next steps:
   1. Review and edit CLAUDE.md
-  2. git add .claude/ CLAUDE.md _state.md && git commit -m "Add Claude Code docs"
+  2. Configure any required MCP secrets: claude config set env.VAR_NAME "value"
+  3. git add .claude/ CLAUDE.md _state.md .mcp.json && git commit -m "Add Claude Code docs"
 ```

package/scaffold/global/.claude/commands/setup-mcp.md

@@ -0,0 +1,115 @@
+---
+description: Recommend and configure MCP servers based on project analysis
+allowed-tools: Read, Write, Glob, Grep, Bash(curl:*), Bash(find:*), Bash(cat:*)
+disable-model-invocation: true
+argument-hint: [--force]
+---
+
+# MCP Server Setup
+
+You are configuring MCP servers for this project. Analyze the tech stack, search the official MCP Registry, verify trust signals, and generate `.mcp.json`.
+
+## Step 1: Analyze the Project
+
+Understand what this project uses:
+
+**Read existing documentation:**
+- Read CLAUDE.md if it exists — it contains the tech stack summary
+- Read _state.md if it exists
+
+**Check for existing MCP config:**
+- Read `.mcp.json` if it exists — you will merge new entries, not overwrite
+
+**Scan manifest files:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "requirements.txt" \) -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/vendor/*" 2>/dev/null | head -20`
+
+**Scan framework and tooling configs:**
+!`find . -maxdepth 2 \( -name "tsconfig*.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "docker-compose.*" -o -name "Dockerfile" -o -name ".env*" -o -name "prisma" -o -name "drizzle.config.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+Read the manifest files you found. Identify:
+- Programming languages and frameworks
+- Databases (PostgreSQL, MongoDB, Redis, etc.)
+- Cloud services (AWS, GCP, Azure)
+- External APIs (Stripe, Sentry, etc.)
+- Dev tools (Docker, GitHub Actions, etc.)
+
+## Step 2: Search the MCP Registry
+
+Read the MCP server reference for search and evaluation guidance:
+@~/.claude/skills/claudenv/templates/mcp-servers.md
+
+For each major technology in the project, search the official MCP Registry API:
+```bash
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=<tech>&version=latest&limit=10'
+```
+
+For each candidate server with an npm package, verify trust by checking monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package>'
+```
+
+Optionally check GitHub stars for additional trust signal:
+```bash
+curl -s 'https://api.github.com/repos/<owner>/<repo>'
+```
+
+**Filtering rules:**
+- Remove servers with <100 monthly npm downloads
+- Rank by: npm downloads (primary) + GitHub stars (secondary) + description relevance
+- When multiple servers exist for the same technology, pick the one with the highest downloads
+
+## Step 3: Present Recommendations
+
+Group your recommendations into three tiers:
+
+**Essential** — servers that directly support the project's core technologies (e.g., PostgreSQL server for a project using PostgreSQL)
+
+**Recommended** — servers that enhance the development workflow (e.g., Context7 for library docs, GitHub for repo management)
+
+**Optional** — servers that could be useful but aren't critical (e.g., Fetch for web content, Docker if Docker is used occasionally)
+
+For each recommendation, explain:
+- **What it does** and why it's relevant to THIS project
+- **Monthly npm downloads** (trust signal)
+- **Environment variables required** and whether they need secrets
+
+Ask the user which servers to configure.
+
+If `$ARGUMENTS` includes `--force`, auto-select all Essential and Recommended servers.
+
+## Step 4: Generate .mcp.json
+
+Build the `.mcp.json` file with the selected servers following the format in the MCP server reference.
+
+**If `.mcp.json` already exists:**
+- Read it and parse the existing `mcpServers` entries
+- Merge new servers into the existing config — do NOT remove or overwrite existing entries
+- If a server key already exists, skip it (preserve the user's existing config)
+
+**Key rules:**
+- Use `${ENV_VAR}` placeholders for ALL secret environment variables — NEVER literal values
+- Non-secret env vars can use literal values when appropriate
+- Use `npx -y <package>@latest` for stdio/npm servers
+- Use the `type` and `url` from remotes for HTTP/SSE servers
+
+Write the `.mcp.json` file.
+
+## Step 5: Update CLAUDE.md
+
+If CLAUDE.md exists, add or update an `## MCP Servers` section listing the configured servers and what they do. Keep it concise — one line per server.
+
+If CLAUDE.md doesn't exist, skip this step and suggest running `/claudenv` first.
+
+## Step 6: Environment Variables
+
+List all required environment variables and how to configure them:
+
+```
+To configure secrets, run:
+  claude config set env.VAR_NAME "your-value"
+
+Required environment variables:
+  VAR_NAME — Description of what this is and where to get it
+```
+
+Remind the user that `.mcp.json` is safe to commit — it only contains placeholders, not actual secrets.

package/scaffold/global/.claude/skills/claudenv/SKILL.md

@@ -8,7 +8,9 @@ allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(mkdir:*)
 
 ## When to auto-trigger
 - CLAUDE.md does not exist in the project root
+- `.mcp.json` does not exist in a project that has CLAUDE.md
 - User mentions "documentation", "CLAUDE.md", "project setup", or "claudenv"
+- User mentions "MCP", "MCP servers", or "mcp.json"
 - User asks to configure Claude Code for their project
 - After major refactoring that changes directory structure
 
@@ -26,6 +28,9 @@ When working in a project with existing documentation, watch for:
 
 When changes are detected, suggest running `/update-docs`.
 
+### MCP Configuration
+When `.mcp.json` is missing in a project that already has CLAUDE.md, suggest running `/setup-mcp` to configure MCP servers. When the user mentions MCP servers, offer to run `/setup-mcp`.
+
 ### Validation
 After documentation changes, run the validation script:
 ```bash
@@ -37,6 +42,9 @@ bash .claude/skills/doc-generator/scripts/validate.sh 2>&1 || true
 For tech stack detection patterns, see:
 @~/.claude/skills/claudenv/templates/detection-patterns.md
 
+For MCP server search, evaluation, and configuration, see:
+@~/.claude/skills/claudenv/templates/mcp-servers.md
+
 ## Project-level scaffold
 
 The following files are available for installation into projects at `~/.claude/skills/claudenv/scaffold/`:
@@ -46,4 +54,6 @@ The following files are available for installation into projects at `~/.claude/s
 - `.claude/skills/doc-generator/SKILL.md` — Per-project doc generation skill
 - `.claude/skills/doc-generator/scripts/validate.sh` — Bash validation script
 - `.claude/skills/doc-generator/templates/detection-patterns.md` — Detection reference
+- `.claude/commands/setup-mcp.md` — MCP server recommendation and setup
+- `.claude/skills/doc-generator/templates/mcp-servers.md` — MCP registry reference
 - `.claude/agents/doc-analyzer.md` — Read-only analysis subagent

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/commands/setup-mcp.md

@@ -0,0 +1,115 @@
+---
+description: Recommend and configure MCP servers based on project analysis
+allowed-tools: Read, Write, Glob, Grep, Bash(curl:*), Bash(find:*), Bash(cat:*)
+disable-model-invocation: true
+argument-hint: [--force]
+---
+
+# MCP Server Setup
+
+You are configuring MCP servers for this project. Analyze the tech stack, search the official MCP Registry, verify trust signals, and generate `.mcp.json`.
+
+## Step 1: Analyze the Project
+
+Understand what this project uses:
+
+**Read existing documentation:**
+- Read CLAUDE.md if it exists — it contains the tech stack summary
+- Read _state.md if it exists
+
+**Check for existing MCP config:**
+- Read `.mcp.json` if it exists — you will merge new entries, not overwrite
+
+**Scan manifest files:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "requirements.txt" \) -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/vendor/*" 2>/dev/null | head -20`
+
+**Scan framework and tooling configs:**
+!`find . -maxdepth 2 \( -name "tsconfig*.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "docker-compose.*" -o -name "Dockerfile" -o -name ".env*" -o -name "prisma" -o -name "drizzle.config.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+Read the manifest files you found. Identify:
+- Programming languages and frameworks
+- Databases (PostgreSQL, MongoDB, Redis, etc.)
+- Cloud services (AWS, GCP, Azure)
+- External APIs (Stripe, Sentry, etc.)
+- Dev tools (Docker, GitHub Actions, etc.)
+
+## Step 2: Search the MCP Registry
+
+Read the MCP server reference for search and evaluation guidance:
+@.claude/skills/doc-generator/templates/mcp-servers.md
+
+For each major technology in the project, search the official MCP Registry API:
+```bash
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=<tech>&version=latest&limit=10'
+```
+
+For each candidate server with an npm package, verify trust by checking monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package>'
+```
+
+Optionally check GitHub stars for additional trust signal:
+```bash
+curl -s 'https://api.github.com/repos/<owner>/<repo>'
+```
+
+**Filtering rules:**
+- Remove servers with <100 monthly npm downloads
+- Rank by: npm downloads (primary) + GitHub stars (secondary) + description relevance
+- When multiple servers exist for the same technology, pick the one with the highest downloads
+
+## Step 3: Present Recommendations
+
+Group your recommendations into three tiers:
+
+**Essential** — servers that directly support the project's core technologies (e.g., PostgreSQL server for a project using PostgreSQL)
+
+**Recommended** — servers that enhance the development workflow (e.g., Context7 for library docs, GitHub for repo management)
+
+**Optional** — servers that could be useful but aren't critical (e.g., Fetch for web content, Docker if Docker is used occasionally)
+
+For each recommendation, explain:
+- **What it does** and why it's relevant to THIS project
+- **Monthly npm downloads** (trust signal)
+- **Environment variables required** and whether they need secrets
+
+Ask the user which servers to configure.
+
+If `$ARGUMENTS` includes `--force`, auto-select all Essential and Recommended servers.
+
+## Step 4: Generate .mcp.json
+
+Build the `.mcp.json` file with the selected servers following the format in the MCP server reference.
+
+**If `.mcp.json` already exists:**
+- Read it and parse the existing `mcpServers` entries
+- Merge new servers into the existing config — do NOT remove or overwrite existing entries
+- If a server key already exists, skip it (preserve the user's existing config)
+
+**Key rules:**
+- Use `${ENV_VAR}` placeholders for ALL secret environment variables — NEVER literal values
+- Non-secret env vars can use literal values when appropriate
+- Use `npx -y <package>@latest` for stdio/npm servers
+- Use the `type` and `url` from remotes for HTTP/SSE servers
+
+Write the `.mcp.json` file.
+
+## Step 5: Update CLAUDE.md
+
+If CLAUDE.md exists, add or update an `## MCP Servers` section listing the configured servers and what they do. Keep it concise — one line per server.
+
+If CLAUDE.md doesn't exist, skip this step and suggest running `/claudenv` first.
+
+## Step 6: Environment Variables
+
+List all required environment variables and how to configure them:
+
+```
+To configure secrets, run:
+  claude config set env.VAR_NAME "your-value"
+
+Required environment variables:
+  VAR_NAME — Description of what this is and where to get it
+```
+
+Remind the user that `.mcp.json` is safe to commit — it only contains placeholders, not actual secrets.

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/commands/update-docs.md

@@ -34,6 +34,7 @@ Compare the current state against the existing documentation:
 - **New directories** not covered in Architecture section
 - **Stale references** to files or directories that no longer exist
 - **Missing conventions** based on new config files (e.g., new linter added)
+- **Missing or outdated `.mcp.json`** — if `.mcp.json` doesn't exist, or if new technologies have been added that could benefit from MCP servers, suggest running `/setup-mcp`
 
 ## Step 4: Propose Updates
 

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/SKILL.md

@@ -12,6 +12,7 @@ allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(node:*)
 - New files detected that change the tech stack (new framework, test runner, etc.)
 - After major refactoring that changes directory structure
 - When CLAUDE.md references files or directories that no longer exist
+- When `.mcp.json` is missing and the project has significant external dependencies
 
 ## Process
 
@@ -28,6 +29,7 @@ If CLAUDE.md already exists, read it and identify:
 
 ### 3. Generate or Update
 - For new documentation: generate CLAUDE.md, _state.md, .claude/rules/code-style.md, .claude/rules/testing.md, .claude/rules/workflow.md
+- For MCP configuration: suggest running `/setup-mcp` to search the MCP Registry and generate `.mcp.json`
 - For updates: propose specific changes and wait for user approval
 - Always present generated content for review before writing
 - NEVER create .md files beyond the ones listed above unless the user explicitly asks
@@ -54,3 +56,4 @@ Generated CLAUDE.md should follow this structure:
 Additionally generate:
 - `_state.md` — project state tracking (decisions, focus, known issues)
 - `.claude/rules/workflow.md` — Claude Code workflow best practices
+- `.mcp.json` — MCP server configuration (via `/setup-mcp`)

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/mcp-servers.md

@@ -0,0 +1,168 @@
+# MCP Server Reference — Registry Search & Configuration
+
+## 1. How to Search the Registry
+
+The official MCP Registry API provides a searchable catalog of MCP servers. No authentication required.
+
+**Endpoint**: `GET https://registry.modelcontextprotocol.io/v0.1/servers`
+
+**Parameters**:
+- `search=<term>` — case-insensitive substring match on server names and descriptions
+- `version=latest` — return only the latest version of each server
+- `limit=<n>` — max results per page (default ~100)
+
+**Search strategy**:
+1. Analyze the project's tech stack from manifest files, configs, and source code
+2. Extract key technology names (languages, frameworks, databases, cloud services, tools)
+3. Search each technology individually — specific terms yield better results
+
+**Example searches**:
+```bash
+# Database
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=postgres&version=latest&limit=10'
+
+# Cloud provider
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=aws&version=latest&limit=10'
+
+# Monitoring
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=sentry&version=latest&limit=10'
+
+# Version control
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=github&version=latest&limit=10'
+```
+
+## 2. How to Evaluate and Trust Results
+
+### Primary trust signal: npm download counts
+
+For each candidate server that has an npm package, check monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package-name>'
+# Returns: { "downloads": N, "package": "...", ... }
+```
+
+- **Filter out** servers with <100 monthly downloads — likely unmaintained or experimental
+- **Prefer** servers with 10,000+ monthly downloads — well-established and community-trusted
+- **Strong signal** at 100,000+ downloads — widely adopted
+
+### Secondary trust signal: GitHub stars
+
+If the server has a repository URL, check GitHub stars:
+```bash
+curl -s 'https://api.github.com/repos/<owner>/<repo>'
+# Check the "stargazers_count" field
+```
+
+- Prefer repos with 100+ stars
+- Stars indicate community interest but downloads are a stronger usage signal
+
+### Additional evaluation criteria
+
+- **Prefer `packages` (npm/stdio) over `remotes` (hosted)** — stdio runs locally with no external dependency
+- **Prefer well-known namespaces**: `io.modelcontextprotocol/*`, `io.github.modelcontextprotocol/*` are official
+- **Read descriptions carefully** — pick servers that match the project's actual use case
+- **Skip** servers that appear to be forks, test entries, or clearly unmaintained
+- **When multiple servers exist for the same tech**, pick the one with highest npm downloads
+- **Check `environmentVariables`** — servers requiring many complex env vars may be harder to set up
+
+## 3. How to Build .mcp.json
+
+The `.mcp.json` file configures MCP servers for a project. It lives in the project root.
+
+**Root structure**:
+```json
+{
+  "mcpServers": {
+    "server-name": { ... }
+  }
+}
+```
+
+### stdio servers (npm packages)
+
+For servers with a `packages` entry of `registryType: "npm"`:
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "<package-identifier>@latest"],
+      "env": {
+        "VAR_NAME": "${VAR_NAME}"
+      }
+    }
+  }
+}
+```
+
+- Add any `packageArguments` with `type: "positional"` to the `args` array after the package name
+- Map `environmentVariables` to the `env` object
+- Use `${ENV_VAR}` placeholders for all variables with `isSecret: true`
+- Non-secret env vars can use literal values when the value is project-specific and non-sensitive
+
+### HTTP/SSE servers (remote)
+
+For servers with a `remotes` entry:
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "type": "streamable-http",
+      "url": "https://example.com/mcp"
+    }
+  }
+}
+```
+
+Use the `type` and `url` from the remote entry directly. Add `headers` if authentication is needed:
+```json
+{
+  "type": "streamable-http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${API_KEY}"
+  }
+}
+```
+
+## 4. Well-Known Servers
+
+These are hints to help find the best option when search results are noisy. Always verify via the registry API — these names and packages may change.
+
+| Technology | Search term | Known namespace | Notes |
+|---|---|---|---|
+| Library docs | `context7` | `io.github.upstash/context7` | Up-to-date docs for any library; useful for most projects |
+| GitHub | `github` | `io.github.modelcontextprotocol/github` | Repo management, PRs, issues |
+| PostgreSQL | `postgres` | `io.github.modelcontextprotocol/postgres` | Database queries; prefer read-only config |
+| Filesystem | `filesystem` | `io.github.modelcontextprotocol/filesystem` | Scoped file access |
+| Fetch | `fetch` | `io.github.modelcontextprotocol/fetch` | Web content retrieval |
+| Sentry | `sentry` | — | Error tracking integration |
+| Stripe | `stripe` | — | Payment API |
+| Docker | `docker` | — | Container management |
+| AWS | `aws` | — | Cloud services |
+| Redis | `redis` | — | Cache and data store |
+| MongoDB | `mongodb` | — | Document database |
+| Slack | `slack` | — | Team communication |
+| Linear | `linear` | — | Issue tracking |
+
+## 5. Security Rules
+
+### Secrets management
+- **NEVER** put actual secret values in `.mcp.json` — use `${ENV_VAR}` placeholders
+- Secret values go in `~/.claude.json` (user-level config, not committed to version control)
+- Tell the user how to configure each secret:
+  ```
+  claude config set env.VAR_NAME "actual-value"
+  ```
+
+### Safe to commit
+- `.mcp.json` is safe to commit to version control — it contains only placeholders, never real secrets
+- Add `.mcp.json` to the git commit alongside other Claude Code config files
+
+### Database safety
+- Prefer read-only database connection strings
+- If read-write access is needed, document this clearly in the recommendation
+
+### Principle of least privilege
+- Only recommend servers that the project actually needs
+- Prefer servers with narrow, well-defined capabilities over general-purpose ones

package/scaffold/global/.claude/skills/claudenv/templates/mcp-servers.md

@@ -0,0 +1,168 @@
+# MCP Server Reference — Registry Search & Configuration
+
+## 1. How to Search the Registry
+
+The official MCP Registry API provides a searchable catalog of MCP servers. No authentication required.
+
+**Endpoint**: `GET https://registry.modelcontextprotocol.io/v0.1/servers`
+
+**Parameters**:
+- `search=<term>` — case-insensitive substring match on server names and descriptions
+- `version=latest` — return only the latest version of each server
+- `limit=<n>` — max results per page (default ~100)
+
+**Search strategy**:
+1. Analyze the project's tech stack from manifest files, configs, and source code
+2. Extract key technology names (languages, frameworks, databases, cloud services, tools)
+3. Search each technology individually — specific terms yield better results
+
+**Example searches**:
+```bash
+# Database
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=postgres&version=latest&limit=10'
+
+# Cloud provider
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=aws&version=latest&limit=10'
+
+# Monitoring
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=sentry&version=latest&limit=10'
+
+# Version control
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=github&version=latest&limit=10'
+```
+
+## 2. How to Evaluate and Trust Results
+
+### Primary trust signal: npm download counts
+
+For each candidate server that has an npm package, check monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package-name>'
+# Returns: { "downloads": N, "package": "...", ... }
+```
+
+- **Filter out** servers with <100 monthly downloads — likely unmaintained or experimental
+- **Prefer** servers with 10,000+ monthly downloads — well-established and community-trusted
+- **Strong signal** at 100,000+ downloads — widely adopted
+
+### Secondary trust signal: GitHub stars
+
+If the server has a repository URL, check GitHub stars:
+```bash
+curl -s 'https://api.github.com/repos/<owner>/<repo>'
+# Check the "stargazers_count" field
+```
+
+- Prefer repos with 100+ stars
+- Stars indicate community interest but downloads are a stronger usage signal
+
+### Additional evaluation criteria
+
+- **Prefer `packages` (npm/stdio) over `remotes` (hosted)** — stdio runs locally with no external dependency
+- **Prefer well-known namespaces**: `io.modelcontextprotocol/*`, `io.github.modelcontextprotocol/*` are official
+- **Read descriptions carefully** — pick servers that match the project's actual use case
+- **Skip** servers that appear to be forks, test entries, or clearly unmaintained
+- **When multiple servers exist for the same tech**, pick the one with highest npm downloads
+- **Check `environmentVariables`** — servers requiring many complex env vars may be harder to set up
+
+## 3. How to Build .mcp.json
+
+The `.mcp.json` file configures MCP servers for a project. It lives in the project root.
+
+**Root structure**:
+```json
+{
+  "mcpServers": {
+    "server-name": { ... }
+  }
+}
+```
+
+### stdio servers (npm packages)
+
+For servers with a `packages` entry of `registryType: "npm"`:
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "<package-identifier>@latest"],
+      "env": {
+        "VAR_NAME": "${VAR_NAME}"
+      }
+    }
+  }
+}
+```
+
+- Add any `packageArguments` with `type: "positional"` to the `args` array after the package name
+- Map `environmentVariables` to the `env` object
+- Use `${ENV_VAR}` placeholders for all variables with `isSecret: true`
+- Non-secret env vars can use literal values when the value is project-specific and non-sensitive
+
+### HTTP/SSE servers (remote)
+
+For servers with a `remotes` entry:
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "type": "streamable-http",
+      "url": "https://example.com/mcp"
+    }
+  }
+}
+```
+
+Use the `type` and `url` from the remote entry directly. Add `headers` if authentication is needed:
+```json
+{
+  "type": "streamable-http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${API_KEY}"
+  }
+}
+```
+
+## 4. Well-Known Servers
+
+These are hints to help find the best option when search results are noisy. Always verify via the registry API — these names and packages may change.
+
+| Technology | Search term | Known namespace | Notes |
+|---|---|---|---|
+| Library docs | `context7` | `io.github.upstash/context7` | Up-to-date docs for any library; useful for most projects |
+| GitHub | `github` | `io.github.modelcontextprotocol/github` | Repo management, PRs, issues |
+| PostgreSQL | `postgres` | `io.github.modelcontextprotocol/postgres` | Database queries; prefer read-only config |
+| Filesystem | `filesystem` | `io.github.modelcontextprotocol/filesystem` | Scoped file access |
+| Fetch | `fetch` | `io.github.modelcontextprotocol/fetch` | Web content retrieval |
+| Sentry | `sentry` | — | Error tracking integration |
+| Stripe | `stripe` | — | Payment API |
+| Docker | `docker` | — | Container management |
+| AWS | `aws` | — | Cloud services |
+| Redis | `redis` | — | Cache and data store |
+| MongoDB | `mongodb` | — | Document database |
+| Slack | `slack` | — | Team communication |
+| Linear | `linear` | — | Issue tracking |
+
+## 5. Security Rules
+
+### Secrets management
+- **NEVER** put actual secret values in `.mcp.json` — use `${ENV_VAR}` placeholders
+- Secret values go in `~/.claude.json` (user-level config, not committed to version control)
+- Tell the user how to configure each secret:
+  ```
+  claude config set env.VAR_NAME "actual-value"
+  ```
+
+### Safe to commit
+- `.mcp.json` is safe to commit to version control — it contains only placeholders, never real secrets
+- Add `.mcp.json` to the git commit alongside other Claude Code config files
+
+### Database safety
+- Prefer read-only database connection strings
+- If read-write access is needed, document this clearly in the recommendation
+
+### Principle of least privilege
+- Only recommend servers that the project actually needs
+- Prefer servers with narrow, well-defined capabilities over general-purpose ones