diff --git a/CHANGELOG.md b/CHANGELOG.md index 6b7642e..03156b4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [1.4.0] - 2026-02-20 +**Git Tag:** [v1.4.0](https://github.com/ai-4-devops/devops-practices/releases/tag/v1.4.0) | **Commit:** `34ca572` +**Published:** PyPI ✅ (2026-02-19) | MCP Registry ✅ (2026-02-20) + ### Fixed **Critical MCP Server Stability Issue:** diff --git a/MIGRATION-GUIDE.md b/MIGRATION-GUIDE.md index fa8702e..53e328d 100644 --- a/MIGRATION-GUIDE.md +++ b/MIGRATION-GUIDE.md @@ -281,6 +281,11 @@ This project follows standard DevOps practices provided by the **DevOps Practice **Quick reference:** See [PRACTICE-INDEX.md](../devops-practices-mcp/PRACTICE-INDEX.md) for scenario-based lookup. +**⚠️ Fallback if MCP unavailable:** +- GitHub: https://github.com/ai-4-devops/devops-practices/tree/main/practices +- Local: `~/.mcp-servers/devops-practices-mcp/practices/` +- Critical summaries in Appendix below + ### Templates Available 1. **CLAUDE.md** - Project instructions template @@ -289,6 +294,27 @@ This project follows standard DevOps practices provided by the **DevOps Practice 4. **RUNBOOK.md** - Session log template (use for EVERY session) ``` +### 4.3: Add Fallback Appendix (Recommended) + +**For resilience, add critical practice summaries as fallback:** + +Use the appendix from [CLAUDE-template.md](templates/CLAUDE-template.md) or create a minimal one: + +```markdown +## Appendix: Critical Practices (Fallback if MCP Unavailable) + +**Full practices**: https://github.com/ai-4-devops/devops-practices/tree/main/practices + +### Essential Patterns +- **Air-gapped**: Laptop → S3 → Bastion (no direct AWS from laptop) +- **Docs**: guides/ = HOW | RUNBOOKS/ = WHAT | reports/ = WHY +- **Git**: Always `git mv` for tracked files +- **Tracking**: Update TRACKER.md + CURRENT-STATE.md every session +- **Runbooks**: MANDATORY for every session in docs/RUNBOOKS/ + +See template for full appendix with summaries. +``` + --- ## Step 5: Test MCP Integration @@ -500,6 +526,14 @@ git push origin main 4. Restart Claude completely 5. Check Claude logs for MCP errors +**Fallback workaround:** +``` +If MCP server won't start, access practices directly: +- GitHub: https://github.com/ai-4-devops/devops-practices/tree/main/practices +- Local: cat ~/.mcp-servers/devops-practices-mcp/practices/03-02-air-gapped-workflow.md +- Appendix in project CLAUDE.md (if you added it in Step 4.3) +``` + ### Issue: Practice content is outdated **Symptoms:** MCP returns old version of practice diff --git a/README.md b/README.md index 771efc9..c3016a7 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,11 @@ mcp-name: io.github.ai-4-devops/devops-practices **Status**: 🎉 **Officially Published** in the [MCP Registry](https://registry.modelcontextprotocol.io/?search=devops-practices) (Published: February 18, 2026) +**Published Versions:** +- 📦 **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`) +- 🌐 **MCP Registry**: v1.4.0 → Git tag [v1.4.0](https://github.com/ai-4-devops/devops-practices/releases/tag/v1.4.0) (`34ca572`) +- 🚀 **Latest Development**: [main branch](https://github.com/ai-4-devops/devops-practices) (may include unreleased features) + --- > **Who is this for?** DevOps engineers using **Claude Code (VS Code plugin)** for PoC development. @@ -81,6 +86,7 @@ When searching "devops" in the MCP Registry (as of February 2026), this is the o - ✅ **Background**: Runs silently while you work - ✅ **On-demand**: Claude queries practices as needed - ✅ **Auto-stop**: Shuts down when Claude closes +- ✅ **Fallback**: Access practices via GitHub/local if MCP unavailable (see [Troubleshooting](#mcp-server-is-down-or-unavailable)) **Configuration Options:** @@ -329,8 +335,13 @@ Claude has access to shared DevOps practices via MCP: - Git best practices - Efficiency guidelines +⚠️ Fallback: If MCP unavailable, see Appendix or GitHub practices + ## Project-Specific: [Project Details] [Only project-specific instructions here] + +## Appendix: Critical Practices (Fallback) +[Emergency practice summaries if MCP down - see CLAUDE-template.md] ``` ### Benefits @@ -338,6 +349,9 @@ Claude has access to shared DevOps practices via MCP: - **Consistency**: All projects follow same standards - **Maintainability**: Update once, all projects benefit - **Discoverability**: Claude can query practices when needed +- **Resilient**: Fallback to GitHub/local/appendix if MCP unavailable + +**Template:** See [CLAUDE-template.md](templates/CLAUDE-template.md) for full structure including fallback appendix --- @@ -769,6 +783,45 @@ git checkout -b hotfix/critical-bug **Log location:** `~/.cache/claude/mcp-devops-practices.log` +### MCP Server is Down or Unavailable + +**Symptoms:** MCP server process crashed, not responding, or cannot start + +**Fallback Options:** + +**Option 1: GitHub Practices (Recommended)** +``` +Access practices directly from GitHub: +https://github.com/ai-4-devops/devops-practices/tree/main/practices + +Ask Claude to read practices via GitHub URLs when MCP unavailable. +``` + +**Option 2: Local Clone** +```bash +# Access practices from local clone +ls ~/.mcp-servers/devops-practices-mcp/practices/ + +# Read practice directly +cat ~/.mcp-servers/devops-practices-mcp/practices/03-02-air-gapped-workflow.md +``` + +**Option 3: CLAUDE.md Appendix** +``` +Projects using the CLAUDE-template.md have a built-in appendix +with critical practice summaries for emergency fallback. + +See: templates/CLAUDE-template.md (Appendix section) +``` + +**Prevention:** +- Use [.mcp.json](.mcp.json) for project-level config (more reliable) +- Add MCP health check to pre-session checklist +- Keep local clone updated: `git pull origin main` +- Monitor logs: `tail -f ~/.cache/claude/mcp-devops-practices.log` + +**Related:** [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md#troubleshooting) for project-specific fallback setup + ### Practice File Not Found 1. Verify file exists: `ls practices/` 2. Check filename matches exactly (case-sensitive) diff --git a/templates/CLAUDE-template.md b/templates/CLAUDE-template.md index f3c3ce9..a235357 100644 --- a/templates/CLAUDE-template.md +++ b/templates/CLAUDE-template.md @@ -12,7 +12,7 @@ Claude has access to shared DevOps practices via MCP service. Query practices wh - **Git practices** - Using `git mv`, commit conventions, backup protocols - **Efficiency guidelines** - When to script vs copy-paste, command batching -**⚠️ Fallback**: If MCP unavailable, critical practices are duplicated below in Appendix. +**⚠️ Fallback**: If MCP unavailable, critical practices are in Appendix below + [GitHub practices](https://github.com/ai-4-devops/devops-practices/tree/main/practices) --- @@ -63,23 +63,110 @@ You are my **expert ${ROLE}**. You bring deep expertise in ${EXPERTISE_AREAS}. ## Appendix: Critical Practices (Fallback if MCP Unavailable) -### Air-Gapped Workflow (Summary) +**📚 Full Practices**: If MCP server is down, access complete practices at: +- GitHub: https://github.com/ai-4-devops/devops-practices/tree/main/practices +- Local clone: `~/.mcp-servers/devops-practices-mcp/practices/` + +**Below are essential summaries for quick reference:** + +--- + +### 03-02 Air-Gapped Workflow (Summary) +**File**: [03-02-air-gapped-workflow.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/03-02-air-gapped-workflow.md) + +**Environment Separation:** - **Laptop**: Git repo, Claude - NO AWS access - **CloudShell/VPS**: ECR uploads - Uses environment variables - **Bastion**: EKS access via SSM - Copy/paste commands only - **EKS**: Air-gapped - Images must be in ECR -**File Transfer**: Laptop → S3 → Bastion +**File Transfer Pattern**: Laptop → S3 → Bastion +**Command Flow**: Write on Laptop → Execute on Bastion (copy/paste) + +--- + +### 04-01 Documentation Standards (Summary) +**File**: [04-01-documentation-standards.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/04-01-documentation-standards.md) + +**Directory Structure:** +- `docs/guides/` = HOW to deploy (procedures) +- `docs/RUNBOOKS/` = WHAT we did (session logs - MANDATORY) +- `docs/reports/` = WHY we did it (decisions) -### Documentation Structure (Summary) -- `docs/guides/` = HOW to deploy -- `docs/RUNBOOKS/` = WHAT we did -- `docs/reports/` = WHY we did it +**Naming**: `YYYYMMDD-descriptive-name.md` -### Git Practices (Summary) +--- + +### 02-01 Git Practices (Summary) +**File**: [02-01-git-practices.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/02-01-git-practices.md) + +**Critical Rules:** - ALWAYS use `git mv` for tracked files (preserves history) - NEVER commit without explicit user request - Backup before changes: `backup-$(date -u +%Y%m%dT%H%M%SZ).yaml` +- Follow GitLab Flow: feature → develop → main + +--- + +### 01-02 Task Tracking (Summary) +**File**: [01-02-task-tracking.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/01-02-task-tracking.md) + +**Required Files:** +- `TRACKER.md` - Milestones and tasks +- `CURRENT-STATE.md` - Session handoff state +- Update both at end of every session + +**Template**: [TRACKER-template.md](https://github.com/ai-4-devops/devops-practices/blob/main/templates/TRACKER-template.md) + +--- + +### 04-03 Runbook Documentation (Summary) +**File**: [04-03-runbook-documentation.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/04-03-runbook-documentation.md) + +**MANDATORY**: Create runbook for EVERY session +**Location**: `docs/RUNBOOKS/YYYYMMDD-session-N-title.md` +**Template**: [RUNBOOK-template.md](https://github.com/ai-4-devops/devops-practices/blob/main/templates/RUNBOOK-template.md) + +**Required Sections**: Objective, Pre-work, Execution, Observations, Next Steps + +--- + +### 03-01 Configuration Management (Summary) +**File**: [03-01-configuration-management.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/03-01-configuration-management.md) + +**Structure:** +``` +configs/${ENV}/${COMPONENT}/ + ├── config-template.yaml # Placeholder version + ├── config.yaml # Actual values (gitignored) + └── README.md # Parameter documentation +``` + +**Rule**: NEVER commit actual credentials or endpoints to git + +--- + +### 01-01 Session Continuity (Summary) +**File**: [01-01-session-continuity.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/01-01-session-continuity.md) + +**End of Session:** +1. Update `CURRENT-STATE.md` with current status +2. Update `TRACKER.md` with progress +3. Create/update runbook in `docs/RUNBOOKS/` +4. Commit all changes + +**Start of Session:** +1. Read `CURRENT-STATE.md` +2. Review `TRACKER.md` +3. Read last runbook + +--- + +**💡 MCP Server Troubleshooting**: +- Verify MCP running: `ps aux | grep mcp-server` +- Check logs: `~/.cache/claude/mcp-devops-practices.log` +- Restart Claude Code/Desktop to reload MCP +- Health check: `~/.mcp-servers/devops-practices-mcp/health-check.sh` ---