PubChem Chemical Safety MCP Server

# PubChem Chemical Safety MCP Server 一个基于 **Model Context Protocol (MCP)** 的化学安全信息服务器，用于从化合物名称或 CID 自动获取毒理、GHS 安全分类、化学性质等信息。 ## 功能特性 - 获取化合物基础属性信息（分子式、分子量、IUPAC名称等） - 获取 GHS 安全分类信息（信号词、象形图、危害声明） - 获取毒性实验数据（LD50、LC50等） - 支持批量查询和缓存机制 - 基于 MCP 协议，可与 Claude Desktop 等 AI 客户端集成 - 支持代理访问，解决网络连接问题 ## 技术栈 - **协议**: Model Context Protocol (MCP) - **语言**: Python 3.10+ - **依赖管理**: uv - **数据源**: PubChem REST API - **缓存**: 本地文件缓存 - **HTTP客户端**: aiohttp (支持代理和重试机制) ## 安装与运行 ### 1. 安装依赖 ```bash uv sync ``` ### 2. 运行 MCP 服务器 ```bash uv run python -m pubchem_mcp.mcp_server ``` ### 3. 测试服务器 ```bash uv run verify_mcp.py ``` ## MCP 工具 服务器提供以下 3 个 MCP 工具： ### 1. `get_compound_info` 获取化合物基础信息 - **参数**: `name` (化合物名称) - **返回**: CID、分子式、分子量、IUPAC名称、SMILES等 - **示例**: `get_compound_info("aspirin")` 或 `get_compound_info("阿司匹林")` ### 2. `get_safety_info` 获取 GHS 安全分类信息 - **参数**: `cid` (PubChem化合物ID) - **返回**: 信号词、GHS象形图、危害声明、预防措施等 - **示例**: `get_safety_info(2244)` (阿司匹林的CID) ### 3. `get_toxicity_data` 获取毒性实验数据 - **参数**: `cid` (PubChem化合物ID) - **返回**: 急性毒性、生态毒性、致癌性、生殖毒性等详细数据 - **示例**: `get_toxicity_data(2244)` (阿司匹林的CID) ## 使用示例 ### Python 客户端示例 ```python import asyncio from mcp.client.stdio import stdio_client from mcp import ClientSession, StdioServerParameters async def main(): server_params = StdioServerParameters( command='uv', args=['--directory', '/path/to/project', 'run', 'python', '-m', 'pubchem_mcp.mcp_server'] ) async with stdio_client(server_params) as (stdio, write): async with ClientSession(stdio, write) as session: await session.initialize() # 获取化合物信息 result = await session.call_tool('get_compound_info', { 'name': 'aspirin' }) print(result.content[0].text) asyncio.run(main()) ``` ### Claude Desktop 中使用 在 Claude Desktop 中可以直接使用自然语言查询： ``` 请查询阿司匹林的安全信息 ``` ``` 获取咖啡因的毒性数据 ``` ## 调试工具 使用 MCP Inspector 进行调试： ```bash npx -y @modelcontextprotocol/inspector uv run python -m pubchem_mcp.mcp_server ``` ## 项目结构 ``` pubchem_mcp/ ├── mcp_server.py # MCP 服务器主文件 ├── services/ │ ├── pubchem_client.py # PubChem API 客户端（支持代理和重试） │ ├── cache_service.py # 缓存服务 │ └── pubchem_service.py # PubChem 服务层 ├── models/ │ └── schemas.py # 数据模型定义 └── api/ └── routes.py # API 路由（可选） tests/ # 测试文件 manage_cache.py # 缓存管理工具 verify_mcp.py # MCP 验证工具 claude_desktop_config.json # Claude Desktop 配置示例 ``` ## 配置选项 - `CACHE_DIR`: 缓存目录路径（默认 `.cache`） - `PUBCHEM_RATE_LIMIT`: API 请求限制（默认 5 req/s） - `https_proxy`: HTTPS 代理设置 - `http_proxy`: HTTP 代理设置 ## 缓存管理 服务器使用本地文件缓存来提高性能： - **缓存位置**: `.cache/` 目录 - **缓存策略**: - 化合物信息缓存2小时 - 安全信息和毒性数据缓存1小时 - 过期文件自动删除 - **缓存管理**: 运行 `uv run manage_cache.py` 查看缓存统计 ## 网络配置 ### 代理设置 项目支持通过环境变量设置代理： ```bash export https_proxy=http://127.0.0.1:10808 export http_proxy=http://127.0.0.1:10808 ``` ### 重试机制 - 自动重试503错误（服务器繁忙） - 递增等待时间避免过于频繁的请求 - 最多重试3次 ### 请求头优化 - 使用完整的浏览器User-Agent - 添加必要的HTTP请求头（Accept、Referer等） - 支持gzip压缩 ## 测试化合物 以下化合物已测试可用： - aspirin (阿司匹林) - CID: 2244 - caffeine (咖啡因) - CID: 2519 - water (水) - CID: 962 - ethanol (乙醇) - CID: 702 - benzene (苯) - CID: 241 ## 故障排除 ### 常见问题 1. **503 错误**: 服务器繁忙，会自动重试 2. **网络连接失败**: 检查代理设置是否正确 3. **化合物未找到**: 尝试使用英文名称或化学式 ### 日志查看 服务器会输出详细的日志信息，包括： - 请求状态 - 重试信息 - 错误详情 ## 开发 ### 运行测试 ```bash uv run pytest tests/ ``` ### 代码格式化 ```bash uv run black . uv run isort . ``` ### 类型检查 ```bash uv run mypy pubchem_mcp/ ``` ## 许可证 MIT License ## 贡献 欢迎提交 Issue 和 Pull Request！