devops-practices

DevOps 实践 - MCP 服务

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

用途：为使用 AI 助手（Claude Code）开展 PoC 的 DevOps 工程师提供生产力框架。

类型：面向 Claude Code 的 Model Context Protocol（MCP）服务

版本：1.4.0

状态：🎉 已在 MCP Registry 中正式发布（发布日期：2026 年 2 月 18 日）

已发布版本：

• 📦 PyPI：v1.4.0 → Git 标签 v1.4.0（34ca572）
• 🌐 MCP Registry：v1.4.0 → Git 标签 v1.4.0（34ca572）
• 🚀 最新开发版本：main 分支（可能包含尚未发布的功能）

---

适用对象： 使用 Claude Code（VS Code 插件） 进行 PoC 开发的 DevOps 工程师。 功能： 提供结构化支持（TRACKER、ISSUES、文档、SoPs），让你专注于构建，而不必担心文档工作带来的额外负担。 它不是什么： 这不是 DevOps 教程，而是一个用于 AI 辅助开发的生产力框架。

---

为什么选择此 MCP 服务？

解决 CLAUDE.md 臃肿问题

厌倦了在多个项目中维护庞大的 CLAUDE.md 文件（1000 多行）？此 MCP 服务集中管理可复用的 DevOps 指南，供参与多个 PoC 的工程师使用，从而避免在不同项目和文件夹中重复编写指南。

问题：

• ❌ 大型 CLAUDE.md 文件会占用上下文窗口
• ❌ 每个项目都重复编写相同的实践
• ❌ 每个 PoC 都要重新创建 TRACKER.md、ISSUES.md、文档和 SoP
• ❌ 各项目的标准不一致
• ❌ 上下文浪费在指南上，而非实际工作

解决方案：

• ✅ 预构建结构 - 提供 TRACKER、ISSUES、文档和 SoP 模板
• ✅ 专注工作 - 无需纠结“这个该怎么记录？”
• ✅ 保持一致 - 所有 PoC 使用相同标准
• ✅ 团队协同 - 相同模式可实现跨会话、系统和团队成员的无缝协作与轻松交接
• ✅ 快速启动 - 复制模板，开始工作
• ✅ 节省上下文 - 无需臃肿的 CLAUDE.md 文件

你将获得的内容（结构，而非知识）：

• 📋 TRACKER.md 模板 - 立即开始跟踪，无需设计跟踪方式
• 🐛 ISSUES.md 系统 - 立即开始记录问题，无需设置 Jira
• 📚 文档标准 - 立即开始编写文档，无需讨论结构
• 📖 Runbook 模板 - 立即开始记录运维内容，无需创建 SoP 格式
• 🔄 会话连续性 - 立即开始交接，无需设计交接流程

截至 2026 年 2 月，在 MCP Registry 中搜索“devops”，这就是唯一的结果。其他 MCP 主要专注于：

• 🔧 开发工具（代码生成、测试、调试）
• 📊 数据分析（数据库、API、分析）
• 🎨 内容创作（写作、设计、媒体）

此 MCP 服务提供：

• 🏗️ 配置结构 - 如何按环境组织配置、根据已完成的配置生成新环境配置，以及创建和验证 SoP
• 📚 文档模式 - 可直接复制的 TRACKER、ISSUES、文档和 runbook 模板
• 🔄 运维模板 - 会话交接、runbook 格式和文档标准
• 🎯 结构化指南 - 按 GG-SS 组织的实践，便于快速查找

它的不同之处：

• 以规范为主，而非生成 - 提供经过验证的实践，而非生成的代码
• 基础设施优先 - 面向运维团队，而非开发人员
• 可复用模式 - 模板和标准适用于所有项目
• 面向 AI 的设计 - 采用便于 Claude 按需查询和应用上下文的组织方式
• 针对研发优化 - 加速概念验证开发和实验

适用人群： 使用 Claude Code（VS Code 插件）构建 PoC 并借助 AI 开展研发的 DevOps 工程师。

---

工作原理

无需管理服务：

• ✅ 自动启动：Claude Code/Desktop 启动时自动运行
• ✅ 后台运行：工作期间静默运行
• ✅ 按需调用：Claude 根据需要查询实践
• ✅ 自动停止：Claude 关闭时自动停止
• ✅ 备用方案：如果 MCP 服务不可用，可通过 GitHub/本地访问实践（参见故障排除）

配置选项：

你可以为全局（所有项目）或单个项目配置 MCP 服务：

选项 1：全局配置（~/.claude.json）

{
  "mcpServers": {
    "devops-practices": {
      "command": "python3",
      "args": ["-u", "~/.mcp-servers/devops-practices/mcp-server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

选项 2：项目级配置（项目根目录中的 .mcp.json）

{
  "mcpServers": {
    "devops-practices": {
      "command": "python3",
      "args": ["-u", "~/.mcp-servers/devops-practices/mcp-server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

设置步骤：

1. 安装 MCP 服务（见下方安装部分）
2. 将配置添加到 ~/.claude.json（全局）或 .mcp.json（单个项目）
3. 重启 Claude Code/Desktop
4. MCP 服务会自动运行，无需手动启动

注意：-u 标志和 PYTHONUNBUFFERED 可确保实时日志记录，便于调试。

---

提供的内容

此 MCP 服务提供适用于基础设施项目的通用 DevOps 实践：

可用实践（11）

采用 GG-SS 前缀模式（组-序号），便于查找：

命名模式： GG-SS-practice-name

• GG = 组 ID（01-04）——功能类别
• SS = 序号 ID（01-03）——组内顺序
• 示例：03-02-air-gapped-workflow = 组 03，序号 02

组别说明：

• 01 = 工作流与流程（如何高效工作）
• 02 = 版本控制与项目管理（git、问题）
• 03 = 基础设施与配置（K8s、部署、配置）
• 04 = 文档标准（文档、README、运行手册）

---

组 01：工作流与流程

1. 01-01-session-continuity - 状态跟踪、交接协议、CURRENT-STATE.md
2. 01-02-task-tracking - TRACKER.md、CURRENT-STATE.md、PENDING-CHANGES.md
3. 01-03-efficiency-guidelines - 何时使用脚本，何时复制粘贴，以及如何批量执行命令

组 02：版本控制与项目管理

4. 02-01-git-practices - 使用 git mv、提交约定、备份协议、GitLab Flow
5. 02-02-issue-tracking 🆕 - 仓库内类似 Jira 的问题跟踪系统（高级）

组 03：基础设施与配置

6. 03-01-configuration-management ⭐ - 配置组织、占位符、环境隔离
7. 03-02-air-gapped-workflow - 在笔记本电脑、CloudShell、堡垒机和 EKS 之间协同工作
8. 03-03-standard-workflow - 常见的运维模式和工作流

组 04：文档标准

9. 04-01-documentation-standards - HOW/WHAT/WHY 结构、命名约定
10. 04-02-readme-maintenance ⭐ - 目录文档标准和最佳实践
11. 04-03-runbook-documentation ⭐ - 强制会话日志标准和要求

可用模板（7）

1. TRACKER.md - 任务跟踪模板（里程碑）
2. CURRENT-STATE.md - 会话交接模板
3. CLAUDE.md - 简化的项目说明模板
4. RUNBOOK.md ⭐ - 包含所有必需章节的会话日志模板
5. ISSUE.md 🆕 - 单个问题模板（高级）
6. ISSUES.md 🆕 - 含统计信息仪表板的问题索引模板（高级）
7. issues/README.md 🆕 - 问题系统使用说明（高级）

---

架构

devops-practices-mcp/
├── README.md                    # This file
├── mcp-server.py                # MCP server implementation
├── requirements.txt             # Python dependencies
├── .github/workflows/ci.yml     # GitHub Actions pipeline
├── health-check.sh              # Health validation script
├── 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
│   ├── 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 工具

MCP 服务提供 5 个工具，供 Claude 查询实践和模板：

工具	说明	示例
list_practices	列出所有可用实践	返回 10 条实践的列表
get_practice	按名称获取实践内容	get_practice("01-02-task-tracking")
list_templates	列出所有可用模板	返回 4 个模板的列表
get_template	按名称获取模板内容	get_template("TRACKER-template")
render_template	使用变量替换渲染模板	render_template("TRACKER-template", {"PROJECT_NAME": "my-project"})

模板变量替换

模板支持 ${VARIABLE} 占位符，系统会自动替换：

自动提供的变量：

• ${DATE} - 当前日期（YYYY-MM-DD 格式）
• ${TIMESTAMP} - UTC 时间戳（YYYYMMDDTHHMMz 格式）
• ${USER} - 当前系统用户
• ${YEAR} - 当前年份

自定义变量： 渲染时可传入任何其他变量：

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

模板中的所有 ${...} 占位符都会替换为提供的值。

---

CI/CD 流水线

此仓库包含一个 GitHub Actions 流水线（.github/workflows/ci.yml），可自动验证变更：

流水线作业

每次合并请求和提交到 main/develop 时：

1. health-check - 运行全面的健康检查脚本
2. python-validation - 验证 Python 语法和依赖项
3. practice-validation - 确保所有实践文件都存在
4. template-validation - 确保模板包含变量占位符
5. link-checker - 检查文档交叉引用

优势

• ✅ 防止破坏性更改进入 main 分支
• ✅ 自动发现缺失文件或语法错误
• ✅ 确保质量标准一致
• ✅ 无需手动验证

流水线状态

在 GitHub 中查看流水线状态：

• 绿色勾号 ✅ - 所有检查均已通过，可以安全合并
• 红色 X ❌ - 检查未通过，合并前请查看错误

---

文档

快速参考

• PRACTICE-INDEX.md - 快速查找何时使用哪项实践的指南
  • 按任务类型整理（部署、编写文档、故障排查等）
  • 常见场景及推荐实践
  • 实践之间的依赖关系

迁移指南

• MIGRATION-GUIDE.md - 将 MCP 部署到现有项目
  • 从单体 CLAUDE.md 逐步迁移
  • Claude Desktop/Code 的配置设置
  • 测试和验证流程
  • 必要时的回滚计划

版本历史

• CHANGELOG.md - 完整的版本历史和升级指南
  • Version 1.0.0（2026-02-13）：10 项实践、4 个模板、健康检查工具
  • Version 0.1.0（2026-02-13）：初始版本

健康检查

• health-check.sh - 部署前验证 MCP 服务
  • 14 项全面检查（目录结构、文件、Python 环境、加载测试）
  • 使用颜色区分结果，并显示通过/失败计数
  • 退出代码：0（正常）、1（异常）

用法：

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

---

项目如何使用

项目 CLAUDE.md 结构

每个项目都有一个简化版 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

⚠️ 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]

优势

• DRY：共享实践只需编写一次，即可在所有项目中使用
• 一致性：所有项目都遵循相同的标准
• 易维护：更新一次，所有项目都能受益
• 易发现：Claude 可在需要时查询实践
• 弹性：如果 MCP 不可用，可回退到 GitHub/本地/附录

**模板：**完整结构（包括回退附录）请参见 CLAUDE-template.md

---

安装与设置

🔧 手动安装（最稳定 - 推荐用于开发）

**适用对象：**开发者、贡献者，或希望完全掌控安装过程的用户

1. 克隆仓库

# Clone to recommended location
git clone https://github.com/ai-4-devops/devops-practices.git ~/.mcp-servers/devops-practices
cd ~/.mcp-servers/devops-practices

2. 安装依赖项

# Using uv (10-100x faster)
curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install -r requirements.txt

# Or using traditional pip
pip install -r requirements.txt

3. 配置 MCP 服务

编辑 ~/.claude/config.json：

{
  "mcpServers": {
    "devops-practices": {
      "command": "python3",
      "args": ["-u", "~/.mcp-servers/devops-practices/mcp-server.py"],
      "env": {"PYTHONUNBUFFERED": "1"}
    }
  }
}

4. 重启 Claude Code/Desktop

5. 验证 MCP 连接

询问 Claude：“你能列出 MCP 服务提供的 DevOps 实践吗？”

**💡 提示：**可能需要提醒 Claude 检查 MCP。如果它没有回复实践名称，请尝试：

• “请确认你能访问 devops-practices MCP 服务”
• “列出所有可用的 MCP 工具”
• 再次重启 Claude Code

---

🧪 实验性 / 测试（适合技术爱好者）

**⚠️ 注意：**这些方法仍处于实验阶段，尚未经过充分测试。为确保可靠安装，请使用上方的手动安装方法。

选项 1：通过 Claude Desktop UI 使用 MCP Registry（实验性）：

1. 打开 Claude Desktop
2. 前往 Settings → Developer → MCP Servers
3. 搜索“devops-practices”
4. 点击“Install”
5. 重启 Claude Code/Desktop

选项 2：通过 uvx 安装（✨ 推荐 - 自动创建 venv）：

# Add MCP server using uvx (handles venv automatically)
claude mcp add devops-practices -- uvx devops-practices-mcp

# Restart Claude Code/Desktop to activate

推荐原因：uvx 会自动为你管理虚拟环境，无需进行任何设置。

选项 3：通过 uv + venv 安装（适合 Python 开发者）：

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv ~/.venvs/devops-practices-mcp

# Activate venv
source ~/.venvs/devops-practices-mcp/bin/activate

# Install MCP server
uv pip install devops-practices-mcp

# Add to Claude configuration (using venv's python)
claude mcp add devops-practices -- ~/.venvs/devops-practices-mcp/bin/python -m devops_practices_mcp

# Restart Claude Code/Desktop to activate

**使用原因：**借助现代化的 uv 工具，完全掌控虚拟环境。

选项 4：安装到用户目录（旧式 - 不使用 venv）：

# Install using pip (to ~/.local/)
pip install --user devops-practices-mcp

# Add to Claude configuration
claude mcp add devops-practices -- python3 -m devops_practices_mcp

# Restart Claude Code/Desktop to activate

选项 5：全系统安装（需要 sudo）：

# Install system-wide (requires root)
sudo pip install devops-practices-mcp

# Add to Claude configuration
claude mcp add devops-practices -- python3 -m devops_practices_mcp

# Restart Claude Code/Desktop to activate

选项 6：手动配置（直接编辑配置文件）：

通过 pip 或 uvx 安装，然后编辑 ~/.claude/config.json：

{
  "mcpServers": {
    "devops-practices": {
      "command": "uvx",
      "args": ["devops-practices-mcp"],
      "env": {}
    }
  }
}

---

实际应用场景

1. 多环境 Kafka 部署

场景：跨 dev → test → uat → prod 部署 Kafka

不使用 MCP：

• 在每个项目中重复维护 580 行的 CLAUDE.md
• 在每个环境中重复解决相同问题（总计 12 小时）
• 各团队之间没有统一的做法

使用 MCP：

• Claude 查询 get_practice("configuration-management")，获取安装 SOP
• 将 dev 环境的运行手册复制到 test 环境（节省 56% 时间）
• 所有团队自动遵循相同标准

结果：耗时从 12 小时降至 5.25 小时（快 56%）

2. 标准化 Git 工作流

场景：团队需要统一的分支策略

不使用 MCP：

• 每个项目采用不同的分支方式
• 新团队成员对工作流感到困惑
• 各处记录的 Git 实践各不相同

使用 MCP：

• Claude 查询 get_practice("02-01-git-practices")
• 每个人都能获取相同的 200 多行 GitLab Flow 文档
• Git 标准只有一个可信来源

结果：所有 15 个项目采用统一的工作流

3. 隔离网络基础设施部署

场景：在无法连接互联网的安全环境中进行部署

不使用 MCP：

• 每次会话都要重新解释工作流
• 从旧运行手册中复制粘贴命令
• 文件传输流程不一致

使用 MCP：

• Claude 查询 get_practice("air-gapped-workflow")
• 获取分步流程：Laptop → S3 → Bastion → Target
• 每次都采用一致的流程

结果：零安全事故，部署过程可预测

4. 项目文档设置

场景：启动新的基础设施项目

不使用 MCP：

• 从头创建 CLAUDE.md（2 小时）
• 从旧项目复制粘贴（内容不一致）
• 遗漏重要实践

使用 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

结果：耗时从 2 小时降至 15 分钟（快 88%）

5. 复杂项目的问题跟踪

场景：管理为期 3 个月项目中的 50 多项工作

不使用 MCP：

• 使用外部 Jira（访问问题、额外开销）
• 或在分散的 Markdown 文件中跟踪
• 没有统一格式

使用 MCP：

• Claude 查询 get_template("ISSUES")
• 在仓库中创建带仪表板的问题跟踪
• 使用 tools/issue-manager.sh 通过命令行进行管理

结果：基于 Git 的跟踪，无需外部依赖

---

使用示例

对于 Claude

在项目中工作时：

查询实践：

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..."

获取模板（原始内容）：

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

渲染模板（带变量）：

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]

更新实践

贡献者操作：

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

---

分支策略

本仓库采用 GitLab Flow 和语义化版本控制，确保依赖项目的稳定性。

分支结构

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

分支类型

分支	用途	创建自	合并到
main	生产版本发布（带标签）	-	-
develop	活跃开发	main	main（通过发布）
feature/*	新功能	develop	develop
release/*	版本准备	develop	main + develop
hotfix/*	关键修复	main	main + develop

为什么选择 GitLab Flow？

• ✅ 稳定性：main 始终包含经过测试、可用于生产环境的代码
• ✅ 安全性：变更必须先经过 develop，才能进入生产环境
• ✅ 测试：CI/CD 会在合并前验证所有变更
• ✅ 版本控制：清晰的语义化版本发布（v1.0.0、v1.1.0 等）
• ✅ 可追溯性：完整记录变更内容和时间

快速工作流

添加实践/模板：

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

创建发布版本：

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

关键热修复：

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

完整文档：参见 CONTRIBUTING.md 和 git-practices.md

---

治理

维护人员

• 负责人：Uttam Jaiswal Lead
• 贡献者：DevOps 工程师
• 审核流程：变更必须提交 PR

更新流程

对于新实践/模板：

1. 从 develop 创建功能分支
2. 更新实践或模板文件
3. 运行健康检查：bash health-check.sh
4. 更新文档（README.md、PRACTICE-INDEX.md）
5. 创建 PR 并添加说明 → develop
6. 由团队进行代码审查
7. CI/CD 通过后合并到 develop

对于发布：

1. 从 develop 创建发布分支：release/v1.x.0
2. 更新 CHANGELOG.md 和版本号
3. 创建 PR → main
4. 合并后为发布打标签：git tag v1.x.0
5. 将发布分支合并回 develop
6. 通知团队（会影响所有依赖项目）

对于严重问题修复：

1. 从 main 创建热修复分支：hotfix/issue-name
2. 修复问题并进行全面测试
3. 创建 PR → main（快速审批）
4. 为热修复发布打标签：git tag v1.x.1
5. 合并到 develop 以保持同步
6. 向团队通报紧急修复

参见：CONTRIBUTING.md 了解详细工作流程

版本管理

• 主版本（2.0）：结构性不兼容变更
• 次版本（1.1）：新增实践
• 修订版本（1.0.1）：说明澄清、问题修复

---

使用此 MCP 服务的项目

项目	用途	位置
kafka-deployment	Apache Kafka 部署	示例项目
observability-stack	可观测性技术栈	示例项目
network-infra	网络基础设施	示例项目

---

开发

有关详细的贡献工作流程、分支策略和代码审查流程，请参见 CONTRIBUTING.md。

添加新实践

1. 在 practices/ 中创建 Markdown 文件
2. 使用清晰的结构并附上示例
3. 如有需要，更新 mcp-server.py
4. 使用 Claude 进行测试
5. 更新此 README（实践数量）
6. 更新 PRACTICE-INDEX.md（添加到场景列表）
7. 更新 CHANGELOG.md（记录新增内容）
8. 运行健康检查：bash health-check.sh

添加新模板

1. 在 templates/ 中创建模板文件
2. 使用占位符：${PROJECT_NAME}、${DATE} 等（参见 MCP Tools 部分中自动提供的变量）
3. 无需更改代码——render_template 会自动处理所有 ${...} 替换
4. 测试模板：render_template("your-template", {"VAR": "value"})
5. 更新此 README（模板数量）
6. 更新 CHANGELOG.md（记录新增内容）
7. 运行健康检查：bash health-check.sh

进行更改

• 发布前： 运行健康检查以验证所有文件
• 更改后： 更新 CHANGELOG.md 并提升版本号
• 不兼容变更： 更新 MIGRATION-GUIDE.md，添加迁移说明
• 新功能： 更新 PRACTICE-INDEX.md，添加使用场景

---

故障排除

Claude 无法访问 MCP 服务

症状： 向 Claude 提问时，它不返回实践内容，或表现得像是 MCP 不存在

解决方案：

1. 明确提醒 Claude：“请检查 devops-practices MCP 服务，并列出可用实践”
2. 确认 MCP 已加载： 询问“你可以访问哪些 MCP 服务？”
3. 检查配置： 确认 ~/.claude/config.json 中的路径正确（必须是绝对路径）
4. 重启 Claude Code： MCP 服务会在启动时加载
5. 检查日志： 查看 ~/.cache/claude/mcp-devops-practices.log 中的错误
6. 确认 MCP 进程： 运行 ps aux | grep mcp-server.py 以确认其正在运行

💡 专业提示： Claude 有时会“忘记”检查 MCP 服务。在继续执行任务前，请明确提醒它验证 MCP。

日志位置： ~/.cache/claude/mcp-devops-practices.log

MCP 服务宕机或不可用

症状： MCP 服务进程崩溃、无响应或无法启动

备用选项：

选项 1：GitHub 实践（推荐）

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.

选项 2：本地克隆

# 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

选项 3：CLAUDE.md 附录

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)

预防措施：

• 使用 .mcp.json 配置项目级设置（更可靠）
• 将 MCP 健康检查添加到会话前检查清单
• 保持本地克隆为最新：git pull origin main
• 监控日志：tail -f ~/.cache/claude/mcp-devops-practices.log

相关内容： MIGRATION-GUIDE.md 提供项目特定的备用设置指南

未找到实践文件

1. 验证文件是否存在：ls practices/
2. 检查文件名是否完全匹配（区分大小写）
3. 检查 MCP 服务日志

模板替换失败

1. 验证占位符语法：${VARIABLE}
2. 检查模板文件编码（UTF-8）
3. 查看 mcp-server.py 日志

---

许可证

MIT 许可证 - 可免费使用和修改

---

维护者：Uttam Jaiswal 最后更新：2026-02-20 版本：1.4.0