Service Health MCP

🚀 服务健康MCP服务器

这是首个通用的服务健康监测工具，适用于Claude桌面版及兼容MCP的AI助手。它是一个专业级的MCP服务器，能让AI助手以企业级的安全性监测Web服务、API和HTTP端点，非常适合DevOps和服务监控，确保服务平稳运行。

---

🎓 透明度与学习

借助AI辅助构建

本项目由 Natasha 与Claude Sonnet 4合作完成，是一个学习实践项目，无需MCP服务器开发经验！

学习目标达成

• ✅ MCP协议实现：从无到有搭建可用服务器
• ✅ TypeScript最佳实践：采用专业的代码结构
• ✅ 安全优先开发：具备企业级的SSRF防护
• ✅ 开源标准：提供适合社区使用的文档
• ✅ 解决实际问题：填补MCP生态系统中的实际空白

给学习者的启示

如果你刚接触MCP开发或对AI辅助编程感兴趣，这个项目展示了在AI指导下学习所能取得的成果。查看我们的 开发流程 和 贡献指南 获取更多见解！

---

✨ 项目存在的意义

项目目标

在学习MCP开发的过程中，我希望构建一个能通过AI对话真正用于监测服务的工具。这个MCP服务器为Claude（以及其他AI助手）提供了一种便捷的方式，可通过聊天自然地检查服务健康状况。

实用之处

• 🔍 对话式监测：通过自然语言检查服务
• 🛡️ 安全优先设计：具备全面的SSRF防护
• ⚡ 快速可靠：提供详细的诊断信息
• 🎯 易于使用：与Claude桌面版开箱即用
• 📊 专业输出：提供可操作的信息

---

🚀 快速开始

步骤1：安装

git clone https://github.com/natashanajdovski/service-health-mcp.git
cd service-health-mcp
npm install
npm run build

步骤2：配置Claude桌面版

查找配置文件

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

添加配置

{
  "mcpServers": {
    "service-health": {
      "command": "node",
      "args": ["C:\\path\\to\\service-health-mcp\\dist\\server.js"],
      "cwd": "C:\\path\\to\\service-health-mcp"
    }
  }
}

步骤3：重启并测试

1. 完全关闭并重新打开Claude桌面版
2. 测试：输入 "Check if google.com is healthy"
3. 立即查看专业的健康报告！🎉

---

💻 使用示例

基础健康监测

📝 "Check if google.com is healthy"
📝 "Is api.github.com responding properly?"
📝 "Test if my-website.com is up"

高级配置

📝 "Check if api.example.com/health is healthy with a 15 second timeout"
📝 "Test httpbin.org/post using POST method"
📝 "Check if my-api.com returns 201 status code"

DevOps与监测

📝 "Check if our production API is responding normally"
📝 "Test all our microservices for health"
📝 "Monitor our CDN endpoints"

---

📊 示例输出

健康服务

✅ **健康检查结果**

**URL**：https://api.github.com
**状态**：HEALTHY
**响应时间**：127ms
**HTTP状态**：200 (OK)
**消息**：Endpoint is healthy (200) - 127ms response time
**检查时间**：2024-07-24T21:30:00.000Z

**解读**：
🎉 端点运行正常！未检测到问题。

不健康服务

❌ **健康检查结果**

**URL**：https://down-service.com
**状态**：UNHEALTHY
**响应时间**：5000ms
**消息**：Network error: Connection timeout
**检查时间**：2024-07-24T21:30:00.000Z

**解读**：
🚨 端点存在问题，可能已关闭或配置错误，需要进行调查。

---

🛠️ 主要特性

特性分类	详情
🔍 健康监测	- ✅ HTTP/HTTPS端点测试 - ✅ 响应时间测量 - ✅ 状态码验证 - ✅ 支持自定义头部 - ✅ 支持多种HTTP方法 - ✅ 可配置超时时间（1 - 30秒）
🛡️ 企业级安全	- ✅ 防止SSRF攻击 - ✅ 阻止内部网络访问 - ✅ 输入验证与清理 - ✅ 协议限制（仅支持HTTP/HTTPS） - ✅ 端口过滤与安全默认设置 - ✅ 零凭证暴露
⚡ 性能	- ✅ 亚秒级响应时间 - ✅ 高效的连接处理 - ✅ 最小化资源使用 - ✅ 非阻塞异步操作 - ✅ 优化的错误处理 - ✅ 智能重试逻辑
🔧 开发者体验	- ✅ 完全支持TypeScript - ✅ 专业的错误消息 - ✅ 全面的日志记录 - ✅ 易于MCP集成 - ✅ 热重载开发 - ✅ 详细的文档

---

🛡️ 安全性

本MCP服务器实现了企业级的安全措施以防止攻击：

🚨 SSRF（服务器端请求伪造）防护

❌ 阻止：localhost, 127.0.0.1
❌ 阻止：192.168.x.x, 10.x.x.x, 172.16 - 31.x.x
❌ 阻止：169.254.169.254（云元数据）
❌ 阻止：非HTTP协议（ftp, file等）
✅ 允许：仅公共HTTP/HTTPS端点

🔒 输入验证

• URL格式：符合RFC标准的验证
• 参数类型：使用Zod进行严格类型检查
• 超时范围：1 - 30秒限制
• 方法限制：仅支持GET, POST, PUT, DELETE
• 端口过滤：标准Web端口（80, 443, 8080, 8443）

🛡️ 安全默认设置

• 10秒超时（防止挂起）
• GET方法（侵入性最小）
• 无凭证存储（无状态操作）
• 最小化错误细节（无信息泄露）

---

🔧 开发

前提条件

• Node.js 18+
• TypeScript 5+
• npm或yarn

开发命令

npm run dev    # 🔄 热重载开发
npm run build  # 🏗️ 生产构建
npm run start  # 🚀 运行构建版本
npm run clean  # 🧹 清理构建文件

使用MCP检查器进行测试

npx @modelcontextprotocol/inspector src/server.ts

项目结构

service-health-mcp/
├── src/
│   ├── server.ts           # 🎯 主MCP服务器
│   ├── health/
│   │   └── http-checker.ts # 🔍 核心健康逻辑
│   ├── security/
│   │   └── url-validator.ts # 🛡️ SSRF防护
│   └── tools/
│       └── check-http.ts   # 🛠️ MCP工具接口
├── dist/                   # 📦 编译后的JavaScript
├── docs/                   # 📚 文档
└── package.json           # 📋 项目配置

---

📚 详细文档

check_http_endpoint

描述

检查HTTP/HTTPS端点是否健康且可响应。

参数

参数	类型	是否必需	默认值	描述
url	string	✅ 是	-	要检查的URL（例如，https://google.com）
method	"GET" | "POST" | "PUT" | "DELETE"	❌ 否	"GET"	要使用的HTTP方法
timeout	number	❌ 否	10000	请求超时时间（毫秒，1000 - 30000）
expectedStatus	number	❌ 否	200	预期的HTTP状态码（100 - 599）
headers	Record<string, string>	❌ 否	{}	可选的HTTP头部

示例请求

{
  "url": "https://api.example.com/health",
  "method": "GET", 
  "timeout": 15000,
  "expectedStatus": 200,
  "headers": {
    "User-Agent": "Health-Checker/1.0",
    "Accept": "application/json"
  }
}

响应格式

{
  status: "healthy" | "unhealthy" | "warning";
  responseTime: number;          // 毫秒
  statusCode?: number;           // HTTP状态码
  message: string;               // 人类可读的描述
  details: {
    url: string;
    timestamp: string;           // ISO 8601格式
    error?: string;              // 错误详情（如果适用）
  }
}

---

🔄 故障排除

❓ 工具未在Claude桌面版中显示

问题

Claude无法识别健康检查工具。

解决方案

1. 验证配置语法：使用JSON验证器
2. 检查文件路径：在配置中使用绝对路径
3. 完全重启：完全关闭Claude桌面版，然后重新打开
4. 测试构建：运行 npm run build 并检查是否有错误
5. 检查权限：确保Node.js可以读取文件

🌐 网络连接问题

问题

出现网络错误或超时。

❌ Network error: Client network socket disconnected

解决方案

• 服务可能已关闭：先尝试在浏览器中检查
• HTTPS问题：尝试使用URL的HTTP版本
• 防火墙：检查网络是否阻止了该服务
• DNS：验证域名解析是否正确

🔒 安全限制消息

问题

由于安全原因URL被阻止。

❌ Access to internal networks and localhost is not allowed

说明

这是有意设置的！安全系统正常工作：

• 本地测试：直接使用浏览器或 curl
• 监测：仅使用外部、公共可访问的URL
• 内部服务：在网络内部部署监测工具

⚡ 性能问题

问题

响应时间慢或超时。

解决方案

• 增加超时时间：对于慢速服务，使用15 - 30秒的超时时间
• 检查网络：测试与目标服务的连接性
• 减少负载：避免同时检查过多端点

---

🤝 贡献

我们欢迎所有技能水平的贡献者！这个项目由一名学习者在AI的辅助下构建，我们很高兴能壮大社区。

🌟 贡献方式

• 🐛 错误报告：发现问题？请报告！
• ✨ 功能请求：有新功能的想法？
• 📖 文档：帮助改进我们的指南
• 🔧 代码：提交增强功能的拉取请求
• 🎓 学习：分享使用这个项目的经验

🚀 开始贡献

1. 分叉 仓库
2. 克隆 你的分叉：git clone https://github.com/yourusername/service-health-mcp.git
3. 创建分支：git checkout -b feature/amazing-feature
4. 进行更改 并彻底测试
5. 提交：git commit -m "Add amazing feature"
6. 推送：git push origin feature/amazing-feature
7. 打开拉取请求 并提供详细描述

📋 贡献指南

• 代码风格：遵循现有的TypeScript模式
• 安全性：维护SSRF防护标准
• 测试：为新功能添加测试
• 文档：对任何更改更新文档
• 提交消息：使用清晰、描述性的提交消息

查看 CONTRIBUTING.md 获取详细指南。

---

🗺️ 路线图

🎯 阶段1：核心稳定性（当前）

• ✅ HTTP/HTTPS健康检查
• ✅ 企业级安全（SSRF防护）
• ✅ Claude桌面版集成
• ✅ 专业文档

🎯 阶段2：数据库支持（下一阶段）

• 🔄 PostgreSQL健康检查
• 🔄 MySQL/MariaDB支持
• 🔄 Redis连接测试
• 🔄 MongoDB健康监测

🎯 阶段3：高级功能

• 📊 多服务仪表盘
• 📈 健康历史跟踪
• 🔔 网络钩子通知
• ⏰ 定时监测

🎯 阶段4：企业级

• ☁️ 云集成（AWS, Azure, GCP）
• 🐳 Docker容器化
• 🔐 认证支持
• 📊 Prometheus指标导出

💡 欢迎社区反馈！

打开一个问题来建议功能或对优先级进行投票。

---

📜 许可证

MIT许可证 - 详情请查看 LICENSE 文件。

简而言之：你可以自由使用、修改和分发这个项目，只需包含许可证声明。

---

🙏 致谢

• 🤖 Anthropic 提供Claude AI辅助和MCP协议
• 🏗️ MCP社区 开创了这个生态系统
• 🌟 开源贡献者 使这样的项目成为可能
• 📚 学习社区 鼓励AI辅助开发

---

📞 支持与社区

📚 文档

• 快速开始指南 - 完整的安装说明
• 开发设置 - 适合刚接触MCP的开发者
• API参考 - 完整的技术文档
• 安全详情 - 安全考虑和最佳实践

💬 获取帮助

• 🐛 问题 - 错误报告和功能请求
• 💭 讨论 - 社区问答和想法交流

🔗 联系我们

• 👩‍💻 GitHub个人资料 - 关注获取更新

---