{"_id":"@ai-architecture-cookbook/mcp-server","_rev":"2-6885b2e443f9a7fbec30be3480f88f4f","name":"@ai-architecture-cookbook/mcp-server","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"@ai-architecture-cookbook/mcp-server","version":"1.0.1","license":"MIT","_id":"@ai-architecture-cookbook/mcp-server@1.0.1","maintainers":[{"name":"mbg9999","email":"miguel.belmonte99@gmail.com"}],"bin":{"cookbook-mcp":"mcp-server/dist/server.js"},"dist":{"shasum":"b2ea4b1c11e64efeedfc50a25aa496e71cb1f7a8","tarball":"https://registry.npmjs.org/@ai-architecture-cookbook/mcp-server/-/mcp-server-1.0.1.tgz","fileCount":198,"integrity":"sha512-9VYSP4F3X2Kbl2lwyJ3rFxqCeFkOD2hFPwOfo7POGhbRrVNOy9Qtk3bt6jqwqniLMeASK+Tf1xyXTKAQ5NsPbQ==","signatures":[{"sig":"MEQCIHI8BkG/83z1OVy5mI/h51iqOEG8sO5yyFdpzRP/L6YKAiAsTcfTNHLTIKCbomP9mHwIJN2KiU5tkhrNwpP267kOHA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3419145},"main":"mcp-server/dist/server.js","type":"module","types":"./mcp-server/dist/server.d.ts","engines":{"node":">=18"},"gitHead":"5fa607b38ae815966eb274180980e6425aa6d347","scripts":{"dev":"tsx mcp-server/src/server.ts","test":"tsx mcp-server/test/runner.ts","build":"tsc -p mcp-server/tsconfig.build.json","start":"node mcp-server/dist/server.js","test:tsc":"tsc -p mcp-server/tsconfig.test.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"mbg9999","email":"miguel.belmonte99@gmail.com"},"_npmVersion":"10.9.3","description":"MCP server exposing AI Architecture Cookbook standards via 10+ MCP tools","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.24.4","js-yaml":"^4.1.0","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.4","rimraf":"^6.0.1","typescript":"^5.8.3","@types/node":"^22.19.17","@types/js-yaml":"^4.0.9"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_1.0.1_1781018261091_0.30737535012621997","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@ai-architecture-cookbook/mcp-server","version":"1.0.2","description":"MCP server exposing AI Architecture Cookbook standards via 10+ MCP tools","license":"MIT","type":"module","main":"mcp-server/dist/server.js","bin":{"cookbook-mcp":"mcp-server/dist/server.js"},"scripts":{"build":"tsc -p mcp-server/tsconfig.build.json","start":"node mcp-server/dist/server.js","dev":"tsx mcp-server/src/server.ts","test":"tsx mcp-server/test/runner.ts","test:tsc":"tsc -p mcp-server/tsconfig.test.json","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","js-yaml":"^4.1.0","zod":"^3.24.4"},"devDependencies":{"@types/js-yaml":"^4.0.9","@types/node":"^22.19.17","rimraf":"^6.0.1","tsx":"^4.19.4","typescript":"^5.8.3"},"engines":{"node":">=18"},"_id":"@ai-architecture-cookbook/mcp-server@1.0.2","gitHead":"ec204bfc9822ebe6f993c114c3deefb1701b4584","types":"./mcp-server/dist/server.d.ts","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-oQkd1BqXmYSCJ9Y1Q/nwjwgCRZ+CQf7VTF84R0t1CjLjkiCu7i7Z4poSl/jL0PzzxhnvjyBlW0JSrmok/O3LCg==","shasum":"93e2fb66cb1d34b5de5b26ffbec3a5d34f5311c7","tarball":"https://registry.npmjs.org/@ai-architecture-cookbook/mcp-server/-/mcp-server-1.0.2.tgz","fileCount":198,"unpackedSize":3430498,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCoyj0BWwEIrZLkjPXxA10wQXs44u020DKuF9tOOqru2wIgXBLcrDlFnDREu/u0WZJfYjJdih017sbJxZto4RsExG8="}]},"_npmUser":{"name":"mbg9999","email":"miguel.belmonte99@gmail.com"},"directories":{},"maintainers":[{"name":"mbg9999","email":"miguel.belmonte99@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_1.0.2_1781123922827_0.820139144609646"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-09T15:17:40.928Z","modified":"2026-06-10T20:38:43.171Z","1.0.1":"2026-06-09T15:17:41.393Z","1.0.2":"2026-06-10T20:38:43.013Z"},"license":"MIT","description":"MCP server exposing AI Architecture Cookbook standards via 10+ MCP tools","maintainers":[{"name":"mbg9999","email":"miguel.belmonte99@gmail.com"}],"readme":"# AI Architecture Cookbook\n\nStrongly opinionated architectural standards for AI code assistants. 44 domain-specific decision frameworks covering authentication, API design, containerization, encryption, testing, and more — each with context-aware decision trees, implementation patterns, anti-patterns, security hardening, and verification checklists.\n\nThese standards are primarily aimed at enterprise-level architectures and operational scenarios.\n\n## Why?\n\nThis cookbook makes architectural knowledge explicit and machine-readable so AI assistants can make consistent, auditable architecture decisions.\n\n- **Help models pick the right architecture:** The decision trees and patterns let an assistant evaluate trade-offs (e.g., REST vs GraphQL, monolith vs microservices) against project constraints and recommend concrete architectures.\n- **Lower the barrier for users:** Teams or developers who aren't architecture experts can get practical, contextual guidance automatically — the model encodes the reasoning and rationale so users don't need deep architectural knowledge to get sound recommendations.\n- **Empower smaller or simpler models:** By exposing structured decision inputs and checklists, less-capable models (or tool-driven pipelines) can follow a deterministic process to reach good recommendations without requiring high-end reasoning in a single pass.\n\nOther benefits and possibilities:\n\n- **Automated verification:** Use the `get_checklist` tool to generate verifiable acceptance criteria and CI checks that ensure designs meet security and operational requirements.\n- **Onboarding & documentation:** Generate human-friendly explanations, trade-off summaries, and architecture diagrams from the same canonical standards to speed team ramp-up.\n- **Governance & compliance:** Encode organization policies (naming, encryption, secrets handling) as rules so assistants recommend only compliant options.\n- **Audit trails & reproducibility:** Tool calls and decision-tree inputs create a traceable record of why a recommendation was made, useful for reviews and postmortems.\n- **Training and feedback loops:** Use real project contexts and outcomes to refine standards over time, improving recommendations and reducing false positives.\n- **Tooling integration:** Integrate recommendations into code-review bots, scaffold generators, or CI pipelines to automate safe architecture scaffolding and guardrails.\n\nIn short: machine-readable standards turn subjective \"best practice\" advice into repeatable, verifiable decisions that scale across users, models, and tooling.\n\n## Quick Start\n\nClone and run the setup script — it optionally installs a pre-commit validation hook:\n\n```bash\n# macOS / Linux\ngit clone <repo-url> && cd AI-Architecture-Cookbook\n./scripts/setup.sh\n```\n\n```powershell\n# Windows (PowerShell)\ngit clone <repo-url>; cd AI-Architecture-Cookbook\n.\\scripts\\setup.ps1\n```\n\nYou can also request recipes by query or ask for a machine-friendly snippet:\n\n\n```cmd\nREM Windows (cmd)\ngit clone <repo-url> && cd AI-Architecture-Cookbook\nscripts\\setup.bat\n```\n\nMost AI assistants will **auto-discover the MCP server** on open — no manual configuration needed:\n\n| Client | Auto-Discovery File | Custom Instructions |\n|--------|---------------------|---------------------|\n| GitHub Copilot (VS Code) | `.vscode/mcp.json` | `.github/copilot-instructions.md` |\n| Claude Code | `.mcp.json` | `CLAUDE.md` |\n| Cursor | `.cursor/mcp.json` | `.cursorrules` |\n| Windsurf | *(manual — see below)* | `.windsurfrules` |\n| Cline | *(manual — see below)* | *(uses CLAUDE.md format)* |\n\n> **Note**: Windsurf and Cline require manual MCP config — see their setup sections below.\n\nChoose an integration method for more detail:\n\n### Option 1: MCP Server (richest experience)\n\nThe server is published on npm. Use via **npx** — no local build needed:\n\n```bash\nnpx -y @ai-architecture-cookbook/mcp-server\n```\n\nAll client configurations below use `npx -y @ai-architecture-cookbook/mcp-server` as the command.\nIf you prefer to build from source, see [mcp-server/README.md](mcp-server/README.md).\n\nThen configure your AI assistant:\n\n#### Smoke test (quick verification)\n\nRun the server to verify it starts:\n\n```bash\nnpx -y @ai-architecture-cookbook/mcp-server\n```\n\nThe server prints `MCP server running` to stderr and waits for MCP stdio messages.\n\n#### Environment and requirements\n\n- Node: >=18 (recommended LTS)\n- npm: latest compatible with Node 18+\n- Python: 3.9+ for the `tools/validate.py` script (optional dev tooling)\n\n#### Python (recommended venv workflow)\n\nUse a virtual environment for the repository's Python tools and prompts:\n\n```bash\n# create a venv in the repo\npython3 -m venv .venv\n\n# macOS / Linux\nsource .venv/bin/activate\n\n# Windows (PowerShell)\n.venv\\Scripts\\Activate.ps1\n\n# Windows (cmd)\n.venv\\Scripts\\activate.bat\n\n# Upgrade pip and install dependencies from the repo requirements\npython -m pip install --upgrade pip\npython -m pip install -r requirements.txt\n\n# Or install just the validator deps\npython -m pip install pyyaml jsonschema\n\n# When finished\ndeactivate\n```\n\nNotes:\n- `requirements.txt` (repo root) is kept for the Python dev tooling; using `-r requirements.txt` installs all pinned versions.\n- If you prefer `pipx` for isolated CLI tools, install the validator there instead of a venv.\n\n#### JSON vs natural-language in clients\n\n- Many MCP clients accept either: (A) a natural-language prompt that instructs the assistant to call a tool, or (B) a direct \"Call tool\" action where you provide the tool name and a JSON input object.\n- If your client exposes a direct tool call UI, paste the JSON object from the examples. If using a chat-style interface, paste the natural-language example.\n\n\n<details>\n<summary><strong>GitHub Copilot (VS Code)</strong></summary>\n\nCreate `.vscode/mcp.json` in your project root:\n```json\n{\n  \"servers\": {\n    \"ai-architecture-cookbook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ai-architecture-cookbook/mcp-server\"]\n    }\n  }\n}\n```\nThen in VS Code: `Cmd+Shift+P` → **MCP: List Servers** → Start the server.\nUse **Copilot Chat in Agent mode** to call the tools automatically.\n\n</details>\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\nRun from the repo root:\n```bash\nclaude mcp add ai-architecture-cookbook npx -y @ai-architecture-cookbook/mcp-server\n```\n\nOr add manually to `.mcp.json` in your project root:\n```json\n{\n  \"mcpServers\": {\n    \"ai-architecture-cookbook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ai-architecture-cookbook/mcp-server\"]\n    }\n  }\n}\n```\n\nFor global access across all projects, add to `~/.claude/mcp.json`.\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n```json\n{\n  \"mcpServers\": {\n    \"ai-architecture-cookbook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ai-architecture-cookbook/mcp-server\"]\n    }\n  }\n}\n```\nRestart Claude Desktop after saving.\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nCreate `.cursor/mcp.json` in your project root:\n```json\n{\n  \"mcpServers\": {\n    \"ai-architecture-cookbook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ai-architecture-cookbook/mcp-server\"]\n    }\n  }\n}\n```\nOr configure globally in **Cursor Settings → MCP**.\n\n</details>\n\n<details>\n<summary><strong>Windsurf (Codeium)</strong></summary>\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"ai-architecture-cookbook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ai-architecture-cookbook/mcp-server\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Cline (VS Code extension)</strong></summary>\n\nOpen Cline settings → **MCP Servers** → **Add** and use:\n- **Name**: `ai-architecture-cookbook`\n- **Command**: `npx`\n- **Args**: `-y @ai-architecture-cookbook/mcp-server`\n\nOr edit `cline_mcp_settings.json` directly with the same `mcpServers` format as Claude.\n\n</details>\n\n<details>\n<summary><strong>OpenCode / other MCP clients</strong></summary>\n\nAny MCP-compatible client can connect via stdio. The general config pattern:\n```json\n{\n  \"mcpServers\": {\n    \"ai-architecture-cookbook\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ai-architecture-cookbook/mcp-server\"]\n    }\n  }\n}\n```\nConsult your client's documentation for the config file location.\n\n</details>\n\n#### Available MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `query_standard` | Get full details for a specific standard |\n| `search_standards` | Search by tags, categories, or free text |\n| `get_checklist` | Get verification checklist (filterable by severity) |\n| `get_decision_tree` | Get decision tree and context inputs |\n| `recommend_pattern` | Provide project context, get pattern recommendations |\n\n### Example MCP Prompts\n\nBelow are example prompts you can send to an AI assistant connected to the MCP server (for example, Copilot Chat, Claude Code, or Cursor). These prompts instruct the assistant to call the cookbook MCP tools (`query_standard`, `search_standards`, `get_checklist`, `get_decision_tree`, `recommend_pattern`). Adjust the `domain`, `category`, or `context` fields to match your query.\n\n- Get a full standard (YAML):\n\n```text\nCall the tool `query_standard` with input: { \"domain\": \"authentication\", \"category\": \"foundational\" } and return the YAML content for that standard.\n```\n\n- Search for standards by keyword or tag:\n\n```text\nCall the tool `search_standards` with input: { \"query\": \"OAuth\", \"tags\": [\"authentication\"] } and summarize the top matches (domain, category, short description).\n```\n\n- Retrieve a checklist filtered by severity:\n\n```text\nCall the tool `get_checklist` with input: { \"domain\": \"authentication\", \"severity\": \"critical\" } and list the checklist items and their severity.\n```\n\n- Ask for decision-tree inputs or the full decision tree:\n\n```text\nCall the tool `get_decision_tree` with input: { \"domain\": \"api-design\" } and return the decision tree nodes and required context inputs.\n```\n\n- Request pattern recommendations for a project context:\n\n```text\nCall the tool `recommend_pattern` with input: { \"context\": { \"scale\": \"enterprise\", \"client_types\": [\"web\", \"mobile\"], \"needs_login\": true } } and return the top 3 recommended patterns with brief rationale.\n```\n\n- Natural-language (chat) example — ask in plain English and let the assistant call the tool for you:\n\n```text\nRecommend the top 3 architecture patterns for an enterprise web+mobile application that requires user login and has real-time features; give a one-line rationale for each.\n```\n\nIf your client supports direct tool calls, you can call the natural-language wrapper explicitly:\n\n```text\nCall the tool `recommend_pattern_nl` with input: { \"text\": \"Recommend the top 3 architecture patterns for an enterprise web+mobile application that requires user login and has real-time features.\" }\n```\n\nThese examples are ready to copy-paste into an assistant prompt when the MCP server is connected. The assistant will call the requested MCP tool and return structured results.\n\n#### Calling from specific clients\n\nBelow are concise, copy-paste examples tailored to popular MCP clients. First ensure the MCP server is configured and running (see Option 1). Then paste the shown prompt into the client chat or command box.\n\n- GitHub Copilot (VS Code)\n\n  - Ensure you added the server to `.vscode/mcp.json` and started it via **MCP: List Servers**.\n  - In Copilot Chat (Agent mode), paste:\n\n  ```text\n  Call the tool `query_standard` with input: { \"domain\": \"authentication\", \"category\": \"foundational\" } and return the YAML content.\n  ```\n\n- Claude Code / Claude Desktop\n\n  - After `claude mcp add` (or adding the server in your Claude settings), open a chat and paste:\n\n  ```text\n  Call the tool `search_standards` with input: { \"query\": \"OAuth\" } and summarize the top matches (domain, category, short description).\n  ```\n\n- Cursor\n\n  - With the MCP server registered in Cursor, open the assistant and paste:\n\n  ```text\n  Call the tool `get_checklist` with input: { \"domain\": \"authentication\", \"severity\": \"critical\" } and list checklist items and their severity.\n  ```\n\n- General guidance\n\n  - Use the natural-language prompts above — the MCP-enabled assistant will route the request to the matching tool and return structured text. If your client exposes a direct \"Call MCP tool\" UI, provide the tool name and the JSON input object shown in the examples.\n\n### Option 2: Skills / Custom Instructions\n\nCopy `skills/ai-architecture-cookbook.md` into your AI assistant's skills directory. The skill instructs the AI to load specific YAML entries on demand.\n\nNote: this file was previously named `SKILL.md` — it has been consolidated and renamed to `ai-architecture-cookbook.md` in the `skills/` directory to avoid ambiguity.\n\n### Option 3: Generated Instruction Files\n\nGenerate pre-built instruction files for your AI assistant:\n\n```bash\n# GitHub Copilot\npython3 prompts/compose.py --format copilot --standards all --output .github/copilot-instructions.md\n\n# Claude\npython3 prompts/compose.py --format claude --standards all --output CLAUDE.md\n\n# Cursor\npython3 prompts/compose.py --format cursor --standards all --output .cursorrules\n\n# Select specific standards\npython3 prompts/compose.py --format copilot --standards authentication,api-design,error-handling\n\n# Select by category\npython3 prompts/compose.py --format copilot --categories foundational,security-quality\n```\n\n### Option 4: Direct YAML Access\n\nRead `index.yaml` for the full catalog, then load specific entries as needed:\n\n```\nindex.yaml                    → Master catalog (all 44 entries, tag index)\n{category}/_index.yaml        → Category metadata\n{category}/{domain}/{domain}.yaml → Full standard\n```\n\n## Examples\n\nThe repository includes runnable example clients and helper scripts under `mcp-server/examples/`. These demonstrate stdio clients, the HTTP wrapper, natural-language flows, and debug helpers.\n\n### Guided Input for Recommendations\n\nA new interactive example `collect-context.mjs` helps you iteratively collect the minimal high‑impact inputs the cookbook needs to generate reliable recommendations. It uses the `validate_recommendation_context` tool to detect missing fields and asks focused questions until the context is complete, then calls `recommend_pattern`.\n\nRun the guided CLI (build first if needed):\n\n```bash\ncd mcp-server\nnpm install\nnpm run build\n# then from mcp-server\nnode --input-type=module dist/examples/collect-context.mjs || node dist/examples/collect-context.mjs\n```\n\nThe interactive flow asks for a project summary and primary goals first (short mode), and can be switched to a more detailed mode via the `guided_recommendation_form` prompt for traffic, SLAs, integrations, budget, and timeline.\n\nPrerequisites\n- Node >= 18\n- Build the server (required for examples that execute `dist/server.js`):\n\n```bash\ncd mcp-server\nnpm ci\nnpm run build\n```\n\nRun the server (optional if examples spawn it):\n\n```bash\n# in one terminal\nnode dist/server.js\n# or for development (no build):\nnpm run dev\n```\n\nRun examples (execute from the `mcp-server` directory):\n\n```bash\n# stdio client that auto-spawns the server if needed\nnode examples/stdio-client.mjs\n\n# stdio client using the natural-language wrapper\nnode examples/stdio-client-nl.mjs\n\n# programmatic natural-language example\nnode examples/run-direct-nl.mjs\n\n# demo rich recommendation\nnode examples/demo-rich-recommend.mjs\n\n# search query debug\nnode examples/search-query-debug.mjs\n\n# HTTP wrapper (starts an HTTP server and forwards requests to the MCP server)\nnode examples/http-wrapper.mjs\n# then open the printed URL or use curl, for example:\ncurl \"http://localhost:61061/?q=authentication\"\n```\n\nNotes\n- Some examples wait for the server to print `MCP server running` on stderr before proceeding; allow a few seconds for startup.\n- If you prefer not to build, run `npm run dev` in one terminal and run the example scripts in another.\n- Inspect `mcp-server/examples/` for the full list and behavior of each script.\n\n## Standards Catalog\n\n### Foundational (11 standards)\n| Standard | Description | files |\n|----------|-------------|-------|\n| [authentication](foundational/authentication/) | OIDC, OAuth2, JWT, DPoP, mTLS | [for humans](foundational/authentication/README.md) \\| [for Agents](foundational/authentication/authentication.yaml) |\n| [api-design](foundational/api-design/) | REST, GraphQL, gRPC, WebSocket | [for humans](foundational/api-design/README.md) \\| [for Agents](foundational/api-design/api-design.yaml) |\n| [error-handling](foundational/error-handling/) | Circuit breakers, retries, fallbacks | [for humans](foundational/error-handling/README.md) \\| [for Agents](foundational/error-handling/error-handling.yaml) |\n| [logging-observability](foundational/logging-observability/) | Structured logging, tracing, metrics | [for humans](foundational/logging-observability/README.md) \\| [for Agents](foundational/logging-observability/logging-observability.yaml) |\n| [data-persistence](foundational/data-persistence/) | SQL, NoSQL, caching, event stores | [for humans](foundational/data-persistence/README.md) \\| [for Agents](foundational/data-persistence/data-persistence.yaml) |\n| [input-validation](foundational/input-validation/) | Validation, sanitization, injection prevention | [for humans](foundational/input-validation/README.md) \\| [for Agents](foundational/input-validation/input-validation.yaml) |\n| [messaging-events](foundational/messaging-events/) | Queues, pub/sub, event sourcing, CQRS | [for humans](foundational/messaging-events/README.md) \\| [for Agents](foundational/messaging-events/messaging-events.yaml) |\n| [configuration-management](foundational/configuration-management/) | Env vars, secrets, feature flags | [for humans](foundational/configuration-management/README.md) \\| [for Agents](foundational/configuration-management/configuration-management.yaml) |\n| [authorization](foundational/authorization/) | RBAC, ABAC, ReBAC, policy-as-code | [for humans](foundational/authorization/README.md) \\| [for Agents](foundational/authorization/authorization.yaml) |\n| [session-management](foundational/session-management/) | Server-side sessions, JWT rotation, BFF | [for humans](foundational/session-management/README.md) \\| [for Agents](foundational/session-management/session-management.yaml) |\n| [secrets-management](foundational/secrets-management/) | Vault services, rotation, zero-trust access | [for humans](foundational/secrets-management/README.md) \\| [for Agents](foundational/secrets-management/secrets-management.yaml) |\n\n### Application Architecture (10 standards)\n| Standard | Description | files |\n|----------|-------------|-------|\n| [ai-agent-architecture](application-architecture/ai-agent-architecture/) | Agent loops, tool use, memory, planning, multi-agent | [for humans](application-architecture/ai-agent-architecture/README.md) \\| [for Agents](application-architecture/ai-agent-architecture/ai-agent-architecture.yaml) |\n| [layered-architecture](application-architecture/layered-architecture/) | Clean, hexagonal, onion architecture | [for humans](application-architecture/layered-architecture/README.md) \\| [for Agents](application-architecture/layered-architecture/layered-architecture.yaml) |\n| [service-architecture](application-architecture/service-architecture/) | Microservices, modular monolith | [for humans](application-architecture/service-architecture/README.md) \\| [for Agents](application-architecture/service-architecture/service-architecture.yaml) |\n| [domain-driven-design](application-architecture/domain-driven-design/) | Bounded contexts, aggregates | [for humans](application-architecture/domain-driven-design/README.md) \\| [for Agents](application-architecture/domain-driven-design/domain-driven-design.yaml) |\n| [state-management](application-architecture/state-management/) | Client, server, distributed state | [for humans](application-architecture/state-management/README.md) \\| [for Agents](application-architecture/state-management/state-management.yaml) |\n| [dependency-injection](application-architecture/dependency-injection/) | DI, IoC, composition root | [for humans](application-architecture/dependency-injection/README.md) \\| [for Agents](application-architecture/dependency-injection/dependency-injection.yaml) |\n| [repository-pattern](application-architecture/repository-pattern/) | Data access, unit of work | [for humans](application-architecture/repository-pattern/README.md) \\| [for Agents](application-architecture/repository-pattern/repository-pattern.yaml) |\n| [design-patterns](application-architecture/design-patterns/) | SOLID principles, GoF patterns | [for humans](application-architecture/design-patterns/README.md) \\| [for Agents](application-architecture/design-patterns/design-patterns.yaml) |\n| [resilience-chaos-engineering](application-architecture/resilience-chaos-engineering/) | Circuit breakers, bulkheads, chaos experiments | [for humans](application-architecture/resilience-chaos-engineering/README.md) \\| [for Agents](application-architecture/resilience-chaos-engineering/resilience-chaos-engineering.yaml) |\n| [feature-flags](application-architecture/feature-flags/) | Progressive delivery, kill switches, A/B testing | [for humans](application-architecture/feature-flags/README.md) \\| [for Agents](application-architecture/feature-flags/feature-flags.yaml) |\n\n### Infrastructure (7 standards)\n| Standard | Description | files |\n|----------|-------------|-------|\n| [containerization](infrastructure/containerization/) | Docker, OCI, runtime security | [for humans](infrastructure/containerization/README.md) \\| [for Agents](infrastructure/containerization/containerization.yaml) |\n| [orchestration](infrastructure/orchestration/) | Kubernetes, service mesh | [for humans](infrastructure/orchestration/README.md) \\| [for Agents](infrastructure/orchestration/orchestration.yaml) |\n| [ci-cd](infrastructure/ci-cd/) | Pipelines, release strategies | [for humans](infrastructure/ci-cd/README.md) \\| [for Agents](infrastructure/ci-cd/ci-cd.yaml) |\n| [infrastructure-as-code](infrastructure/infrastructure-as-code/) | Terraform, Pulumi, Bicep | [for humans](infrastructure/infrastructure-as-code/README.md) \\| [for Agents](infrastructure/infrastructure-as-code/infrastructure-as-code.yaml) |\n| [cloud-architecture](infrastructure/cloud-architecture/) | Cloud-native, well-architected | [for humans](infrastructure/cloud-architecture/README.md) \\| [for Agents](infrastructure/cloud-architecture/cloud-architecture.yaml) |\n| [database-migration](infrastructure/database-migration/) | Schema evolution, zero-downtime | [for humans](infrastructure/database-migration/README.md) \\| [for Agents](infrastructure/database-migration/database-migration.yaml) |\n| [api-gateway-edge-security](infrastructure/api-gateway-edge-security/) | WAF, DDoS protection, zero-trust edge | [for humans](infrastructure/api-gateway-edge-security/README.md) \\| [for Agents](infrastructure/api-gateway-edge-security/api-gateway-edge-security.yaml) |\n\n### Security & Quality (10 standards)\n| Standard | Description | files |\n|----------|-------------|-------|\n| [encryption](security-quality/encryption/) | TLS, cryptography, key management | [for humans](security-quality/encryption/README.md) \\| [for Agents](security-quality/encryption/encryption.yaml) |\n| [rate-limiting](security-quality/rate-limiting/) | Throttling, abuse prevention | [for humans](security-quality/rate-limiting/README.md) \\| [for Agents](security-quality/rate-limiting/rate-limiting.yaml) |\n| [testing-strategies](security-quality/testing-strategies/) | Test pyramid, TDD, coverage | [for humans](security-quality/testing-strategies/README.md) \\| [for Agents](security-quality/testing-strategies/testing-strategies.yaml) |\n| [code-quality](security-quality/code-quality/) | Linting, static analysis | [for humans](security-quality/code-quality/README.md) \\| [for Agents](security-quality/code-quality/code-quality.yaml) |\n| [performance-optimization](security-quality/performance-optimization/) | Profiling, caching, scaling | [for humans](security-quality/performance-optimization/README.md) \\| [for Agents](security-quality/performance-optimization/performance-optimization.yaml) |\n| [accessibility](security-quality/accessibility/) | WCAG, ARIA, inclusive design | [for humans](security-quality/accessibility/README.md) \\| [for Agents](security-quality/accessibility/accessibility.yaml) |\n| [client-platform-security](security-quality/client-platform-security/) | CSP, cert pinning, root detection, anti-tamper | [for humans](security-quality/client-platform-security/README.md) \\| [for Agents](security-quality/client-platform-security/client-platform-security.yaml) |\n| [secure-sdlc](security-quality/secure-sdlc/) | SAST, DAST, SCA, supply chain, SBOM | [for humans](security-quality/secure-sdlc/README.md) \\| [for Agents](security-quality/secure-sdlc/secure-sdlc.yaml) |\n| [compliance-data-privacy](security-quality/compliance-data-privacy/) | GDPR, CCPA, HIPAA, consent, data retention | [for humans](security-quality/compliance-data-privacy/README.md) \\| [for Agents](security-quality/compliance-data-privacy/compliance-data-privacy.yaml) |\n| [security-monitoring](security-quality/security-monitoring/) | SIEM, anomaly detection, incident response | [for humans](security-quality/security-monitoring/README.md) \\| [for Agents](security-quality/security-monitoring/security-monitoring.yaml) |\n\n### Integration & Data (9 standards)\n| Standard | Description | files |\n|----------|-------------|-------|\n| [data-transformation](integration-data/data-transformation/) | ETL/ELT, streaming pipelines | [for humans](integration-data/data-transformation/README.md) \\| [for Agents](integration-data/data-transformation/data-transformation.yaml) |\n| [file-storage](integration-data/file-storage/) | Object storage, CDN, presigned URLs | [for humans](integration-data/file-storage/README.md) \\| [for Agents](integration-data/file-storage/file-storage.yaml) |\n| [llm-integration](integration-data/llm-integration/) | LLM guardrails, caching, cost control, self-hosted inference | [for humans](integration-data/llm-integration/README.md) \\| [for Agents](integration-data/llm-integration/llm-integration.yaml) |\n| [rag-architecture](integration-data/rag-architecture/) | Vector search, embeddings, RAG pipelines, grounding | [for humans](integration-data/rag-architecture/README.md) \\| [for Agents](integration-data/rag-architecture/rag-architecture.yaml) |\n| [search](integration-data/search/) | Full-text search, indexing strategies | [for humans](integration-data/search/README.md) \\| [for Agents](integration-data/search/search.yaml) |\n| [third-party-integration](integration-data/third-party-integration/) | Vendor abstraction, circuit breakers | [for humans](integration-data/third-party-integration/README.md) \\| [for Agents](integration-data/third-party-integration/third-party-integration.yaml) |\n| [vector-databases](integration-data/vector-databases/) | Index types, sharding, hybrid search, provider comparison | [for humans](integration-data/vector-databases/README.md) \\| [for Agents](integration-data/vector-databases/vector-databases.yaml) |\n| [versioning](integration-data/versioning/) | API versioning, backward compatibility | [for humans](integration-data/versioning/README.md) \\| [for Agents](integration-data/versioning/versioning.yaml) |\n| [webhooks](integration-data/webhooks/) | Delivery guarantees, idempotent processing | [for humans](integration-data/webhooks/README.md) \\| [for Agents](integration-data/webhooks/webhooks.yaml) |\n\n## Entry Structure\n\nEvery standard follows `base-template.yaml` v3:\n\n```\nmeta                → Domain, version, tags, prerequisites, related standards\ncontext_inputs      → Parameters for decision tree evaluation\ndecision_tree       → Priority-ordered if/then/else rules\ndecision_metadata   → Confidence level, risk, fallback pattern\npatterns            → Implementation details with code examples\nexamples            → Correct and incorrect code\nsecurity_hardening  → 6 categories (transport, data protection, access control, etc.)\ncompliance          → Standards references (RFCs, OWASP, etc.)\nprompt_recipes      → Pre-built prompts for common scenarios\nanti_patterns       → What to avoid, with detection and migration\nchecklist           → Verification items with severity\n```\n\n## How Decision Trees Work\n\nEach standard has a decision tree that maps your context to a recommended pattern:\n\n1. **Provide context**: Answer questions like \"What client types?\" \"What scale?\"\n2. **Evaluate rules**: Walk the tree from priority 1 downward\n3. **Get recommendation**: First matching rule gives you the pattern\n4. **Fallback**: If nothing matches, use the declared fallback pattern\n\nExample (authentication):\n```\nPriority 1: IF client_types == server AND security_level in [high, critical]\n              THEN → mtls_authentication (mutual TLS for service-to-service)\n\nPriority 2: IF security_level in [high, critical] AND data_sensitivity == high\n              THEN → sender_constrained_tokens (DPoP / mTLS PoP)\n\nPriority 3: IF third_party_access == true\n              THEN → delegated_authorization (OAuth2 scoped grants)\n\nPriority 4: IF needs_login == true\n              THEN → federated_authentication (OIDC + OAuth2)\n              ELSE → delegated_authorization (OAuth2 for M2M)\n\nPriority 5: IF session_type == stateless\n              THEN → token_based_auth (JWT)\n\nFALLBACK → federated_authentication\n```\n\n## Validation\n\nThe validator (`tools/validate.py`) checks every YAML entry against the v3 JSON Schema **and** a set of semantic rules to catch structural errors, missing content, broken cross-references, and index inconsistencies.\n\n### What it checks\n\n| Check | Description |\n|-------|-------------|\n| **JSON Schema compliance** | Structure, required fields, types, enums, string patterns (kebab-case domain, semver version, etc.) |\n| **Quality gates** | Minimum content thresholds: ≥3 patterns, ≥3 anti-patterns, ≥1 example, ≥4 prompt recipes |\n| **Cross-reference integrity** | `prerequisites` and `related_standards` point to known domains (warnings for future-batch refs) |\n| **Decision tree consistency** | Every `then` / `else` pattern exists in the `patterns` list; condition variables match `context_inputs` |\n| **Fallback consistency** | The `decision_metadata.fallback.pattern` references a defined pattern |\n| **Anti-pattern references** | Each anti-pattern's `related_pattern` exists in `patterns` |\n| **Checklist references** | `verified_by` fields point to a valid pattern or anti-pattern name |\n| **ID uniqueness** | No duplicate checklist IDs; no duplicate decision-tree priorities |\n| **Index consistency** | Every entry in `_index.yaml` has a matching YAML file, and vice versa |\n\n### Usage examples\n\n```bash\n# Validate all 44 entries\npython3 tools/validate.py\n```\n\n```\n============================================================\nAI Architecture Cookbook — Validation Report\n============================================================\nEntries validated: 44\nPassed: 44\nFailed: 0\n\n✓ All entries valid. (0 warnings)\n```\n\n```bash\n# Validate a single entry\npython3 tools/validate.py foundational/authentication/authentication.yaml\n```\n\n```\n============================================================\nAI Architecture Cookbook — Validation Report\n============================================================\nEntries validated: 1\nPassed: 1\nFailed: 0\n\nWARNINGS (non-blocking):\n\n  foundational/authentication/authentication.yaml:\n  XREF: related_standard 'encryption' not found in known domains (future batch?)\n  XREF: related_standard 'input-validation' not found in known domains (future batch?)\n\n✓ All entries valid. (2 warnings)\n```\n\n> **Note**: Cross-reference warnings are non-blocking — they flag references to domains\n> not present in the validation scope (e.g., when validating a single file whose\n> `related_standards` point to other entries).\n\n```bash\n# Validate an entire category\npython3 tools/validate.py foundational/\n```\n\nWhen an entry **fails**, the report shows the specific errors:\n\n```\nFAIL foundational/authentication/authentication.yaml:\n  SCHEMA [meta.domain]: 'Auth' does not match '^[a-z][a-z0-9-]*$'\n  QUALITY: 2 patterns (minimum 3)\n  CONSISTENCY: decision_tree node 'rule_1' references pattern 'oauth_basic' not defined in patterns\n```\n\n### Error categories\n\n- **SCHEMA** — JSON Schema violations (wrong types, missing required fields, invalid formats)\n- **QUALITY** — Below minimum content thresholds\n- **XREF** — Cross-reference to an unknown domain (warning)\n- **CONSISTENCY** — Internal reference mismatch (decision tree → patterns, checklist → verified_by, etc.)\n- **INDEX** — Mismatch between `_index.yaml` listings and actual YAML files on disk\n\n## Claude Code Hooks\n\nThe repository includes [Claude Code hooks](https://code.claude.com/docs/en/hooks) that automatically integrate the cookbook's MCP tools and skill into every session. Hooks are configured in `.claude/settings.json` and fire as lifecycle events — no manual invocation needed.\n\n### What the hooks do\n\n| Hook | Event | Trigger | Effect |\n|------|-------|---------|--------|\n| `session-context.sh` | SessionStart | Session begins or resumes | Injects `additionalContext` with MCP tool catalog, standard count, skill location, and usage workflow |\n| `architecture-advisor.sh` | UserPromptSubmit | Every user prompt | Detects architecture-related keywords (auth, API, security, testing, etc.) and suggests specific MCP tool calls |\n| `post-mcp-guidance.sh` | PostToolUse | After any `mcp__ai-architecture-cookbook__*` tool returns | Injects next-step guidance (evaluate decision tree → apply pattern → verify checklist) |\n\n### How it works\n\n1. **SessionStart** — Claude receives the full MCP tool catalog and skill reference at session start, so it knows the cookbook is available.\n2. **UserPromptSubmit** — When you ask about authentication, API design, testing, etc., the hook detects the domain and injects a reminder with the exact MCP tool call to run (e.g., `query_standard {\"domain\":\"authentication\"}`).\n3. **PostToolUse** — After an MCP tool returns results, the hook tells Claude what to do next: evaluate the decision tree, apply the pattern, or walk the checklist.\n\n### Enabling the hooks\n\nThe hooks are committed to the repo and activate automatically when you open the project in Claude Code. No additional setup is required — Claude Code reads `.claude/settings.json` on session start.\n\n> **Note**: These hooks are specific to Claude Code. For other AI assistants, use the git pre-commit hook installed by `scripts/setup.sh`, which provides equivalent validation at commit time.\n\n## Contributing\n\nThis repository was created alongside [awslabs/aidlc-workflows](https://github.com/awslabs/aidlc-workflows), an AI-assisted development lifecycle workflow toolkit. Using aidlc-workflows is recommended when adding new standards or making significant contributions — it provides structured inception, requirements analysis, design, and code-generation phases that keep contributions consistent and well-documented.\n\n### Adding a new standard with AI-DLC\n\nThe fastest way to contribute a new standard is to let AI-DLC drive the entire process. Open your AI assistant (Copilot Chat, Claude Code, Cursor, etc.) in the repo and paste a prompt like:\n\n```text\nUsing AI-DLC, implement a new cookbook standard for \"caching-strategies\" in the\nfoundational category.\n\nRequirements:\n- Cover in-memory, distributed, and CDN caching patterns\n- Include decision tree inputs: data_volatility, read_write_ratio, cache_location,\n  scale, and consistency_requirement\n- Provide at least 4 patterns: local_in_memory, distributed_redis,\n  cdn_edge_caching, and write_through_cache\n- Add anti-patterns for cache stampede, unbounded caches, and stale-while-revalidate misuse\n- Include security hardening for cache poisoning and sensitive data leakage\n- Reference related standards: performance-optimization, data-persistence, api-design\n- Ensure the entry passes `python3 tools/validate.py` with zero errors\n```\n\nAI-DLC will walk through its adaptive workflow:\n\n1. **Workspace Detection** — detects the existing cookbook (brownfield) and scans for reverse-engineering artifacts\n2. **Requirements Analysis** — clarifies scope, quality gates (≥3 patterns, ≥3 anti-patterns, ≥4 recipes, etc.), and cross-references\n3. **Application Design** — designs the YAML structure, decision tree nodes, and pattern details\n4. **Code Generation** — creates `foundational/caching-strategies/caching-strategies.yaml`, updates `foundational/_index.yaml`, and adds the entry to `index.yaml`\n5. **Build & Test** — runs `python3 tools/validate.py` to confirm schema compliance, cross-reference integrity, and index consistency\n\nThe result is a fully validated standard ready for pull request — with audit trail and design docs under `aidlc-docs/`.\n\n> **Tip**: You can scope the prompt to any category. For example:\n> `\"Using AI-DLC, implement a new standard for 'graph-databases' in the integration-data category.\"`\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full manual guidelines on adding or improving standards.\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}