🚀 安全文化 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 工具以查询检查数据。
• 添加用于日期解析和数据分析的工具模块。
• 添加配置管理。