DevOps Practices - MCP Server

mcp-name: io.github.ai-4-devops/devops-practices

Purpose: Centralized DevOps practices and standards for infrastructure projects.

Type: Model Context Protocol (MCP) Server for Claude Code

Version: 1.3.0

What This Provides

This MCP server provides shared DevOps practices that are common across infrastructure projects:

Available Practices (11)

Air-Gapped Workflow - Working across laptop, CloudShell, bastion, and EKS
Documentation Standards - HOW/WHAT/WHY structure, naming conventions
Session Continuity - State tracking, handoff protocols
Task Tracking - TRACKER.md, CURRENT-STATE.md, PENDING-CHANGES.md
Git Practices - Using git mv, commit conventions, backup protocols, GitLab Flow
Efficiency Guidelines - When to script vs copy-paste, batching commands
Standard Workflow - Common operational patterns and workflows
Runbook Documentation ⭐ - Mandatory session log standards and requirements
Configuration Management ⭐ - Config organization, placeholders, environment isolation
README Maintenance ⭐ - Directory documentation standards and best practices
Issue Tracking 🆕 - In-repository Jira-like issue tracking system (Advanced)

Available Templates (7)

TRACKER.md - Task tracking template (milestones)
CURRENT-STATE.md - Session handoff template
CLAUDE.md - Simplified project instructions template
RUNBOOK.md ⭐ - Session log template with all required sections
ISSUE.md 🆕 - Individual issue template (Advanced)
ISSUES.md 🆕 - Issue index template with stats dashboard (Advanced)
issues/README.md 🆕 - How to use the issue system (Advanced)

Architecture

devops-practices-mcp/
├── README.md                    # This file
├── mcp-server.py                # MCP server implementation
├── 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
├── templates/                   # File templates (7 files)
│   ├── TRACKER-template.md
│   ├── CURRENT-STATE-template.md
│   ├── CLAUDE-template.md
│   ├── RUNBOOK-template.md
│   ├── ISSUE-TEMPLATE.md        # 🆕 Individual issue template
│   ├── ISSUES.md                # 🆕 Issue index with dashboard
│   └── issues-README.md         # 🆕 Issue system guide
├── tools/                       # Automation tools 🆕
│   └── issue-manager.sh         # CLI for managing issues
└── config/                      # MCP configuration
    └── mcp-config.json          # Server configuration

MCP Tools

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")`
`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"})`

Template Variable Substitution

Templates support ${VARIABLE} placeholders that are automatically substituted:

Auto-provided variables:

${DATE} - Current date (YYYY-MM-DD format)
${TIMESTAMP} - UTC timestamp (YYYYMMDDTHHMMz format)
${USER} - Current system user
${YEAR} - Current year

Custom variables: Pass any additional variables when rendering:

render_template("RUNBOOK-template", {
    "SESSION_NUMBER": "1",
    "TITLE": "Kafka Deployment",
    "CLUSTER_NAME": "example-eks-uat",
    "OBJECTIVE_DESCRIPTION": "Deploy Kafka cluster to UAT"
})

All ${...} placeholders in the template are replaced with provided values.

CI/CD Pipeline

This repository includes a GitLab CI/CD pipeline (.gitlab-ci.yml) that automatically validates changes:

Pipeline Jobs

On every merge request and commit to main/develop:

health-check - Runs the comprehensive health check script
python-validation - Validates Python syntax and dependencies
practice-validation - Ensures all practice files exist
template-validation - Ensures templates contain variable placeholders
link-checker - Checks documentation cross-references

Benefits

✅ Prevents breaking changes from reaching main branch
✅ Catches missing files or syntax errors automatically
✅ Ensures consistent quality standards
✅ No manual validation needed

Pipeline Status

Check pipeline status in GitLab:

Green checkmark ✅ - All checks passed, safe to merge
Red X ❌ - Checks failed, review errors before merging

Documentation

Quick Reference

PRACTICE-INDEX.md - Quick lookup guide for which practice to use when
- Organized by task type (deploying, documenting, troubleshooting, etc.)
- Common scenarios with recommended practices
- Practice dependencies and relationships

Migration Guide

MIGRATION-GUIDE.md - Roll out MCP to existing projects
- Step-by-step migration from monolithic CLAUDE.md
- Configuration setup for Claude Desktop/Code
- Testing and validation procedures
- Rollback plan if needed

Version History

CHANGELOG.md - Complete version history and upgrade guides
- Version 1.0.0 (2026-02-13): 10 practices, 4 templates, health check tool
- Version 0.1.0 (2026-02-13): Initial release

Health Check

health-check.sh - Validate MCP server before deployment
- 14 comprehensive checks (directory structure, files, Python environment, loading tests)
- Colored output with pass/fail counts
- Exit codes: 0 (healthy), 1 (unhealthy)

Usage:

cd devops-practices-mcp
bash health-check.sh

How Projects Use This

Project CLAUDE.md Structure

Each project has a simplified CLAUDE.md:

# Claude AI Assistant - [Project Name]

## MCP Service Integration
**Shared Practices**: `devops-practices` MCP server

Claude has access to shared DevOps practices via MCP:
- Air-gapped workflow
- Documentation standards
- Session continuity protocols
- Task tracking guidelines
- Git best practices
- Efficiency guidelines

## Project-Specific: [Project Details]
[Only project-specific instructions here]

Benefits

DRY: Shared practices written once, used everywhere
Consistency: All projects follow same standards
Maintainability: Update once, all projects benefit
Discoverability: Claude can query practices when needed

Installation & Setup

Recommended Location: ~/.mcp-servers/devops-practices/

This keeps MCP servers organized and makes configuration easier. All examples below use this location.

1. Clone Repository

# Clone to recommended location
git clone <repo-url> ~/.mcp-servers/devops-practices
cd ~/.mcp-servers/devops-practices

2. Install Dependencies

Using uv (recommended - 10-100x faster):

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv pip install -r requirements.txt

Or using traditional pip:

pip install -r requirements.txt

Why uv?

10-100x faster than pip
Better dependency resolution
Built in Rust for performance
Drop-in replacement for pip

3. Configure MCP Server

Edit ~/.config/claude/config.json (or wherever Claude config lives):

{
  "mcpServers": {
    "devops-practices": {
      "command": "python",
      "args": ["/home/<username>/.mcp-servers/devops-practices/mcp-server.py"],
      "env": {}
    }
  }
}

Note: Replace <username> with your actual username, or use the full absolute path.

3. Restart Claude Code

# Restart Claude Code to load the MCP server

4. Test Connection

Ask Claude: "Can you list the available DevOps practices?"

Claude should be able to query the MCP server and list practices.

Real-World Use Cases

1. Multi-Environment Kafka Deployment

Scenario: Deploying Kafka across dev → test → uat → prod

Without MCP:

Duplicate 580-line CLAUDE.md in each project
Repeat same issues on each environment (12 hours total)
No standardized approach across teams

With MCP:

Claude queries get_practice("configuration-management") for installation SOPs
Copies dev runbook for test environment (56% time savings)
All teams follow same standards automatically

Result: 5.25 hours vs 12 hours (56% faster)

2. Standardized Git Workflow

Scenario: Team needs consistent branching strategy

Without MCP:

Each project has different branching approach
New team members confused about workflow
Git practices documented differently everywhere

With MCP:

Claude queries get_practice("git-practices")
Everyone gets same 200+ line GitLab Flow documentation
Single source of truth for git standards

Result: Consistent workflow across all 15 projects

3. Air-Gapped Infrastructure Deployment

Scenario: Deploying to secure environment without internet

Without MCP:

Re-explain workflow every session
Copy-paste commands from old runbooks
Inconsistent file transfer procedures

With MCP:

Claude queries get_practice("air-gapped-workflow")
Gets step-by-step: Laptop → S3 → Bastion → Target
Consistent process every time

Result: Zero security incidents, predictable deployments

4. Project Documentation Setup

Scenario: Starting new infrastructure project

Without MCP:

Create CLAUDE.md from scratch (2 hours)
Copy-paste from old projects (inconsistent)
Miss important practices

With MCP:

User: "Create project structure for monitoring-stack project"
Claude: [Queries MCP for templates]
Claude: Creates TRACKER.md, CURRENT-STATE.md, RUNBOOK.md
        All following latest standards

Result: 15 minutes vs 2 hours (88% faster)

5. Issue Tracking for Complex Projects

Scenario: Managing 50+ work items across 3-month project

Without MCP:

Use external Jira (access issues, overhead)
Or track in scattered markdown files
No consistent format

With MCP:

Claude queries get_template("ISSUES")
Creates in-repo issue tracking with dashboard
Uses tools/issue-manager.sh for CLI management

Result: Git-based tracking, no external dependencies

Usage Examples

For Claude

When working on your projects:

Query Practice:

User: "What's the air-gapped workflow for file transfers?"
Claude: [Queries MCP: get_practice("air-gapped-workflow")]
Claude: [Receives markdown content]
Claude: "Here's the air-gapped workflow..."

Get Template (Raw):

User: "Show me the TRACKER template"
Claude: [Queries MCP: get_template("TRACKER-template")]
Claude: [Receives template with ${VARIABLES}]
Claude: "Here's the template..."

Render Template (With Variables):

User: "Create a TRACKER.md for my kafka-deployment project"
Claude: [Queries MCP: render_template("TRACKER-template", {
    "PROJECT_NAME": "kafka-deployment",
    "DATE": "2026-02-14",
    "PHASE_NAME": "UAT Deployment"
})]
Claude: [Receives rendered template with all variables substituted]
Claude: [Creates TRACKER.md with actual values]

For Uttam Jaiswal

Update a Practice:

cd devops-practices-mcp
vim practices/documentation-standards.md
# Make changes
git add practices/documentation-standards.md
git commit -m "Update documentation standards: add new RUNBOOKS guidelines"
git push
# All projects using this MCP server now get updated standards

Branching Strategy

This repository uses GitLab Flow with semantic versioning to ensure stability for dependent projects.

Branch Structure

main            ← Production releases only (v1.0.0, v1.1.0, etc.)
  ↑
develop         ← Active development, integration branch
  ↑
feature/*       ← New practices, templates
release/*       ← Version preparation (v1.2.0)
hotfix/*        ← Critical production fixes

Branch Types

Branch	Purpose	Created From	Merges To
`main`	Production releases (tagged)	-	-
`develop`	Active development	`main`	`main` (via release)
`feature/*`	New functionality	`develop`	`develop`
`release/*`	Version preparation	`develop`	`main` + `develop`
`hotfix/*`	Critical fixes	`main`	`main` + `develop`

Why GitLab Flow?

✅ Stability: main always contains tested, production-ready code
✅ Safety: Changes go through develop before reaching production
✅ Testing: CI/CD validates all changes before merge
✅ Versioning: Clear semantic version releases (v1.0.0, v1.1.0, etc.)
✅ Traceability: Full history of what changed and when

Quick Workflows

Add New Practice/Template:

git checkout develop
git checkout -b feature/add-security-practice
# Make changes, commit
git push origin feature/add-security-practice
# Create MR → develop

Create Release:

git checkout develop
git checkout -b release/v1.2.0
# Update CHANGELOG.md, version numbers
# Create MR → main
# Tag release: git tag v1.2.0
# Merge back to develop

Critical Hotfix:

git checkout main
git checkout -b hotfix/critical-bug
# Fix, commit, push
# Create MR → main (fast-track)
# Also merge to develop

Full Documentation: See CONTRIBUTING.md and git-practices.md

Governance

Who Maintains This

Owner: Uttam Jaiswal Lead
Contributors: DevOps Engineers
Review Process: PR required for changes

Update Protocol

For New Practices/Templates:

Create feature branch from develop
Update practice or template files
Run health check: bash health-check.sh
Update documentation (README.md, PRACTICE-INDEX.md)
Create MR with description → develop
Code review by team
Merge to develop after CI/CD passes

For Releases:

Create release branch from develop: release/v1.x.0
Update CHANGELOG.md and version numbers
Create MR → main
Tag release after merge: git tag v1.x.0
Merge release back to develop
Announce to team (affects all dependent projects)

For Critical Fixes:

Create hotfix branch from main: hotfix/issue-name
Fix issue and test thoroughly
Create MR → main (fast-track approval)
Tag hotfix release: git tag v1.x.1
Merge to develop to keep in sync
Announce urgent fix to team

See: CONTRIBUTING.md for detailed workflows

Versioning

Major version (2.0): Breaking changes to structure
Minor version (1.1): New practices added
Patch version (1.0.1): Clarifications, fixes

Projects Using This MCP Server

Project	Purpose	Location
kafka-deployment	Apache Kafka deployment	Example project
observability-stack	Observability stack	Example project
network-infra	Network infrastructure	Example project

Development

See CONTRIBUTING.md for detailed contribution workflow, branching strategy, and code review process.

Adding a New Practice

Create markdown file in practices/
Use clear structure with examples
Update mcp-server.py if needed
Test with Claude
Update this README (practice count)
Update PRACTICE-INDEX.md (add to scenario lists)
Update CHANGELOG.md (document the addition)
Run health check: bash health-check.sh

Adding a New Template

Create template file in templates/
Use placeholders: ${PROJECT_NAME}, ${DATE}, etc. (see auto-provided variables in MCP Tools section)
No code changes needed - render_template handles all ${...} substitutions automatically
Test template: render_template("your-template", {"VAR": "value"})
Update this README (template count)
Update CHANGELOG.md (document the addition)
Run health check: bash health-check.sh

Making Changes

Before release: Run health check to validate all files
After changes: Update CHANGELOG.md with version bump
Breaking changes: Update MIGRATION-GUIDE.md with migration notes
New features: Update PRACTICE-INDEX.md with usage scenarios

Troubleshooting

Claude Can't Access MCP Server

Check MCP server is running: ps aux | grep mcp-server.py
Check Claude config: ~/.config/claude/config.json
Check file paths are absolute
Restart Claude Code

Practice File Not Found

Verify file exists: ls practices/
Check filename matches exactly (case-sensitive)
Check MCP server logs

Template Substitution Failing

Verify placeholder syntax: ${VARIABLE}
Check template file encoding (UTF-8)
Review mcp-server.py logs

License

MIT License - Free to use and modify

Maintained By: Uttam Jaiswal Last Updated: 2026-02-17 Version: 1.3.0

Name		Name	Last commit message	Last commit date
.claude		.claude
.github/workflows		.github/workflows
config		config
practices		practices
src/devops_practices_mcp		src/devops_practices_mcp
templates		templates
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
JOURNEY.md		JOURNEY.md
LICENSE		LICENSE
MIGRATION-GUIDE.md		MIGRATION-GUIDE.md
PORTABILITY.md		PORTABILITY.md
PRACTICE-INDEX.md		PRACTICE-INDEX.md
QUICK-START.md		QUICK-START.md
README.md		README.md
SETUP.md		SETUP.md
claude-config-example.json		claude-config-example.json
health-check.sh		health-check.sh
mcp-server-sdk.py		mcp-server-sdk.py
mcp-server.py		mcp-server.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
server.json		server.json

FilesExpand file tree

Directory actions

More options

Directory actions

More options

Latest commit

History

Folders and files

README.md

DevOps Practices - MCP Server

What This Provides

Available Practices (11)

Available Templates (7)

Architecture

MCP Tools

Template Variable Substitution

CI/CD Pipeline

Pipeline Jobs

Benefits

Pipeline Status

Documentation

Quick Reference

Migration Guide

Version History

Health Check

How Projects Use This

Project CLAUDE.md Structure

Benefits

Installation & Setup

1. Clone Repository

2. Install Dependencies

3. Configure MCP Server

3. Restart Claude Code

4. Test Connection

Real-World Use Cases

1. Multi-Environment Kafka Deployment

2. Standardized Git Workflow

3. Air-Gapped Infrastructure Deployment

4. Project Documentation Setup

5. Issue Tracking for Complex Projects

Usage Examples

For Claude

For Uttam Jaiswal

Branching Strategy

Branch Structure

Branch Types

Why GitLab Flow?

Quick Workflows

Governance

Who Maintains This

Update Protocol

Versioning

Projects Using This MCP Server

Development

Adding a New Practice

Adding a New Template

Making Changes

Troubleshooting

Claude Can't Access MCP Server

Practice File Not Found

Template Substitution Failing

License