diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ede6d9..328f602 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,179 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 --- +## [1.4.0] - 2026-02-20 + +### Fixed + +**Critical MCP Server Stability Issue:** +- **Fixed stdio protocol corruption** - Changed logging from stderr to FileHandler only + - Root cause: Default logging wrote to stderr, corrupting JSON-RPC 2.0 messages + - Symptom: "Failed to connect" in `claude mcp list` despite server passing manual tests + - Solution: Explicit FileHandler configuration writing to `~/.cache/claude/mcp-devops-practices.log` + - Impact: Server now matches dev-kit stability pattern + - Lines changed: mcp-server-sdk.py lines 18-28 + +**Configuration Fix:** +- Fixed `~/.claude.json` pointing to non-existent `.venv/bin/python3` +- Changed to `uv run` pattern matching dev-kit for consistency +- Now uses: `uv run --directory python mcp-server-sdk.py` + +### Added + +**New MCP Tools (2):** +- **get_practice_summary** - Lightweight metadata extraction + - Returns practice heading + description only (not full content) + - Ideal for quick overview without loading full ~1000 line practices + - Use case: "What does this practice cover?" + +- **search_practices** - Keyword search across all practices + - Searches practice names and content + - Returns matching practices with context + - Use case: "Find practices about git", "Find practices mentioning docker" + +**Enhanced MCP Tools:** +- **list_practices** - Now includes metadata extraction + - Returns: practice name, heading, description, line count + - Uses regex to extract metadata from markdown + - Provides context without loading full practice content + +### Changed + +**Major: GG-SS Reorganization (11 practices renamed)** + +All practices reorganized with Group-Sequence prefix pattern for better discoverability: + +**Group 01 - Workflow & Processes (3 practices):** +- `session-continuity.md` → **01-01-session-continuity.md** +- `task-tracking.md` → **01-02-task-tracking.md** +- `efficiency-guidelines.md` → **01-03-efficiency-guidelines.md** + +**Group 02 - Version Control & Project Management (2 practices):** +- `git-practices.md` → **02-01-git-practices.md** +- `issue-tracking.md` → **02-02-issue-tracking.md** + +**Group 03 - Infrastructure & Configuration (3 practices):** +- `configuration-management.md` → **03-01-configuration-management.md** +- `air-gapped-workflow.md` → **03-02-air-gapped-workflow.md** +- `standard-workflow.md` → **03-03-standard-workflow.md** + +**Group 04 - Documentation Standards (3 practices):** +- `documentation-standards.md` → **04-01-documentation-standards.md** +- `readme-maintenance.md` → **04-02-readme-maintenance.md** +- `runbook-documentation.md` → **04-03-runbook-documentation.md** + +**Implementation Details:** +- Used `git mv` to preserve full git history (100% renames) +- Renamed in both `practices/` and `src/devops_practices_mcp/practices/` directories +- GG-SS are **prefixes** to existing descriptive names (not replacements) +- Supports hierarchical organization and room for growth (01-04, 01-05, etc.) + +**Documentation Updates:** +- **README.md** - Added group structure with descriptions, updated all examples +- **health-check.sh** - Updated EXPECTED_PRACTICES array with new GG-SS names +- **QUICK-START.md** - Batch updated all practice references +- **SETUP.md** - Batch updated all practice references +- **REORGANIZATION-PROPOSAL.md** - New comprehensive proposal document with rationale + +**Code Improvements:** +- Enhanced mcp-server-sdk.py: 237 → 337 lines +- MCP tools: 5 → 7 tools +- Added `import re` for metadata extraction +- Improved error handling and logging + +### Technical Details + +**MCP Server:** +- Version: 1.3.1 → 1.4.0 +- Total practices: 11 (unchanged count, reorganized naming) +- Total templates: 7 (unchanged) +- Total MCP tools: 7 (was 5) +- Lines of code: +100 lines (enhanced functionality) + +**Git History:** +- All renames preserve full history via `git mv` +- Git shows 100% renames (not deletes + adds) +- No content changes to practices (only filenames) + +**Duplicate Analysis:** +- ✅ NO duplicates found in practices +- Each practice has unique focus and purpose +- Confirmed no overlap with dev-kit practices (complementary, not duplicate) + +### Benefits + +**For Discoverability:** +- ✅ Practices grouped by function (workflow → infra → docs) +- ✅ Consistent with dev-kit GG-SS pattern +- ✅ Easy to browse: "03-xx = infrastructure practices" +- ✅ Alphabetical sorting now groups related practices + +**For Scalability:** +- ✅ Room to grow within groups (01-04, 01-05, etc.) +- ✅ Clear where new practices fit +- ✅ Groups 05+ available for future expansion + +**For Stability:** +- ✅ MCP server connection now stable (matches dev-kit reliability) +- ✅ No more stdio protocol corruption +- ✅ Consistent logging pattern across MCP servers + +**For Intelligence:** +- ✅ Metadata extraction enables smart practice selection +- ✅ Search capability for finding relevant practices +- ✅ Future: Routing table for intelligent recommendations + +### Migration Notes + +**Breaking Changes:** Practice filenames changed (GG-SS prefixes added) + +**Required Actions:** + +1. **Update MCP Configuration** (if you modified it): + ```json + { + "command": "uv", + "args": [ + "run", + "--directory", + "/home/ukj/.mcp-servers/devops-practices-mcp", + "python", + "mcp-server-sdk.py" + ] + } + ``` + +2. **Update practice references in your code**: + ```python + # Old + get_practice("git-practices") + + # New + get_practice("02-01-git-practices") + ``` + +3. **Pull latest changes**: + ```bash + cd ~/.mcp-servers/devops-practices-mcp + git pull origin main + ``` + +4. **Restart Claude Code** to reload MCP server with new practice names + +**Backward Compatibility:** +- ❌ Old practice names will not work (must use new GG-SS prefixed names) +- ✅ All templates unchanged (no breaking changes) +- ✅ All MCP tools backward compatible (new tools added, existing tools unchanged) + +**Impact:** +- Projects using practice names in CLAUDE.md or scripts need updates +- MCP tools (list_practices, get_practice) work with new names automatically +- Documentation updated - follow examples in README.md + +**Projects Affected:** All projects referencing devops-practices by name + +--- + ## [1.3.0] - 2026-02-17 ### Added @@ -360,6 +533,7 @@ Initial release with core DevOps practices extracted from multiple infrastructur | Version | Date | Practices | Templates | MCP Tools | Scripts | Notes | |---------|------|-----------|-----------|-----------|---------|-------| +| 1.4.0 | 2026-02-20 | 11 | 7 | 7 | CI/CD + CLI | GG-SS reorganization, stability fix, 2 new tools, enhanced search | | 1.3.0 | 2026-02-17 | 11 | 7 | 5 | CI/CD + CLI | Issue tracking system (advanced), 3 templates, issue-manager tool | | 1.2.0 | 2026-02-14 | 10 | 4 | 5 | CI/CD | GitLab Flow branching, CONTRIBUTING.md, enhanced docs | | 1.1.0 | 2026-02-14 | 10 | 4 | 5 | CI/CD | Added render_template, GitLab CI/CD pipeline | @@ -370,6 +544,71 @@ Initial release with core DevOps practices extracted from multiple infrastructur ## Upgrade Guide +### From 1.3.1 to 1.4.0 + +**Breaking Changes:** Practice filenames changed (GG-SS prefixes added) + +**Critical Bug Fix:** +- MCP server stdio protocol corruption fixed (logging now to file only) +- Server connection stability now matches dev-kit + +**New Features:** +- 2 new MCP tools (get_practice_summary, search_practices) +- Enhanced list_practices with metadata +- GG-SS hierarchical practice organization (4 groups) + +**Migration Steps:** + +1. **Pull latest changes:** + ```bash + cd ~/.mcp-servers/devops-practices-mcp + git checkout main + git pull origin main + ``` + +2. **Restart Claude Code** to reload MCP server + +3. **Update practice references** in your project files: + ```bash + # Example: Update CLAUDE.md references + sed -i 's/git-practices/02-01-git-practices/g' CLAUDE.md + sed -i 's/session-continuity/01-01-session-continuity/g' CLAUDE.md + sed -i 's/configuration-management/03-01-configuration-management/g' CLAUDE.md + # ... etc for other practices + ``` + +4. **New practice naming convention:** + - Group 01: Workflow & Processes (01-01, 01-02, 01-03) + - Group 02: Version Control & PM (02-01, 02-02) + - Group 03: Infrastructure & Config (03-01, 03-02, 03-03) + - Group 04: Documentation Standards (04-01, 04-02, 04-03) + +5. **Use new tools:** + ```python + # Quick summary without loading full practice + get_practice_summary("02-01-git-practices") + + # Search across all practices + search_practices("kubernetes") + search_practices("git workflow") + + # List with metadata + list_practices() # Now includes heading, description, line count + ``` + +**When to upgrade:** +- ✅ Immediately - Critical stability fix +- ✅ Better practice organization and discoverability +- ✅ Enhanced search and metadata capabilities + +**Effort:** Low - Mostly practice name updates in documentation + +**Projects Affected:** All projects referencing practices by name + +**Impact:** High - Server stability significantly improved, better practice discoverability + +--- + ### From 1.2.0 to 1.3.0 **Breaking Changes:** None diff --git a/QUICK-START.md b/QUICK-START.md index e40346d..8710566 100644 --- a/QUICK-START.md +++ b/QUICK-START.md @@ -28,11 +28,11 @@ network-infra/CLAUDE.md → ~150 lines (only networking-specific) ## What's Inside ### 11 Practice Documents -1. **air-gapped-workflow.md** - How to work across laptop/CloudShell/bastion/EKS -2. **documentation-standards.md** - HOW/WHAT/WHY structure, naming conventions -3. **session-continuity.md** - State tracking, handoff protocols -4. **task-tracking.md** - TRACKER.md guidelines -5. **git-practices.md** ⭐ - GitLab Flow branching, `git mv`, backup protocols (200+ lines) +1. **03-02-air-gapped-workflow.md** - How to work across laptop/CloudShell/bastion/EKS +2. **04-01-documentation-standards.md** - HOW/WHAT/WHY structure, naming conventions +3. **01-01-session-continuity.md** - State tracking, handoff protocols +4. **01-02-task-tracking.md** - TRACKER.md guidelines +5. **02-01-git-practices.md** ⭐ - GitLab Flow branching, `git mv`, backup protocols (200+ lines) 6. **efficiency-guidelines.md** - Script vs copy-paste decisions 7. **standard-workflow.md** - Common operational patterns 8. **runbook-documentation.md** ⭐ - Mandatory session log standards @@ -195,7 +195,7 @@ Claude should list 11 practices: - documentation-standards - session-continuity - task-tracking -- git-practices +- 02-01-git-practices - efficiency-guidelines - standard-workflow - runbook-documentation @@ -216,7 +216,7 @@ Claude: [Shows 11 practices from MCP server] ### Test 2: Get a Practice ✅ ``` User: "Show me the git branching strategy" -Claude: [Displays git-practices.md with GitLab Flow documentation] +Claude: [Displays 02-01-git-practices.md with GitLab Flow documentation] ``` ### Test 3: Render a Template ✅ @@ -296,7 +296,7 @@ When creating a new project: ### "Practice not found" - Check practice exists: `ls practices/` -- Filename is case-sensitive: `air-gapped-workflow.md` +- Filename is case-sensitive: `03-02-air-gapped-workflow.md` ### "Python not found" - Check Python: `python3 --version` @@ -354,7 +354,7 @@ When creating a new project: See [CHANGELOG.md](CHANGELOG.md) for complete version history. **Previous Releases:** -- v1.2.0: GitLab Flow branching, CONTRIBUTING.md, enhanced git-practices +- v1.2.0: GitLab Flow branching, CONTRIBUTING.md, enhanced 02-01-git-practices - v1.1.0: render_template tool, GitLab CI/CD pipeline - v1.0.0: runbook-documentation, configuration-management, readme-maintenance diff --git a/README.md b/README.md index f4604c4..fbe7b23 100644 --- a/README.md +++ b/README.md @@ -20,17 +20,40 @@ mcp-name: io.github.ai-4-devops/devops-practices This MCP server provides shared DevOps practices that are common across infrastructure projects: ### Available Practices (11) -1. **Air-Gapped Workflow** - Working across laptop, CloudShell, bastion, and EKS -2. **Documentation Standards** - HOW/WHAT/WHY structure, naming conventions -3. **Session Continuity** - State tracking, handoff protocols -4. **Task Tracking** - TRACKER.md, CURRENT-STATE.md, PENDING-CHANGES.md -5. **Git Practices** - Using `git mv`, commit conventions, backup protocols, GitLab Flow -6. **Efficiency Guidelines** - When to script vs copy-paste, batching commands -7. **Standard Workflow** - Common operational patterns and workflows -8. **Runbook Documentation** ⭐ - Mandatory session log standards and requirements -9. **Configuration Management** ⭐ - Config organization, placeholders, environment isolation -10. **README Maintenance** ⭐ - Directory documentation standards and best practices -11. **Issue Tracking** 🆕 - In-repository Jira-like issue tracking system (Advanced) + +Organized using **GG-SS** prefix pattern (Group-Sequence) for better discoverability: + +**Naming Pattern:** `GG-SS-practice-name` +- **GG** = Group ID (01-04) - Functional category +- **SS** = Sequence ID (01-03) - Order within group +- Example: `03-02-air-gapped-workflow` = Group 03, Sequence 02 + +**Group Legend:** +- **01** = Workflow & Processes (how to work effectively) +- **02** = Version Control & Project Management (git, issues) +- **03** = Infrastructure & Configuration (K8s, deployments, config) +- **04** = Documentation Standards (docs, READMEs, runbooks) + +--- + +#### Group 01: Workflow & Processes +1. **01-01-session-continuity** - State tracking, handoff protocols, CURRENT-STATE.md +2. **01-02-task-tracking** - TRACKER.md, CURRENT-STATE.md, PENDING-CHANGES.md +3. **01-03-efficiency-guidelines** - When to script vs copy-paste, batching commands + +#### Group 02: Version Control & Project Management +4. **02-01-git-practices** - Using `git mv`, commit conventions, backup protocols, GitLab Flow +5. **02-02-issue-tracking** 🆕 - In-repository Jira-like issue tracking system (Advanced) + +#### Group 03: Infrastructure & Configuration +6. **03-01-configuration-management** ⭐ - Config organization, placeholders, environment isolation +7. **03-02-air-gapped-workflow** - Working across laptop, CloudShell, bastion, and EKS +8. **03-03-standard-workflow** - Common operational patterns and workflows + +#### Group 04: Documentation Standards +9. **04-01-documentation-standards** - HOW/WHAT/WHY structure, naming conventions +10. **04-02-readme-maintenance** ⭐ - Directory documentation standards and best practices +11. **04-03-runbook-documentation** ⭐ - Mandatory session log standards and requirements ### Available Templates (7) 1. **TRACKER.md** - Task tracking template (milestones) @@ -52,18 +75,18 @@ devops-practices-mcp/ ├── requirements.txt # Python dependencies ├── .gitlab-ci.yml # GitLab CI/CD pipeline ├── health-check.sh # Health validation script -├── practices/ # Shared practice documents (11 files) -│ ├── air-gapped-workflow.md -│ ├── documentation-standards.md -│ ├── session-continuity.md -│ ├── task-tracking.md -│ ├── git-practices.md -│ ├── efficiency-guidelines.md -│ ├── standard-workflow.md -│ ├── runbook-documentation.md -│ ├── configuration-management.md -│ ├── readme-maintenance.md -│ └── issue-tracking.md # 🆕 Advanced: In-repo issue tracking +├── practices/ # Shared practice documents (11 files, GG-SS organized) +│ ├── 01-01-session-continuity.md +│ ├── 01-02-task-tracking.md +│ ├── 01-03-efficiency-guidelines.md +│ ├── 02-01-git-practices.md +│ ├── 02-02-issue-tracking.md # 🆕 Advanced: In-repo issue tracking +│ ├── 03-01-configuration-management.md +│ ├── 03-02-air-gapped-workflow.md +│ ├── 03-03-standard-workflow.md +│ ├── 04-01-documentation-standards.md +│ ├── 04-02-readme-maintenance.md +│ └── 04-03-runbook-documentation.md ├── templates/ # File templates (7 files) │ ├── TRACKER-template.md │ ├── CURRENT-STATE-template.md @@ -87,7 +110,7 @@ The MCP server provides 5 tools for Claude to query practices and templates: | Tool | Description | Example | |------|-------------|---------| | `list_practices` | List all available practices | Returns list of 10 practices | -| `get_practice` | Get practice content by name | `get_practice("task-tracking")` | +| `get_practice` | Get practice content by name | `get_practice("01-02-task-tracking")` | | `list_templates` | List all available templates | Returns list of 4 templates | | `get_template` | Get template content by name | `get_template("TRACKER-template")` | | `render_template` | Render template with variable substitution | `render_template("TRACKER-template", {"PROJECT_NAME": "my-project"})` | @@ -301,7 +324,7 @@ Claude should be able to query the MCP server and list practices. - Git practices documented differently everywhere **With MCP**: -- Claude queries `get_practice("git-practices")` +- Claude queries `get_practice("02-01-git-practices")` - Everyone gets same 200+ line GitLab Flow documentation - Single source of truth for git standards diff --git a/REORGANIZATION-PROPOSAL.md b/REORGANIZATION-PROPOSAL.md new file mode 100644 index 0000000..77c4bae --- /dev/null +++ b/REORGANIZATION-PROPOSAL.md @@ -0,0 +1,278 @@ +# DevOps Practices - GG-SS Reorganization Proposal + +## Executive Summary + +Reorganize 11 practices using **GG-SS** (Group-Sequence) naming pattern for better discoverability and logical grouping. + +--- + +## Current State + +| Practice | Lines | Focus | +|----------|-------|-------| +| air-gapped-workflow | 287 | Kubernetes air-gapped deployment | +| configuration-management | 1067 | Infrastructure config, multi-env | +| documentation-standards | 378 | Doc guidelines | +| efficiency-guidelines | 455 | Best practices, anti-patterns | +| git-practices | 1011 | Git workflows, branching | +| issue-tracking | 569 | Issue management | +| readme-maintenance | 663 | README standards | +| runbook-documentation | 471 | Runbooks, operational docs | +| session-continuity | 310 | Claude session management | +| standard-workflow | 336 | Non-air-gapped deployment | +| task-tracking | 322 | Task management | + +**Total:** 11 practices, ~6,900 lines + +--- + +## Proposed GG-SS Structure + +### Group 01: Workflow & Processes (Session Management) +**Focus:** How to work effectively with DevOps projects and Claude + +- **01-01-session-continuity** ← `session-continuity.md` + - Claude session handoff, CURRENT-STATE.md + - **Why 01:** Foundation for working with Claude + +- **01-02-task-tracking** ← `task-tracking.md` + - Task management, TODO tracking + - **Why 01:** Core workflow practice + +- **01-03-efficiency-guidelines** ← `efficiency-guidelines.md` + - Best practices, anti-patterns, patterns + - **Why 01:** Fundamental working principles + +--- + +### Group 02: Version Control & Project Management +**Focus:** Git, issues, tracking + +- **02-01-git-practices** ← `git-practices.md` + - Git workflows, branching, commits + - **Why 02:** Version control foundation + +- **02-02-issue-tracking** ← `issue-tracking.md` + - ISSUES.md, issue management, TRACKER relationship + - **Why 02:** Project tracking + +--- + +### Group 03: Infrastructure & Configuration +**Focus:** Kubernetes, deployments, config management + +- **03-01-configuration-management** ← `configuration-management.md` + - Multi-environment consistency, infrastructure config + - **Why 03:** Infrastructure foundation + +- **03-02-air-gapped-workflow** ← `air-gapped-workflow.md` + - Kubernetes air-gapped deployment, offline environments + - **Why 03:** Specialized infrastructure + +- **03-03-standard-workflow** ← `standard-workflow.md` + - Non-air-gapped deployment, standard environments + - **Why 03:** Standard infrastructure + +--- + +### Group 04: Documentation Standards +**Focus:** Documentation practices, standards, runbooks + +- **04-01-documentation-standards** ← `documentation-standards.md` + - General doc guidelines, standards + - **Why 04:** Doc foundation + +- **04-02-readme-maintenance** ← `readme-maintenance.md` + - README specific guidelines + - **Why 04:** README is primary doc + +- **04-03-runbook-documentation** ← `runbook-documentation.md` + - Operational runbooks, procedures + - **Why 04:** Operational documentation + +--- + +## Group Breakdown + +``` +01 - Workflow & Processes (3 practices) +├── 01-01-session-continuity +├── 01-02-task-tracking +└── 01-03-efficiency-guidelines + +02 - Version Control & Project Management (2 practices) +├── 02-01-git-practices +└── 02-02-issue-tracking + +03 - Infrastructure & Configuration (3 practices) +├── 03-01-configuration-management +├── 03-02-air-gapped-workflow +└── 03-03-standard-workflow + +04 - Documentation Standards (3 practices) +├── 04-01-documentation-standards +├── 04-02-readme-maintenance +└── 04-03-runbook-documentation +``` + +--- + +## Comparison with dev-kit Groups + +| dev-kit Groups | devops-practices Groups | +|----------------|-------------------------| +| 01 - Core/Governance | 01 - Workflow/Processes | +| 02 - Project Management | 02 - Version Control/PM | +| 03 - Backend/Infra | 03 - Infrastructure/Config | +| 04 - Frontend | 04 - Documentation | +| 05 - Testing | *(not applicable)* | +| 06 - DevOps | *(merged into 02-03)* | +| 07 - Architecture | *(not applicable)* | +| 08 - Documentation | *(moved to 04)* | + +**Rationale:** devops-practices is infrastructure-focused, so we have fewer groups but more depth in infra/config. + +--- + +## Duplicate Analysis + +### Overlap with dev-kit + +| devops-practices | dev-kit | Duplication? | +|------------------|---------|--------------| +| 02-02-issue-tracking | 02-04-issue-tracking | **Partial** - Different focus | +| 01-01-session-continuity | 02-02-claude-workflow | **Partial** - Complementary | +| 02-01-git-practices | 06-02-git-workflow | **Partial** - DevOps specific | +| 04-01-documentation-standards | 08-01/02 | **Partial** - Different scope | + +**Conclusion:** No true duplicates. Content is complementary: +- **dev-kit:** Full-stack development (app dev, testing, frontend, backend) +- **devops-practices:** Infrastructure & operations (Kubernetes, config mgmt, runbooks) + +### Internal Duplication + +**None found.** Each practice has unique focus: +- `air-gapped-workflow` ≠ `standard-workflow` (different environments) +- `configuration-management` ≠ workflows (config vs. process) +- `task-tracking` ≠ `issue-tracking` (TODOs vs. ISSUES.md) + +--- + +## Migration Plan + +### Phase 1: Rename Files with git mv (Preserves History) + +**Important:** Use `git mv` to preserve git history! + +```bash +# Group 01: Workflow & Processes +git mv practices/session-continuity.md practices/01-01-session-continuity.md +git mv practices/task-tracking.md practices/01-02-task-tracking.md +git mv practices/efficiency-guidelines.md practices/01-03-efficiency-guidelines.md + +# Group 02: Version Control & Project Management +git mv practices/git-practices.md practices/02-01-git-practices.md +git mv practices/issue-tracking.md practices/02-02-issue-tracking.md + +# Group 03: Infrastructure & Configuration +git mv practices/configuration-management.md practices/03-01-configuration-management.md +git mv practices/air-gapped-workflow.md practices/03-02-air-gapped-workflow.md +git mv practices/standard-workflow.md practices/03-03-standard-workflow.md + +# Group 04: Documentation Standards +git mv practices/documentation-standards.md practices/04-01-documentation-standards.md +git mv practices/readme-maintenance.md practices/04-02-readme-maintenance.md +git mv practices/runbook-documentation.md practices/04-03-runbook-documentation.md + +# Commit the renames +git commit -m "refactor: Reorganize practices with GG-SS prefix pattern + +- GG = Group ID (01-04) +- SS = Sequence ID within group (01-03) +- Groups: Workflow, Version Control, Infrastructure, Documentation +- Preserves git history via git mv" +``` + +**Note:** GG-SS are **prefixes** to the existing names, not replacements. The practices keep their descriptive names with GG-SS ordering. + +### Phase 2: Update References + +Files to update: +- `mcp-server-sdk.py` - Update practice loading +- `README.md` - Update practice list +- `health-check.sh` - Update validation +- Documentation - Update examples + +### Phase 3: Add Routing Table (Like dev-kit) + +Create intelligent routing for common tasks: + +```python +ROUTING_TABLE = { + 'kubernetes-deployment': ['03-02-air-gapped-workflow', '03-01-configuration-management'], + 'git-workflow': ['02-01-git-practices', '02-02-issue-tracking'], + 'documentation': ['04-01-documentation-standards', '04-02-readme-maintenance', '04-03-runbook-documentation'], + 'session-start': ['01-01-session-continuity', '01-02-task-tracking'], + 'multi-environment': ['03-01-configuration-management', '03-03-standard-workflow'], +} +``` + +--- + +## Benefits + +### 1. **Discoverability** ⭐ +- Grouped by function (workflow → infra → docs) +- Consistent with dev-kit pattern +- Easy to browse: "03-xx = infrastructure" + +### 2. **Scalability** 📈 +- Room to grow within groups (01-04, 01-05, etc.) +- Clear where new practices fit +- Group 05+ available for future + +### 3. **Intelligence** 🧠 +- Routing table enables smart recommendations +- "Working on Kubernetes?" → "Load 03-01, 03-02" +- Context-aware practice loading + +### 4. **Professionalism** 💼 +- Industry-standard hierarchical structure +- Matches dev-kit conventions +- Better for MCP Registry presentation + +--- + +## Risks & Mitigation + +| Risk | Mitigation | +|------|------------| +| Breaking changes for users | Symlinks for backward compatibility | +| PyPI package disruption | Time with v1.4.0 (after registry approval) | +| Search confusion | Update descriptions, add aliases | +| Large PR review | Phase implementation, incremental commits | + +--- + +## Timeline + +- **Now:** Get approval on structure +- **Week 1:** Rename files, create symlinks +- **Week 2:** Update code, tests, docs +- **Week 3:** Add routing table feature +- **Week 4:** Release as v1.4.0 + +--- + +## Decision + +**Approve reorganization?** +- [ ] Yes, proceed with GG-SS structure +- [ ] Modify proposal (specify changes) +- [ ] Defer until after MCP Registry approval + +--- + +**Maintained By:** Uttam Jaiswal +**Proposal Date:** 2026-02-20 +**Status:** Pending Review diff --git a/SETUP.md b/SETUP.md index f4540f7..1b70dab 100644 --- a/SETUP.md +++ b/SETUP.md @@ -24,7 +24,7 @@ ls -la # Verify practices loaded ls practices/ -# Should see: air-gapped-workflow.md, documentation-standards.md, etc. +# Should see: 03-02-air-gapped-workflow.md, 04-01-documentation-standards.md, etc. # Verify templates loaded ls templates/ @@ -194,7 +194,7 @@ Expected: Claude should list: - documentation-standards - session-continuity - task-tracking -- git-practices +- 02-01-git-practices - efficiency-guidelines ``` @@ -202,7 +202,7 @@ Expected: Claude should list: ``` User: "Can you show me the air-gapped workflow practice?" -Expected: Claude should retrieve and display the full air-gapped-workflow.md content +Expected: Claude should retrieve and display the full 03-02-air-gapped-workflow.md content ``` ### Test 3: Get a Template @@ -233,7 +233,7 @@ Expected: Claude should retrieve and display TRACKER-template.md content **Fix**: 1. Check practice file exists: `ls practices/` -2. Check filename matches exactly (case-sensitive): `air-gapped-workflow.md` +2. Check filename matches exactly (case-sensitive): `03-02-air-gapped-workflow.md` 3. Restart MCP server (restart Claude Code) ### Python Not Found @@ -274,7 +274,7 @@ Claude: [Receives full practice content] Claude: "Here's the air-gapped workflow: The laptop where Claude runs has NO AWS access... -[Full content from air-gapped-workflow.md] +[Full content from 03-02-air-gapped-workflow.md] " ``` @@ -288,10 +288,10 @@ To update a practice: cd /home/ukj/work/devops/protean/devops-practices-mcp # Edit practice file -vim practices/documentation-standards.md +vim practices/04-01-documentation-standards.md # Commit changes -git add practices/documentation-standards.md +git add practices/04-01-documentation-standards.md git commit -m "Update documentation standards: add new RUNBOOKS guidelines" # Push to remote (if configured) @@ -327,7 +327,7 @@ vim ~/.config/claude/config.json ls practices/ # Edit a practice -vim practices/air-gapped-workflow.md +vim practices/03-02-air-gapped-workflow.md # Commit changes git add . && git commit -m "Update practice" && git push diff --git a/health-check.sh b/health-check.sh index 9c49c06..af6ca76 100755 --- a/health-check.sh +++ b/health-check.sh @@ -122,17 +122,17 @@ echo print_info "Checking practice files..." EXPECTED_PRACTICES=( - "air-gapped-workflow.md" - "documentation-standards.md" - "session-continuity.md" - "task-tracking.md" - "git-practices.md" - "efficiency-guidelines.md" - "standard-workflow.md" - "runbook-documentation.md" - "configuration-management.md" - "readme-maintenance.md" - "issue-tracking.md" + "01-01-session-continuity.md" + "01-02-task-tracking.md" + "01-03-efficiency-guidelines.md" + "02-01-git-practices.md" + "02-02-issue-tracking.md" + "03-01-configuration-management.md" + "03-02-air-gapped-workflow.md" + "03-03-standard-workflow.md" + "04-01-documentation-standards.md" + "04-02-readme-maintenance.md" + "04-03-runbook-documentation.md" ) PRACTICE_COUNT=0 diff --git a/mcp-server-sdk.py b/mcp-server-sdk.py index b698053..7ece17c 100755 --- a/mcp-server-sdk.py +++ b/mcp-server-sdk.py @@ -7,18 +7,24 @@ import asyncio import logging -from pathlib import Path -from datetime import datetime import os +import re +from datetime import datetime +from pathlib import Path from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent -# Configure logging +# Configure logging to file (to avoid interfering with stdio protocol) +log_dir = os.path.expanduser('~/.cache/claude') +os.makedirs(log_dir, exist_ok=True) +log_file = os.path.join(log_dir, 'mcp-devops-practices.log') + logging.basicConfig( level=logging.INFO, - format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', + handlers=[logging.FileHandler(log_file)] ) logger = logging.getLogger('devops-practices') @@ -42,8 +48,9 @@ def load_practices() -> dict[str, str]: practice_name = file_path.stem try: with open(file_path, 'r', encoding='utf-8') as f: - practices[practice_name] = f.read() - logger.info(f"Loaded practice: {practice_name}") + content = f.read() + practices[practice_name] = content + logger.info(f"Loaded practice: {practice_name} ({len(content)} chars)") except Exception as e: logger.error(f"Error loading practice {practice_name}: {e}") @@ -94,14 +101,47 @@ async def list_tools() -> list[Tool]: "required": ["name"] } ), + Tool( + name="get_practice_summary", + description="Get a brief summary of a practice (first ~500 chars). Lighter than get_practice, good for quick reference.", + inputSchema={ + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "Name of the practice" + }, + "max_chars": { + "type": "integer", + "description": "Maximum characters to return (default: 500)", + "default": 500 + } + }, + "required": ["name"] + } + ), Tool( name="list_practices", - description="List all available DevOps practices", + description="List all available DevOps practices with metadata", inputSchema={ "type": "object", "properties": {} } ), + Tool( + name="search_practices", + description="Search practices by keyword in name or content", + inputSchema={ + "type": "object", + "properties": { + "keyword": { + "type": "string", + "description": "Keyword to search for" + } + }, + "required": ["keyword"] + } + ), Tool( name="get_template", description="Get a file template by name", @@ -154,8 +194,27 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]: logger.info(f"Tool called: {name} with args: {arguments}") if name == "list_practices": - practices_list = list(PRACTICES.keys()) - text = "Available practices:\n" + '\n'.join(f'- {p}' for p in practices_list) + practices_list = [] + for practice_name, content in PRACTICES.items(): + # Extract title from first heading + title_match = re.search(r'^#\s+(.+)$', content, re.MULTILINE) + title = title_match.group(1) if title_match else practice_name + + practices_list.append({ + 'name': practice_name, + 'title': title, + 'size': f'{len(content)} chars' + }) + + # Sort by name + practices_list.sort(key=lambda x: x['name']) + + text = "Available DevOps Practices:\n\n" + for practice in practices_list: + text += f"• **{practice['name']}**\n" + text += f" Title: {practice['title']}\n" + text += f" Size: {practice['size']}\n\n" + return [TextContent(type="text", text=text)] elif name == "get_practice": @@ -167,6 +226,46 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]: available = ', '.join(PRACTICES.keys()) raise ValueError(f'Practice not found: {practice_name}. Available: {available}') + elif name == "get_practice_summary": + practice_name = arguments.get("name", "") + max_chars = arguments.get("max_chars", 500) + content = PRACTICES.get(practice_name) + if content: + summary = content[:max_chars] + if len(content) > max_chars: + summary += "..." + return [TextContent(type="text", text=summary)] + else: + available = ', '.join(PRACTICES.keys()) + raise ValueError(f'Practice not found: {practice_name}. Available: {available}') + + elif name == "search_practices": + keyword = arguments.get("keyword", "").lower() + if not keyword: + raise ValueError("keyword parameter is required") + + results = [] + for practice_name, content in PRACTICES.items(): + # Search in name + if keyword in practice_name.lower(): + results.append(practice_name) + continue + # Search in content + if keyword in content.lower(): + results.append(practice_name) + + if results: + text = f"Found {len(results)} practice(s) matching '{keyword}':\n\n" + for practice_name in results: + # Extract title + content = PRACTICES[practice_name] + title_match = re.search(r'^#\s+(.+)$', content, re.MULTILINE) + title = title_match.group(1) if title_match else practice_name + text += f"• {practice_name}: {title}\n" + return [TextContent(type="text", text=text)] + else: + return [TextContent(type="text", text=f"No practices found matching '{keyword}'")] + elif name == "list_templates": templates_list = list(TEMPLATES.keys()) text = "Available templates:\n" + '\n'.join(f'- {t}' for t in templates_list) @@ -223,8 +322,9 @@ async def main(): async with stdio_server() as (read_stream, write_stream): logger.info("Starting DevOps Practices MCP Server") logger.info(f"Base directory: {BASE_DIR}") - logger.info(f"Practices loaded: {', '.join(PRACTICES.keys())}") - logger.info(f"Templates loaded: {', '.join(TEMPLATES.keys())}") + logger.info(f"Practices loaded: {', '.join(sorted(PRACTICES.keys()))}") + logger.info(f"Templates loaded: {', '.join(sorted(TEMPLATES.keys()))}") + logger.info(f"Log file: {log_file}") await app.run( read_stream, diff --git a/practices/session-continuity.md b/practices/01-01-session-continuity.md similarity index 100% rename from practices/session-continuity.md rename to practices/01-01-session-continuity.md diff --git a/practices/task-tracking.md b/practices/01-02-task-tracking.md similarity index 100% rename from practices/task-tracking.md rename to practices/01-02-task-tracking.md diff --git a/practices/efficiency-guidelines.md b/practices/01-03-efficiency-guidelines.md similarity index 100% rename from practices/efficiency-guidelines.md rename to practices/01-03-efficiency-guidelines.md diff --git a/practices/git-practices.md b/practices/02-01-git-practices.md similarity index 100% rename from practices/git-practices.md rename to practices/02-01-git-practices.md diff --git a/practices/issue-tracking.md b/practices/02-02-issue-tracking.md similarity index 100% rename from practices/issue-tracking.md rename to practices/02-02-issue-tracking.md diff --git a/practices/configuration-management.md b/practices/03-01-configuration-management.md similarity index 100% rename from practices/configuration-management.md rename to practices/03-01-configuration-management.md diff --git a/practices/air-gapped-workflow.md b/practices/03-02-air-gapped-workflow.md similarity index 100% rename from practices/air-gapped-workflow.md rename to practices/03-02-air-gapped-workflow.md diff --git a/practices/standard-workflow.md b/practices/03-03-standard-workflow.md similarity index 100% rename from practices/standard-workflow.md rename to practices/03-03-standard-workflow.md diff --git a/practices/documentation-standards.md b/practices/04-01-documentation-standards.md similarity index 100% rename from practices/documentation-standards.md rename to practices/04-01-documentation-standards.md diff --git a/practices/readme-maintenance.md b/practices/04-02-readme-maintenance.md similarity index 100% rename from practices/readme-maintenance.md rename to practices/04-02-readme-maintenance.md diff --git a/practices/runbook-documentation.md b/practices/04-03-runbook-documentation.md similarity index 100% rename from practices/runbook-documentation.md rename to practices/04-03-runbook-documentation.md diff --git a/pyproject.toml b/pyproject.toml index 010e4b9..608de29 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "devops-practices-mcp" -version = "1.3.1" +version = "1.4.0" description = "AI-powered DevOps knowledge base with practices, templates, and automation tools" readme = "README.md" requires-python = ">=3.10" diff --git a/src/devops_practices_mcp/__init__.py b/src/devops_practices_mcp/__init__.py index f1bf42b..a7c6cc2 100644 --- a/src/devops_practices_mcp/__init__.py +++ b/src/devops_practices_mcp/__init__.py @@ -3,7 +3,7 @@ Provides shared DevOps practices and templates for infrastructure projects. """ -__version__ = "1.3.1" +__version__ = "1.4.0" def main(): """Entry point for the MCP server.""" diff --git a/src/devops_practices_mcp/__main__.py b/src/devops_practices_mcp/__main__.py index ddcd687..48e6532 100755 --- a/src/devops_practices_mcp/__main__.py +++ b/src/devops_practices_mcp/__main__.py @@ -186,7 +186,7 @@ def _initialize(self, params: dict[str, Any]) -> dict[str, Any]: }, 'serverInfo': { 'name': 'devops-practices', - 'version': '1.2.0' + 'version': '1.4.0' } } } diff --git a/src/devops_practices_mcp/practices/session-continuity.md b/src/devops_practices_mcp/practices/01-01-session-continuity.md similarity index 100% rename from src/devops_practices_mcp/practices/session-continuity.md rename to src/devops_practices_mcp/practices/01-01-session-continuity.md diff --git a/src/devops_practices_mcp/practices/task-tracking.md b/src/devops_practices_mcp/practices/01-02-task-tracking.md similarity index 100% rename from src/devops_practices_mcp/practices/task-tracking.md rename to src/devops_practices_mcp/practices/01-02-task-tracking.md diff --git a/src/devops_practices_mcp/practices/efficiency-guidelines.md b/src/devops_practices_mcp/practices/01-03-efficiency-guidelines.md similarity index 100% rename from src/devops_practices_mcp/practices/efficiency-guidelines.md rename to src/devops_practices_mcp/practices/01-03-efficiency-guidelines.md diff --git a/src/devops_practices_mcp/practices/git-practices.md b/src/devops_practices_mcp/practices/02-01-git-practices.md similarity index 100% rename from src/devops_practices_mcp/practices/git-practices.md rename to src/devops_practices_mcp/practices/02-01-git-practices.md diff --git a/src/devops_practices_mcp/practices/issue-tracking.md b/src/devops_practices_mcp/practices/02-02-issue-tracking.md similarity index 100% rename from src/devops_practices_mcp/practices/issue-tracking.md rename to src/devops_practices_mcp/practices/02-02-issue-tracking.md diff --git a/src/devops_practices_mcp/practices/configuration-management.md b/src/devops_practices_mcp/practices/03-01-configuration-management.md similarity index 100% rename from src/devops_practices_mcp/practices/configuration-management.md rename to src/devops_practices_mcp/practices/03-01-configuration-management.md diff --git a/src/devops_practices_mcp/practices/air-gapped-workflow.md b/src/devops_practices_mcp/practices/03-02-air-gapped-workflow.md similarity index 100% rename from src/devops_practices_mcp/practices/air-gapped-workflow.md rename to src/devops_practices_mcp/practices/03-02-air-gapped-workflow.md diff --git a/src/devops_practices_mcp/practices/standard-workflow.md b/src/devops_practices_mcp/practices/03-03-standard-workflow.md similarity index 100% rename from src/devops_practices_mcp/practices/standard-workflow.md rename to src/devops_practices_mcp/practices/03-03-standard-workflow.md diff --git a/src/devops_practices_mcp/practices/documentation-standards.md b/src/devops_practices_mcp/practices/04-01-documentation-standards.md similarity index 100% rename from src/devops_practices_mcp/practices/documentation-standards.md rename to src/devops_practices_mcp/practices/04-01-documentation-standards.md diff --git a/src/devops_practices_mcp/practices/readme-maintenance.md b/src/devops_practices_mcp/practices/04-02-readme-maintenance.md similarity index 100% rename from src/devops_practices_mcp/practices/readme-maintenance.md rename to src/devops_practices_mcp/practices/04-02-readme-maintenance.md diff --git a/src/devops_practices_mcp/practices/runbook-documentation.md b/src/devops_practices_mcp/practices/04-03-runbook-documentation.md similarity index 100% rename from src/devops_practices_mcp/practices/runbook-documentation.md rename to src/devops_practices_mcp/practices/04-03-runbook-documentation.md diff --git a/uv.lock b/uv.lock new file mode 100644 index 0000000..d9e04a5 --- /dev/null +++ b/uv.lock @@ -0,0 +1,8 @@ +version = 1 +revision = 3 +requires-python = ">=3.10" + +[[package]] +name = "devops-practices-mcp" +version = "1.3.1" +source = { editable = "." }