claudenv 1.0.1 → 1.1.0

package/README.md

@@ -1,103 +1,77 @@
 # claudenv
 
-One command to set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) documentation for any project.
+One command to set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in any project. Claude AI analyzes your codebase and generates all the documentation it needs to work effectively.
 
-## Installation
-
-Run directly without installing — pick your package manager:
+## Quick Start
 
 ```bash
-npx claudenv          # npm
-pnpm dlx claudenv     # pnpm
-bunx claudenv         # bun
-yarn dlx claudenv     # yarn
+npm i -g claudenv && claudenv
 ```
 
-Or install globally:
+Done. Open Claude Code in any project and type `/claudenv`.
 
-```bash
-npm i -g claudenv
-```
+## How It Works
 
-## Quick start
+**One-time setup** — install and activate:
 
 ```bash
-cd your-project
-npx claudenv
+npm i -g claudenv && claudenv
 ```
 
-Scans your project, detects the tech stack, asks a few questions, and generates everything Claude Code needs to understand your codebase.
+This installs the `/claudenv` command globally into `~/.claude/`, making it available in every project.
 
-Skip the questions with `-y`:
+**In any project** — open Claude Code and type `/claudenv`.
 
-```bash
-npx claudenv -y
-```
-
-## Usage in Claude Code
+Claude AI will:
+1. Read your manifest files, configs, and source code
+2. Detect your tech stack, frameworks, and tooling
+3. Ask you about the project (description, deployment, conventions)
+4. Generate all documentation files
+5. Install slash commands for ongoing maintenance
 
-### Option A: Global install + shell command
+**Step 3.** You now have three commands available in Claude Code:
 
-```bash
-npm i -g claudenv
-# Then inside Claude Code, just run:
-claudenv
-```
-
-### Option B: Slash command (auto-installed)
-
-After running `claudenv` in your project, the `.claude/commands/init-docs.md` file is created. This gives you the `/init-docs` slash command inside Claude Code, which does the same thing — analyzes the project and generates documentation.
+| Command | What it does |
+|---------|-------------|
+| `/init-docs` | Regenerate documentation from scratch |
+| `/update-docs` | Scan for changes and propose updates |
+| `/validate-docs` | Check that documentation is complete and correct |
 
-## What gets generated
+## What Gets Generated
 
 ```
 your-project/
-├── CLAUDE.md                          # Project overview, commands, architecture
-├── _state.md                          # Track decisions and context across sessions
-├── .claude/
-│   ├── rules/
-│   │   ├── code-style.md              # Coding conventions (scoped by file paths)
-│   │   ├── testing.md                 # Testing patterns and commands
-│   │   └── workflow.md                # Claude Code best practices
-│   ├── settings.json                  # Validation hooks
-│   ├── commands/
-│   │   ├── init-docs.md               # /init-docs — regenerate docs interactively
-│   │   ├── update-docs.md             # /update-docs — refresh from current state
-│   │   └── validate-docs.md           # /validate-docs — check docs are correct
-│   ├── skills/
-│   │   └── doc-generator/             # Auto-invoked when docs need updating
-│   │       ├── SKILL.md
-│   │       ├── scripts/validate.sh
-│   │       └── templates/detection-patterns.md
-│   └── agents/
-│       └── doc-analyzer.md            # Read-only analysis subagent
+├── CLAUDE.md                              # Project overview, commands, architecture
+├── _state.md                              # Session memory (decisions, focus, issues)
+└── .claude/
+    ├── rules/
+    │   ├── code-style.md                  # Coding conventions (scoped by file paths)
+    │   ├── testing.md                     # Test patterns and commands
+    │   └── workflow.md                    # Claude Code best practices
+    ├── settings.json                      # Validation hooks
+    ├── commands/
+    │   ├── init-docs.md                   # /init-docs
+    │   ├── update-docs.md                 # /update-docs
+    │   └── validate-docs.md              # /validate-docs
+    ├── skills/
+    │   └── doc-generator/                 # Auto-triggers when docs need updating
+    └── agents/
+        └── doc-analyzer.md                # Read-only analysis subagent
 ```
 
-### Key files
+### Key Files
 
 | File | Purpose |
 |------|---------|
-| `CLAUDE.md` | Compact project overview (< 60 lines) with `@import` references to rule files |
-| `_state.md` | Tracks current focus, key decisions, known issues — persists context between sessions |
-| `.claude/rules/workflow.md` | Best practices: plan mode, `/compact`, `/clear`, subagents, git discipline |
+| `CLAUDE.md` | Compact project overview with `@import` references to rule files |
+| `_state.md` | Persists context between sessions — current focus, decisions, known issues |
+| `.claude/rules/workflow.md` | Best practices: plan mode, `/compact`, subagents, git discipline |
 | `.claude/rules/code-style.md` | Language and framework-specific coding conventions |
 | `.claude/rules/testing.md` | Test framework patterns and commands |
 
-## After setup
+## Tech Stack Detection
 
-Inside Claude Code, you get three slash commands:
-
-| Command | What it does |
-|---------|-------------|
-| `/init-docs` | Re-run interactive documentation setup |
-| `/update-docs` | Scan for changes and propose doc updates |
-| `/validate-docs` | Check that documentation is complete and correct |
-
-The `doc-generator` skill auto-triggers when Claude detects your docs are outdated.
-
-## What it detects
-
-**10+ languages** and **25+ frameworks** out of the box:
+Claude AI reads your actual code, but the following are auto-detected for context:
 
 - **Languages**: TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Java, Kotlin, C#
 - **Frameworks**: Next.js, Vite, Nuxt, SvelteKit, Astro, Angular, Django, FastAPI, Flask, Rails, Laravel, Spring Boot, and more
@@ -106,51 +80,39 @@ The `doc-generator` skill auto-triggers when Claude detects your docs are outdat
 - **CI/CD**: GitHub Actions, GitLab CI, Jenkins, CircleCI
 - **Linters/formatters**: ESLint, Biome, Prettier, Ruff, RuboCop, golangci-lint, Clippy
 
-## CLI reference
+## CLI Reference
 
 ```
-Usage: claudenv [dir] [options]
-
-Options:
-  -y, --yes        Skip prompts, use auto-detected defaults
-  --overwrite      Overwrite existing files
-  -V, --version    Show version
-  -h, --help       Show help
-
-Commands:
-  init [dir]       Interactive setup (default when no command given)
-  generate         Non-interactive generation (templates only)
-  validate         Check documentation completeness
+claudenv                Install /claudenv into ~/.claude/ (default)
+claudenv install        Same as above (explicit)
+claudenv install -f     Reinstall, overwriting existing files
+claudenv uninstall      Remove /claudenv from ~/.claude/
+claudenv init [dir]     Legacy: static analysis + terminal prompts (no AI)
+claudenv init -y        Legacy: skip prompts, auto-detect everything
+claudenv generate       Templates only, no scaffold
+claudenv validate       Check documentation completeness
 ```
 
-## Install from source
+## Alternative: Run Without Installing
 
 ```bash
-git clone https://github.com/AGoldian/claudenv.git
-cd claudenv
-npm install
-npm link
-
-# Then in any project:
-claudenv
+npx claudenv            # npm
+pnpm dlx claudenv       # pnpm
+bunx claudenv           # bun
 ```
 
-## Programmatic API
-
-```javascript
-import { detectTechStack, generateDocs, writeDocs, installScaffold } from 'claudenv';
+## Uninstall
 
-const detected = await detectTechStack('/path/to/project');
-const { files } = await generateDocs('/path/to/project', {
-  ...detected,
-  projectDescription: 'My awesome project',
-  generateRules: true,
-  generateHooks: true,
-});
-await writeDocs('/path/to/project', files);
-await installScaffold('/path/to/project');
+```bash
+claudenv uninstall      # Remove from ~/.claude/
+npm uninstall -g claudenv
 ```
 
+## Requirements
+
+- Node.js >= 20
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
+
 ## License
 
 MIT

package/bin/cli.js

@@ -9,6 +9,7 @@ import { detectTechStack } from '../src/detector.js';
 import { generateDocs, writeDocs, installScaffold } from '../src/generator.js';
 import { validateClaudeMd, validateStructure, crossReferenceCheck } from '../src/validator.js';
 import { runExistingProjectFlow, runColdStartFlow, buildDefaultConfig } from '../src/prompts.js';
+import { installGlobal, uninstallGlobal } from '../src/installer.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgJson = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -20,17 +21,28 @@ program
   .description('One command to set up Claude Code documentation for any project')
   .version(pkgJson.version);
 
-// --- Default action: running without subcommand triggers init ---
+// --- Default action: install global Claude Code command ---
 program
-  .argument('[dir]', 'Project directory', '.')
-  .option('-y, --yes', 'Skip prompts, use auto-detected defaults')
-  .option('--overwrite', 'Overwrite existing files')
-  .action(runInit);
+  .option('-f, --force', 'Overwrite existing files')
+  .action(runInstall);
 
-// --- init (explicit subcommand, same logic) ---
+// --- install (explicit subcommand, same logic) ---
+program
+  .command('install')
+  .description('Install /claudenv command globally into ~/.claude/')
+  .option('-f, --force', 'Overwrite existing files')
+  .action(runInstall);
+
+// --- uninstall ---
+program
+  .command('uninstall')
+  .description('Remove /claudenv command from ~/.claude/')
+  .action(runUninstall);
+
+// --- init (legacy static flow for backward compatibility) ---
 program
   .command('init')
-  .description('Interactive setup — detect stack, ask questions, generate docs')
+  .description('Legacy: static analysis + interactive setup (no Claude AI)')
   .argument('[dir]', 'Project directory', '.')
   .option('-y, --yes', 'Skip prompts, use auto-detected defaults')
   .option('--overwrite', 'Overwrite existing files')
@@ -102,7 +114,56 @@ program
   });
 
 // =============================================
-// Main init logic
+// Install / Uninstall
+// =============================================
+async function runInstall(opts) {
+  console.log(`\n  claudenv v${pkgJson.version}\n`);
+  console.log('  Installing Claude Code integration...\n');
+
+  const force = opts.force || false;
+  const { written, skipped } = await installGlobal({ force });
+
+  if (written.length > 0) {
+    console.log(`  Installed ${written.length} file(s) to ~/.claude/:\n`);
+    for (const f of written) console.log(`    + ${f}`);
+  }
+
+  if (skipped.length > 0) {
+    console.log(`\n  Skipped ${skipped.length} existing file(s) (use --force to overwrite):\n`);
+    for (const f of skipped) console.log(`    ~ ${f}`);
+  }
+
+  if (written.length === 0 && skipped.length > 0) {
+    console.log('\n  Already installed. Use --force to reinstall.');
+  }
+
+  console.log(`
+  Done! Now open Claude Code in any project and type:
+
+    /claudenv
+
+  Claude will analyze your project and generate documentation.
+`);
+}
+
+async function runUninstall() {
+  console.log(`\n  claudenv v${pkgJson.version}\n`);
+  console.log('  Removing Claude Code integration...\n');
+
+  const { removed } = await uninstallGlobal();
+
+  if (removed.length > 0) {
+    console.log(`  Removed ${removed.length} item(s) from ~/.claude/:\n`);
+    for (const f of removed) console.log(`    - ${f}`);
+  } else {
+    console.log('  Nothing to remove — not installed.');
+  }
+
+  console.log();
+}
+
+// =============================================
+// Legacy init logic
 // =============================================
 async function runInit(dirArg, opts) {
   // Commander passes (dir, opts) for arguments, or (opts) for options-only

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claudenv",
-  "version": "1.0.1",
-  "description": "One command to set up Claude Code documentation for any project — detects tech stack, generates CLAUDE.md, rules, hooks, commands, and skills",
+  "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": {
     "claudenv": "./bin/cli.js"
@@ -23,17 +23,17 @@
     "prepublishOnly": "vitest run"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.0.0",
-    "commander": "^13.0.0",
-    "ejs": "^3.1.10",
-    "glob": "^11.0.0",
+    "@inquirer/prompts": "^8.0.0",
+    "commander": "^14.0.0",
+    "ejs": "^4.0.0",
+    "glob": "^13.0.0",
     "smol-toml": "^1.3.0"
   },
   "devDependencies": {
-    "vitest": "^3.0.0"
+    "vitest": "^4.0.0"
   },
   "keywords": [
     "claude",

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