{
  "markdown": "# DevOps Practices - MCP Server\n\n[![CI/CD Pipeline](https://github.com/ai-4-devops/devops-practices/actions/workflows/ci.yml/badge.svg)](https://github.com/ai-4-devops/devops-practices/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Version](https://img.shields.io/badge/version-1.4.0-blue.svg)](https://github.com/ai-4-devops/devops-practices/releases)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Published-green.svg)](https://registry.modelcontextprotocol.io/?search=devops-practices)\n[![PyPI](https://img.shields.io/pypi/v/devops-practices-mcp.svg)](https://pypi.org/project/devops-practices-mcp/)\n\nmcp-name: io.github.ai-4-devops/devops-practices\n\n**Purpose**: Productivity framework for DevOps engineers using AI assistance (Claude Code) while working on PoCs.\n\n**Type**: Model Context Protocol (MCP) Server for Claude Code\n\n**Version**: 1.4.0\n\n**Status**: 🎉 **Officially Published** in the [MCP Registry](https://registry.modelcontextprotocol.io/?search=devops-practices) (Published: February 18, 2026)\n\n**Published Versions:**\n- 📦 **PyPI**: [v1.4.0](https://pypi.org/project/devops-practices-mcp/1.4.0/) → Git tag [v1.4.0](https://github.com/ai-4-devops/devops-practices/releases/tag/v1.4.0) (`34ca572`)\n- 🌐 **MCP Registry**: v1.4.0 → Git tag [v1.4.0](https://github.com/ai-4-devops/devops-practices/releases/tag/v1.4.0) (`34ca572`)\n- 🚀 **Latest Development**: [main branch](https://github.com/ai-4-devops/devops-practices) (may include unreleased features)\n\n---\n\n> **Who is this for?** DevOps engineers using **Claude Code (VS Code plugin)** for PoC development.\n> **What it does:** Provides structure (TRACKER, ISSUES, docs, SoPs) so you can focus on building without worrying about documentation overhead.\n> **What it's NOT:** Not a DevOps tutorial - it's a productivity framework for AI-assisted development.\n\n---\n\n## Why This MCP Server?\n\n**Solves the CLAUDE.md Bloat Problem**\n\nTired of maintaining massive CLAUDE.md files (1000+ lines) across multiple projects? This MCP centralizes reusable DevOps instructions for engineers working on multiple PoCs, eliminating repeated instructions across projects and folders.\n\n**The Problem:**\n- ❌ Large CLAUDE.md files eat up context window\n- ❌ Same practices duplicated across every project\n- ❌ Reinventing TRACKER.md, ISSUES.md, docs, SoPs for every PoC\n- ❌ Inconsistent standards across projects\n- ❌ Context wasted on instructions instead of actual work\n\n**The Solution:**\n- ✅ **Pre-built structure** - Templates for TRACKER, ISSUES, docs, SoPs\n- ✅ **Focus on work** - Not on \"how should I document this?\"\n- ✅ **Consistency** - Same standards across all your PoCs\n- ✅ **Team alignment** - Same patterns enable seamless collaboration and easy handovers across sessions, systems, and team members\n- ✅ **Faster startup** - Copy template, start working\n- ✅ **Context saved** - No bloated CLAUDE.md files\n\n**What you get (structure, not knowledge):**\n- 📋 **TRACKER.md template** - Start tracking immediately, don't design tracking\n- 🐛 **ISSUES.md system** - Start logging issues, don't setup Jira\n- 📚 **Documentation standards** - Start writing docs, don't debate structure\n- 📖 **Runbook templates** - Start documenting ops, don't create SoP formats\n- 🔄 **Session continuity** - Start handoffs, don't design handoff protocols\n\nWhen searching \"devops\" in the MCP Registry (as of February 2026), this is the only result. While other MCPs focus on:\n- 🔧 **Development tools** (code generation, testing, debugging)\n- 📊 **Data analysis** (databases, APIs, analytics)\n- 🎨 **Content creation** (writing, design, media)\n\n**This MCP provides:**\n- 🏗️ **Configuration structure** - How to organize configs per environment, generate new env configs from completed ones, create and validate SoPs\n- 📚 **Documentation patterns** - TRACKER, ISSUES, docs, runbook templates ready to copy\n- 🔄 **Operations templates** - Session handoff, runbook formats, documentation standards\n- 🎯 **Structured guidance** - GG-SS organized practices for quick discovery\n\n**What makes it different:**\n- **Prescriptive, not generative** - Provides proven practices, not generated code\n- **Infrastructure-first** - Built for ops teams, not developers\n- **Reusable patterns** - Templates and standards across all your projects\n- **AI-native design** - Organized for Claude to query and apply contextually\n- **R&D optimized** - Accelerates proof-of-concept development and experimentation\n\n**Perfect for:** DevOps engineers using Claude Code (VS Code plugin) to build PoCs and conduct R&D with AI assistance.\n\n---\n\n## How It Works\n\n**No server management required:**\n- ✅ **Auto-start**: Spawns when Claude Code/Desktop starts\n- ✅ **Background**: Runs silently while you work\n- ✅ **On-demand**: Claude queries practices as needed\n- ✅ **Auto-stop**: Shuts down when Claude closes\n- ✅ **Fallback**: Access practices via GitHub/local if MCP unavailable (see [Troubleshooting](#mcp-server-is-down-or-unavailable))\n\n**Configuration Options:**\n\nYou can configure the MCP server globally (all projects) or per-project:\n\n**Option 1: Global Configuration** (`~/.claude.json`)\n```json\n{\n  \"mcpServers\": {\n    \"devops-practices\": {\n      \"command\": \"python3\",\n      \"args\": [\"-u\", \"~/.mcp-servers/devops-practices/mcp-server.py\"],\n      \"env\": {\"PYTHONUNBUFFERED\": \"1\"}\n    }\n  }\n}\n```\n\n**Option 2: Project-Level Configuration** (`.mcp.json` in project root)\n```json\n{\n  \"mcpServers\": {\n    \"devops-practices\": {\n      \"command\": \"python3\",\n      \"args\": [\"-u\", \"~/.mcp-servers/devops-practices/mcp-server.py\"],\n      \"env\": {\"PYTHONUNBUFFERED\": \"1\"}\n    }\n  }\n}\n```\n\n**Setup Steps:**\n1. Install the MCP server (see Installation section below)\n2. Add configuration to `~/.claude.json` (global) or `.mcp.json` (per-project)\n3. Restart Claude Code/Desktop\n4. MCP server runs automatically - no manual startup needed\n\n**Note**: The `-u` flag and `PYTHONUNBUFFERED` ensure real-time logging for debugging.\n\n---\n\n## What This Provides\n\nThis MCP server provides shared DevOps practices that are common across infrastructure projects:\n\n### Available Practices (11)\n\nOrganized using **GG-SS** prefix pattern (Group-Sequence) for better discoverability:\n\n**Naming Pattern:** `GG-SS-practice-name`\n- **GG** = Group ID (01-04) - Functional category\n- **SS** = Sequence ID (01-03) - Order within group\n- Example: `03-02-air-gapped-workflow` = Group 03, Sequence 02\n\n**Group Legend:**\n- **01** = Workflow & Processes (how to work effectively)\n- **02** = Version Control & Project Management (git, issues)\n- **03** = Infrastructure & Configuration (K8s, deployments, config)\n- **04** = Documentation Standards (docs, READMEs, runbooks)\n\n---\n\n#### Group 01: Workflow & Processes\n1. **01-01-session-continuity** - State tracking, handoff protocols, CURRENT-STATE.md\n2. **01-02-task-tracking** - TRACKER.md, CURRENT-STATE.md, PENDING-CHANGES.md\n3. **01-03-efficiency-guidelines** - When to script vs copy-paste, batching commands\n\n#### Group 02: Version Control & Project Management\n4. **02-01-git-practices** - Using `git mv`, commit conventions, backup protocols, GitLab Flow\n5. **02-02-issue-tracking** 🆕 - In-repository Jira-like issue tracking system (Advanced)\n\n#### Group 03: Infrastructure & Configuration\n6. **03-01-configuration-management** ⭐ - Config organization, placeholders, environment isolation\n7. **03-02-air-gapped-workflow** - Working across laptop, CloudShell, bastion, and EKS\n8. **03-03-standard-workflow** - Common operational patterns and workflows\n\n#### Group 04: Documentation Standards\n9. **04-01-documentation-standards** - HOW/WHAT/WHY structure, naming conventions\n10. **04-02-readme-maintenance** ⭐ - Directory documentation standards and best practices\n11. **04-03-runbook-documentation** ⭐ - Mandatory session log standards and requirements\n\n### Available Templates (7)\n1. **TRACKER.md** - Task tracking template (milestones)\n2. **CURRENT-STATE.md** - Session handoff template\n3. **CLAUDE.md** - Simplified project instructions template\n4. **RUNBOOK.md** ⭐ - Session log template with all required sections\n5. **ISSUE.md** 🆕 - Individual issue template (Advanced)\n6. **ISSUES.md** 🆕 - Issue index template with stats dashboard (Advanced)\n7. **issues/README.md** 🆕 - How to use the issue system (Advanced)\n\n---\n\n## Architecture\n\n```\ndevops-practices-mcp/\n├── README.md                    # This file\n├── mcp-server.py                # MCP server implementation\n├── requirements.txt             # Python dependencies\n├── .github/workflows/ci.yml     # GitHub Actions pipeline\n├── health-check.sh              # Health validation script\n├── practices/                   # Shared practice documents (11 files, GG-SS organized)\n│   ├── 01-01-session-continuity.md\n│   ├── 01-02-task-tracking.md\n│   ├── 01-03-efficiency-guidelines.md\n│   ├── 02-01-git-practices.md\n│   ├── 02-02-issue-tracking.md  # 🆕 Advanced: In-repo issue tracking\n│   ├── 03-01-configuration-management.md\n│   ├── 03-02-air-gapped-workflow.md\n│   ├── 03-03-standard-workflow.md\n│   ├── 04-01-documentation-standards.md\n│   ├── 04-02-readme-maintenance.md\n│   └── 04-03-runbook-documentation.md\n├── templates/                   # File templates (7 files)\n│   ├── TRACKER-template.md\n│   ├── CURRENT-STATE-template.md\n│   ├── CLAUDE-template.md\n│   ├── RUNBOOK-template.md\n│   ├── ISSUE-TEMPLATE.md        # 🆕 Individual issue template\n│   ├── ISSUES.md                # 🆕 Issue index with dashboard\n│   └── issues-README.md         # 🆕 Issue system guide\n├── tools/                       # Automation tools 🆕\n│   └── issue-manager.sh         # CLI for managing issues\n└── config/                      # MCP configuration\n    └── mcp-config.json          # Server configuration\n```\n\n---\n\n## MCP Tools\n\nThe MCP server provides 5 tools for Claude to query practices and templates:\n\n| Tool | Description | Example |\n|------|-------------|---------|\n| `list_practices` | List all available practices | Returns list of 10 practices |\n| `get_practice` | Get practice content by name | `get_practice(\"01-02-task-tracking\")` |\n| `list_templates` | List all available templates | Returns list of 4 templates |\n| `get_template` | Get template content by name | `get_template(\"TRACKER-template\")` |\n| `render_template` | Render template with variable substitution | `render_template(\"TRACKER-template\", {\"PROJECT_NAME\": \"my-project\"})` |\n\n### Template Variable Substitution\n\nTemplates support `${VARIABLE}` placeholders that are automatically substituted:\n\n**Auto-provided variables:**\n- `${DATE}` - Current date (YYYY-MM-DD format)\n- `${TIMESTAMP}` - UTC timestamp (YYYYMMDDTHHMMz format)\n- `${USER}` - Current system user\n- `${YEAR}` - Current year\n\n**Custom variables:**\nPass any additional variables when rendering:\n```python\nrender_template(\"RUNBOOK-template\", {\n    \"SESSION_NUMBER\": \"1\",\n    \"TITLE\": \"Kafka Deployment\",\n    \"CLUSTER_NAME\": \"example-eks-uat\",\n    \"OBJECTIVE_DESCRIPTION\": \"Deploy Kafka cluster to UAT\"\n})\n```\n\nAll `${...}` placeholders in the template are replaced with provided values.\n\n---\n\n## CI/CD Pipeline\n\nThis repository includes a **GitHub Actions pipeline** (`.github/workflows/ci.yml`) that automatically validates changes:\n\n### Pipeline Jobs\n\n**On every merge request and commit to main/develop:**\n\n1. **health-check** - Runs the comprehensive health check script\n2. **python-validation** - Validates Python syntax and dependencies\n3. **practice-validation** - Ensures all practice files exist\n4. **template-validation** - Ensures templates contain variable placeholders\n5. **link-checker** - Checks documentation cross-references\n\n### Benefits\n\n- ✅ Prevents breaking changes from reaching main branch\n- ✅ Catches missing files or syntax errors automatically\n- ✅ Ensures consistent quality standards\n- ✅ No manual validation needed\n\n### Pipeline Status\n\nCheck pipeline status in GitHub:\n- **Green checkmark** ✅ - All checks passed, safe to merge\n- **Red X** ❌ - Checks failed, review errors before merging\n\n---\n\n## Documentation\n\n### Quick Reference\n- **[PRACTICE-INDEX.md](PRACTICE-INDEX.md)** - Quick lookup guide for which practice to use when\n  - Organized by task type (deploying, documenting, troubleshooting, etc.)\n  - Common scenarios with recommended practices\n  - Practice dependencies and relationships\n\n### Migration Guide\n- **[MIGRATION-GUIDE.md](MIGRATION-GUIDE.md)** - Roll out MCP to existing projects\n  - Step-by-step migration from monolithic CLAUDE.md\n  - Configuration setup for Claude Desktop/Code\n  - Testing and validation procedures\n  - Rollback plan if needed\n\n### Version History\n- **[CHANGELOG.md](CHANGELOG.md)** - Complete version history and upgrade guides\n  - Version 1.0.0 (2026-02-13): 10 practices, 4 templates, health check tool\n  - Version 0.1.0 (2026-02-13): Initial release\n\n### Health Check\n- **[health-check.sh](health-check.sh)** - Validate MCP server before deployment\n  - 14 comprehensive checks (directory structure, files, Python environment, loading tests)\n  - Colored output with pass/fail counts\n  - Exit codes: 0 (healthy), 1 (unhealthy)\n\n**Usage:**\n```bash\ncd devops-practices-mcp\nbash health-check.sh\n```\n\n---\n\n## How Projects Use This\n\n### Project CLAUDE.md Structure\nEach project has a simplified CLAUDE.md:\n\n```markdown\n# Claude AI Assistant - [Project Name]\n\n## MCP Service Integration\n**Shared Practices**: `devops-practices` MCP server\n\nClaude has access to shared DevOps practices via MCP:\n- Air-gapped workflow\n- Documentation standards\n- Session continuity protocols\n- Task tracking guidelines\n- Git best practices\n- Efficiency guidelines\n\n⚠️ Fallback: If MCP unavailable, see Appendix or GitHub practices\n\n## Project-Specific: [Project Details]\n[Only project-specific instructions here]\n\n## Appendix: Critical Practices (Fallback)\n[Emergency practice summaries if MCP down - see CLAUDE-template.md]\n```\n\n### Benefits\n- **DRY**: Shared practices written once, used everywhere\n- **Consistency**: All projects follow same standards\n- **Maintainability**: Update once, all projects benefit\n- **Discoverability**: Claude can query practices when needed\n- **Resilient**: Fallback to GitHub/local/appendix if MCP unavailable\n\n**Template:** See [CLAUDE-template.md](templates/CLAUDE-template.md) for full structure including fallback appendix\n\n---\n\n## Installation & Setup\n\n### 🔧 Manual Installation (Most Stable - Recommended for Development)\n\n**Best for:** Developers, contributors, or anyone who wants full control\n\n#### 1. Clone Repository\n```bash\n# Clone to recommended location\ngit clone https://github.com/ai-4-devops/devops-practices.git ~/.mcp-servers/devops-practices\ncd ~/.mcp-servers/devops-practices\n```\n\n#### 2. Install Dependencies\n```bash\n# Using uv (10-100x faster)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv pip install -r requirements.txt\n\n# Or using traditional pip\npip install -r requirements.txt\n```\n\n#### 3. Configure MCP Server\nEdit `~/.claude/config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"devops-practices\": {\n      \"command\": \"python3\",\n      \"args\": [\"-u\", \"~/.mcp-servers/devops-practices/mcp-server.py\"],\n      \"env\": {\"PYTHONUNBUFFERED\": \"1\"}\n    }\n  }\n}\n```\n\n#### 4. Restart Claude Code/Desktop\n\n#### 5. Verify MCP Connection\nAsk Claude: \"Can you list the available DevOps practices from the MCP server?\"\n\n**💡 Tip:** Claude may need a reminder to check the MCP. If it doesn't respond with practice names, try:\n- \"Please verify you can access the devops-practices MCP server\"\n- \"List all available MCP tools\"\n- Restart Claude Code again\n\n---\n\n### 🧪 Experimental / Testing (For Nerds)\n\n**⚠️ Note:** These methods are experimental and not yet fully tested. Use Manual Installation (above) for reliable setup.\n\n**Option 1: MCP Registry via Claude Desktop UI** (Experimental):\n1. Open Claude Desktop\n2. Go to Settings → Developer → MCP Servers\n3. Search for \"devops-practices\"\n4. Click \"Install\"\n5. Restart Claude Code/Desktop\n\n**Option 2: Install via uvx** (✨ Recommended - automatic venv):\n```bash\n# Add MCP server using uvx (handles venv automatically)\nclaude mcp add devops-practices -- uvx devops-practices-mcp\n\n# Restart Claude Code/Desktop to activate\n```\n**Why recommended:** `uvx` automatically manages the virtual environment for you - no setup needed.\n\n**Option 3: Install with uv + venv** (For Python developers):\n```bash\n# Install uv if you don't have it\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Create virtual environment\nuv venv ~/.venvs/devops-practices-mcp\n\n# Activate venv\nsource ~/.venvs/devops-practices-mcp/bin/activate\n\n# Install MCP server\nuv pip install devops-practices-mcp\n\n# Add to Claude configuration (using venv's python)\nclaude mcp add devops-practices -- ~/.venvs/devops-practices-mcp/bin/python -m devops_practices_mcp\n\n# Restart Claude Code/Desktop to activate\n```\n**Why use this:** Full control over the virtual environment with modern `uv` tooling.\n\n**Option 4: Install to user directory** (Legacy - no venv):\n```bash\n# Install using pip (to ~/.local/)\npip install --user devops-practices-mcp\n\n# Add to Claude configuration\nclaude mcp add devops-practices -- python3 -m devops_practices_mcp\n\n# Restart Claude Code/Desktop to activate\n```\n\n**Option 5: Install system-wide** (Requires sudo):\n```bash\n# Install system-wide (requires root)\nsudo pip install devops-practices-mcp\n\n# Add to Claude configuration\nclaude mcp add devops-practices -- python3 -m devops_practices_mcp\n\n# Restart Claude Code/Desktop to activate\n```\n\n**Option 6: Manual configuration** (Edit config files directly):\n\nInstall via pip or uvx, then edit `~/.claude/config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"devops-practices\": {\n      \"command\": \"uvx\",\n      \"args\": [\"devops-practices-mcp\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n---\n\n## Real-World Use Cases\n\n### 1. **Multi-Environment Kafka Deployment**\n**Scenario**: Deploying Kafka across dev → test → uat → prod\n\n**Without MCP**:\n- Duplicate 580-line CLAUDE.md in each project\n- Repeat same issues on each environment (12 hours total)\n- No standardized approach across teams\n\n**With MCP**:\n- Claude queries `get_practice(\"configuration-management\")` for installation SOPs\n- Copies dev runbook for test environment (56% time savings)\n- All teams follow same standards automatically\n\n**Result**: 5.25 hours vs 12 hours (56% faster)\n\n### 2. **Standardized Git Workflow**\n**Scenario**: Team needs consistent branching strategy\n\n**Without MCP**:\n- Each project has different branching approach\n- New team members confused about workflow\n- Git practices documented differently everywhere\n\n**With MCP**:\n- Claude queries `get_practice(\"02-01-git-practices\")`\n- Everyone gets same 200+ line GitLab Flow documentation\n- Single source of truth for git standards\n\n**Result**: Consistent workflow across all 15 projects\n\n### 3. **Air-Gapped Infrastructure Deployment**\n**Scenario**: Deploying to secure environment without internet\n\n**Without MCP**:\n- Re-explain workflow every session\n- Copy-paste commands from old runbooks\n- Inconsistent file transfer procedures\n\n**With MCP**:\n- Claude queries `get_practice(\"air-gapped-workflow\")`\n- Gets step-by-step: Laptop → S3 → Bastion → Target\n- Consistent process every time\n\n**Result**: Zero security incidents, predictable deployments\n\n### 4. **Project Documentation Setup**\n**Scenario**: Starting new infrastructure project\n\n**Without MCP**:\n- Create CLAUDE.md from scratch (2 hours)\n- Copy-paste from old projects (inconsistent)\n- Miss important practices\n\n**With MCP**:\n```\nUser: \"Create project structure for monitoring-stack project\"\nClaude: [Queries MCP for templates]\nClaude: Creates TRACKER.md, CURRENT-STATE.md, RUNBOOK.md\n        All following latest standards\n```\n\n**Result**: 15 minutes vs 2 hours (88% faster)\n\n### 5. **Issue Tracking for Complex Projects**\n**Scenario**: Managing 50+ work items across 3-month project\n\n**Without MCP**:\n- Use external Jira (access issues, overhead)\n- Or track in scattered markdown files\n- No consistent format\n\n**With MCP**:\n- Claude queries `get_template(\"ISSUES\")`\n- Creates in-repo issue tracking with dashboard\n- Uses `tools/issue-manager.sh` for CLI management\n\n**Result**: Git-based tracking, no external dependencies\n\n---\n\n## Usage Examples\n\n### For Claude\nWhen working on your projects:\n\n**Query Practice:**\n```\nUser: \"What's the air-gapped workflow for file transfers?\"\nClaude: [Queries MCP: get_practice(\"air-gapped-workflow\")]\nClaude: [Receives markdown content]\nClaude: \"Here's the air-gapped workflow...\"\n```\n\n**Get Template (Raw):**\n```\nUser: \"Show me the TRACKER template\"\nClaude: [Queries MCP: get_template(\"TRACKER-template\")]\nClaude: [Receives template with ${VARIABLES}]\nClaude: \"Here's the template...\"\n```\n\n**Render Template (With Variables):**\n```\nUser: \"Create a TRACKER.md for my kafka-deployment project\"\nClaude: [Queries MCP: render_template(\"TRACKER-template\", {\n    \"PROJECT_NAME\": \"kafka-deployment\",\n    \"DATE\": \"2026-02-14\",\n    \"PHASE_NAME\": \"UAT Deployment\"\n})]\nClaude: [Receives rendered template with all variables substituted]\nClaude: [Creates TRACKER.md with actual values]\n```\n\n### Updating Practices\n**For Contributors:**\n```bash\ncd devops-practices-mcp\nvim practices/documentation-standards.md\n# Make changes\ngit add practices/documentation-standards.md\ngit commit -m \"Update documentation standards: add new RUNBOOKS guidelines\"\ngit push\n# All projects using this MCP server now get updated standards\n```\n\n---\n\n## Branching Strategy\n\nThis repository uses **GitLab Flow** with semantic versioning to ensure stability for dependent projects.\n\n### Branch Structure\n\n```\nmain            ← Production releases only (v1.0.0, v1.1.0, etc.)\n  ↑\ndevelop         ← Active development, integration branch\n  ↑\nfeature/*       ← New practices, templates\nrelease/*       ← Version preparation (v1.2.0)\nhotfix/*        ← Critical production fixes\n```\n\n### Branch Types\n\n| Branch | Purpose | Created From | Merges To |\n|--------|---------|--------------|-----------|\n| `main` | Production releases (tagged) | - | - |\n| `develop` | Active development | `main` | `main` (via release) |\n| `feature/*` | New functionality | `develop` | `develop` |\n| `release/*` | Version preparation | `develop` | `main` + `develop` |\n| `hotfix/*` | Critical fixes | `main` | `main` + `develop` |\n\n### Why GitLab Flow?\n\n- ✅ **Stability**: `main` always contains tested, production-ready code\n- ✅ **Safety**: Changes go through `develop` before reaching production\n- ✅ **Testing**: CI/CD validates all changes before merge\n- ✅ **Versioning**: Clear semantic version releases (v1.0.0, v1.1.0, etc.)\n- ✅ **Traceability**: Full history of what changed and when\n\n### Quick Workflows\n\n**Add New Practice/Template**:\n```bash\ngit checkout develop\ngit checkout -b feature/add-security-practice\n# Make changes, commit\ngit push origin feature/add-security-practice\n# Create PR → develop\n```\n\n**Create Release**:\n```bash\ngit checkout develop\ngit checkout -b release/v1.2.0\n# Update CHANGELOG.md, version numbers\n# Create PR → main\n# Tag release: git tag v1.2.0\n# Merge back to develop\n```\n\n**Critical Hotfix**:\n```bash\ngit checkout main\ngit checkout -b hotfix/critical-bug\n# Fix, commit, push\n# Create PR → main (fast-track)\n# Also merge to develop\n```\n\n**Full Documentation**: See [CONTRIBUTING.md](CONTRIBUTING.md) and [git-practices.md](practices/git-practices.md)\n\n---\n\n## Governance\n\n### Who Maintains This\n- **Owner**: Uttam Jaiswal Lead\n- **Contributors**: DevOps Engineers\n- **Review Process**: PR required for changes\n\n### Update Protocol\n\n**For New Practices/Templates**:\n1. Create feature branch from `develop`\n2. Update practice or template files\n3. Run health check: `bash health-check.sh`\n4. Update documentation (README.md, PRACTICE-INDEX.md)\n5. Create PR with description → `develop`\n6. Code review by team\n7. Merge to `develop` after CI/CD passes\n\n**For Releases**:\n1. Create release branch from `develop`: `release/v1.x.0`\n2. Update CHANGELOG.md and version numbers\n3. Create PR → `main`\n4. Tag release after merge: `git tag v1.x.0`\n5. Merge release back to `develop`\n6. Announce to team (affects all dependent projects)\n\n**For Critical Fixes**:\n1. Create hotfix branch from `main`: `hotfix/issue-name`\n2. Fix issue and test thoroughly\n3. Create PR → `main` (fast-track approval)\n4. Tag hotfix release: `git tag v1.x.1`\n5. Merge to `develop` to keep in sync\n6. Announce urgent fix to team\n\n**See**: [CONTRIBUTING.md](CONTRIBUTING.md) for detailed workflows\n\n### Versioning\n- **Major version** (2.0): Breaking changes to structure\n- **Minor version** (1.1): New practices added\n- **Patch version** (1.0.1): Clarifications, fixes\n\n---\n\n## Projects Using This MCP Server\n\n| Project | Purpose | Location |\n|---------|---------|----------|\n| kafka-deployment | Apache Kafka deployment | Example project\n| observability-stack | Observability stack | Example project\n| network-infra | Network infrastructure | Example project\n\n---\n\n## Development\n\n**See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution workflow, branching strategy, and code review process.**\n\n### Adding a New Practice\n1. Create markdown file in `practices/`\n2. Use clear structure with examples\n3. Update `mcp-server.py` if needed\n4. Test with Claude\n5. Update this README (practice count)\n6. Update [PRACTICE-INDEX.md](PRACTICE-INDEX.md) (add to scenario lists)\n7. Update [CHANGELOG.md](CHANGELOG.md) (document the addition)\n8. Run health check: `bash health-check.sh`\n\n### Adding a New Template\n1. Create template file in `templates/`\n2. Use placeholders: `${PROJECT_NAME}`, `${DATE}`, etc. (see auto-provided variables in MCP Tools section)\n3. No code changes needed - `render_template` handles all `${...}` substitutions automatically\n4. Test template: `render_template(\"your-template\", {\"VAR\": \"value\"})`\n5. Update this README (template count)\n6. Update [CHANGELOG.md](CHANGELOG.md) (document the addition)\n7. Run health check: `bash health-check.sh`\n\n### Making Changes\n- **Before release:** Run health check to validate all files\n- **After changes:** Update CHANGELOG.md with version bump\n- **Breaking changes:** Update MIGRATION-GUIDE.md with migration notes\n- **New features:** Update PRACTICE-INDEX.md with usage scenarios\n\n---\n\n## Troubleshooting\n\n### Claude Can't Access MCP Server\n\n**Symptoms:** Claude doesn't return practices when asked, or acts like MCP doesn't exist\n\n**Solutions:**\n1. **Remind Claude explicitly:** \"Please check the devops-practices MCP server and list available practices\"\n2. **Verify MCP is loaded:** Ask \"What MCP servers do you have access to?\"\n3. **Check configuration:** Verify `~/.claude/config.json` has correct paths (must be absolute paths)\n4. **Restart Claude Code:** MCP servers load on startup\n5. **Check logs:** Look at `~/.cache/claude/mcp-devops-practices.log` for errors\n6. **Verify MCP process:** Run `ps aux | grep mcp-server.py` to confirm it's running\n\n**💡 Pro Tip:** Claude sometimes \"forgets\" to check MCP servers. Explicitly remind it to verify the MCP before proceeding with tasks.\n\n**Log location:** `~/.cache/claude/mcp-devops-practices.log`\n\n### MCP Server is Down or Unavailable\n\n**Symptoms:** MCP server process crashed, not responding, or cannot start\n\n**Fallback Options:**\n\n**Option 1: GitHub Practices (Recommended)**\n```\nAccess practices directly from GitHub:\nhttps://github.com/ai-4-devops/devops-practices/tree/main/practices\n\nAsk Claude to read practices via GitHub URLs when MCP unavailable.\n```\n\n**Option 2: Local Clone**\n```bash\n# Access practices from local clone\nls ~/.mcp-servers/devops-practices-mcp/practices/\n\n# Read practice directly\ncat ~/.mcp-servers/devops-practices-mcp/practices/03-02-air-gapped-workflow.md\n```\n\n**Option 3: CLAUDE.md Appendix**\n```\nProjects using the CLAUDE-template.md have a built-in appendix\nwith critical practice summaries for emergency fallback.\n\nSee: templates/CLAUDE-template.md (Appendix section)\n```\n\n**Prevention:**\n- Use [.mcp.json](.mcp.json) for project-level config (more reliable)\n- Add MCP health check to pre-session checklist\n- Keep local clone updated: `git pull origin main`\n- Monitor logs: `tail -f ~/.cache/claude/mcp-devops-practices.log`\n\n**Related:** [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md#troubleshooting) for project-specific fallback setup\n\n### Practice File Not Found\n1. Verify file exists: `ls practices/`\n2. Check filename matches exactly (case-sensitive)\n3. Check MCP server logs\n\n### Template Substitution Failing\n1. Verify placeholder syntax: `${VARIABLE}`\n2. Check template file encoding (UTF-8)\n3. Review mcp-server.py logs\n\n---\n\n## License\n\nMIT License - Free to use and modify\n\n---\n\n**Maintained By**: Uttam Jaiswal\n**Last Updated**: 2026-02-20\n**Version**: 1.4.0",
  "bytes": 28673,
  "sha": "de1b92a253745afdb8d81a7d8850c7faaf9f81c0e1911fac5c49f1c1577a275d",
  "repo_slug": "ai-4-devops/devops-practices",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ai_4_devops_devops_practices_35256508/readme"
}