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個人資料 - 關注獲取更新

---