# 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！