Zerubroberts Safetyculture MCP Server

🚀 安全文化 MCP 服務器

這是一個專為 SafetyCulture API 構建的模型上下文協議（MCP）服務器。藉助該項目，用戶在提供 API 密鑰後，就能使用自然語言查詢他們的安全文化數據，為數據查詢帶來極大便利。

✨ 主要特性

• 自然語言查詢：支持使用自然語言查詢安全文化數據，讓數據查詢更便捷。
• 數據檢查與分析：可分析檢查數據和趨勢，助力用戶深入瞭解數據情況。
• 指標比較：能夠比較不同時期和類別的安全指標，便於發現數據差異。
• 趨勢可視化：可將檢查隨時間的趨勢進行可視化展示，讓數據趨勢一目瞭然。

📦 安裝指南

1. 克隆此倉庫。
2. 安裝依賴項，執行命令：pip install -r requirements.txt。
3. 複製 example.env 到 .env，並配置您的安全文化 API 密鑰。
4. 選擇以下方法之一運行服務器：
   • run_server.bat：使用 .env 文件中的配置運行服務器。
   • run_with_key.bat YOUR_API_KEY：使用提供的 API 密鑰運行服務器。

💻 使用示例

基礎用法

要測試您的安全文化 API 密鑰是否正常工作，可執行以下命令：

test_api.bat YOUR_API_KEY

高級用法

其他測試選項：

• test_api.bat：以交互方式運行測試（提示輸入 API 密鑰）。
• test_api.bat feed YOUR_API_KEY：只測試 Feed API。
• test_api.bat url：檢查在沒有身份驗證的情況下可以訪問哪些 API URL。

使用 Claude for Desktop

1. 安裝 Claude for Desktop。
2. 將 Claude for Desktop 配置為使用此 MCP 服務器，通過編輯配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。
3. 添加以下配置：

{
    "mcpServers": {
        "safetyculture": {
            "command": "python",
            "args": [
                "/path/to/your/project/src/main.py"
            ]
        }
    }
}

4. 重啟 Claude for Desktop。
5. 使用 MCP 工具用以下問題查詢您的安全文化數據：
   • “過去三個月中這個站點完成了多少次檢查？”
   • “比較報告的傷害在該類別中的任何趨勢”

📚 詳細文檔

可用工具

身份驗證

• authenticate：使用 API 密鑰與安全文化 API 進行身份驗證。

檢查數據（使用 Feed API）

• get_inspections：獲取特定時間段的安全文化檢查。
• get_inspection_trends：分析隨時間的安全文化檢查趨勢。
• compare_injury_reports：比較兩個時間段的傷害報告。

行動數據（使用 Feed API）

• get_actions：獲取特定時間段的安全文化行動。
  • 按狀態過濾（例如，“進行中”、“完成”、“overdue”）。
  • 按優先級過濾（例如，“低”、“中”、“高”）。
  • 查看每個行動的詳細信息。
• get_action_details：通過 ID 獲取特定行動的詳細信息。

關於 Feed API

此 MCP 服務器使用安全文化 Feed API，該 API 提供了一種簡單的方式來訪問資源集合：

• /feed/inspections：用於列出帶有各種過濾參數的檢查。
• /feed/actions：用於列出帶有各種過濾參數的行動。

當需要列出多個項目時，Feed API 建議優先於單獨的資源端點。

開發

項目結構

.
├── README.md
├── requirements.txt
├── example.env
└── src/
    ├── main.py                      # 主入口點
    ├── safetyculture_api/           # 安全文化 API 客戶端
    │   ├── __init__.py
    │   └── client.py                # API 客戶端實現
    ├── tools/                       # MCP 工具
    │   ├── __init__.py
    │   └── inspection_tools.py      # 檢查和行動工具
    └── utils/                       # 工具模塊
        ├── __init__.py
        ├── analysis.py              # 數據分析實用程序
        ├── config.py                # 配置管理
        └── date_utils.py            # 日期解析實用程序

開發日誌

初始設置

• 創建項目結構。
• 設置 Git 倉庫。
• 添加 README 和 requirements。
• 實現安全文化 API 客戶端。
• 添加 MCP 工具以查詢檢查數據。
• 添加用於日期解析和數據分析的工具模塊。
• 添加配置管理。