🚀 服务健康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：重启并测试
- 完全关闭并重新打开Claude桌面版
- 测试：输入
"Check if google.com is healthy" - 立即查看专业的健康报告！🎉
💻 使用示例
基础健康监测
📝 "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 |
❌ 否 | {} |
可选的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无法识别健康检查工具。
解决方案
- 验证配置语法：使用JSON验证器
- 检查文件路径：在配置中使用绝对路径
- 完全重启：完全关闭Claude桌面版，然后重新打开
- 测试构建：运行
npm run build并检查是否有错误 - 检查权限：确保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的辅助下构建，我们很高兴能壮大社区。
🌟 贡献方式
- 🐛 错误报告：发现问题？请报告！
- ✨ 功能请求：有新功能的想法？
- 📖 文档：帮助改进我们的指南
- 🔧 代码：提交增强功能的拉取请求
- 🎓 学习：分享使用这个项目的经验
🚀 开始贡献
- 分叉 仓库
- 克隆 你的分叉：
git clone https://github.com/yourusername/service-health-mcp.git - 创建分支：
git checkout -b feature/amazing-feature - 进行更改 并彻底测试
- 提交：
git commit -m "Add amazing feature" - 推送：
git push origin feature/amazing-feature - 打开拉取请求 并提供详细描述
📋 贡献指南
- 代码风格：遵循现有的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个人资料 - 关注获取更新
🚀 用 ❤️、TypeScript和Claude AI构建 | 让服务监测人人可用
⭐ 如果这个项目对你有帮助，请给它加星！ ⭐