shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

service-health-mcp

一个专业的MCP服务器，使AI助手能够监控网络服务、API和HTTP端点，具有企业级安全性。适用于DevOps、监控和确保服务正常运行。

article

README

🚀 服务健康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辅助开发

📞 支持与社区

📚 文档

💬 获取帮助

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

🔗 联系我们

🚀 用 ❤️、TypeScript和Claude AI构建 | 让服务监测人人可用

⭐ 如果这个项目对你有帮助，请给它加星！ ⭐

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端