内容
# 仪器MCP服务器
用于通过SCPI命令控制测试仪器的模型上下文协议（MCP）服务器。
支持安捷龙MXA/EXA频谱分析仪、罗德与施瓦茨CMW500无线通信测试仪和安捷龙直流电源。
## 功能特点
- **自然语言仪器控制** - 通过对话式AI控制仪器
- **自动发现** - 通过*IDN?自动识别仪器型号
- **YAML驱动命令** - 轻松添加新仪器，无需代码更改
- **多仪器会话** - 同时连接和控制多个仪器
- **错误处理** - 自动错误队列读取和诊断
- **AI自我学习** - AI可以探索、学习和保存新的仪器命令
## 先决条件
在安装之前，请确保您已具备：
- **Python 3.10+**
- **VISA后端**（以下之一）：
- [NI-VISA](https://www.ni.com/en-us/support/downloads/drivers/download.ni-visa.html)（Windows/Linux）
- [安捷龙IO库套件](https://www.keysight.com/find/iosuite)（Windows）
- [pyvisa-py](https://pyvisa-py.readthedocs.io/)（纯Python，有限支持）
> **注意**：如果没有VISA后端，软件包将安装但无法与仪器通信。
## 支持的仪器
| 仪器 | 类型 | 连接方式 |
|-----------|------|-----------|
| 安捷龙MXA N9020A / N9010A / EXA | 频谱分析仪 | VISA（TCP/IP/GPIB/USB） |
| 罗德与施瓦茨CMW500 | 无线通信测试仪 | VISA（TCP/IP） |
| 安捷龙66311B / 66311 | 直流电源 | VISA（GPIB） |
| 通用SCPI仪器 | 任意 | VISA |
## 安装
### 使用uv（推荐）
```bash
# 从PyPI安装
uv tool install instrument-mcp
# 或从本地源码安装
uv tool install .
# 或开发模式安装
uv tool install --editable .
```
### 使用pip
```bash
pip install instrument-mcp
```
### 从源码安装
```bash
git clone https://github.com/yourusername/instrument-mcp.git
cd instrument-mcp
pip install -e .
```
## 使用
### 作为独立的MCP服务器
```bash
# 启动服务器（stdio模式，用于MCP客户端）
instrument-mcp
# 或使用Python模块
python -m instrument_mcp.server
# 使用uv运行（无需全局安装）
uv run instrument-mcp
```
### 在Claude Desktop中配置
将以下内容添加到您的Claude Desktop配置（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"instrument": {
"command": "instrument-mcp"
}
}
}
```
或使用uv（如果未全局安装）：
```json
{
"mcpServers": {
"instrument": {
"command": "uv",
"args": ["run", "instrument-mcp"]
}
}
}
```
或使用完整路径：
```json
{
"mcpServers": {
"instrument": {
"command": "python",
"args": ["-m", "instrument_mcp.server"]
}
}
}
```
### 与Claude Code一起使用
```bash
# 添加到您的项目
claude mcp add instrument instrument-mcp
```
## 示例命令
连接后，您可以使用自然语言：
```
"连接到192.168.1.100的MXA"
"设置中心频率为2.4 GHz，带宽为100 MHz"
"运行峰值搜索并读取标记"
"配置谐波测量，包含7个谐波"
"获取谐波幅度值"
```
或与CMW500一起使用：
```
"连接到172.22.1.3的CMW500"
"仪器预置"
"设置LTE Band 7，带宽20MHz"
"打开小区"
"检查UE连接状态"
```
## 开发
```bash
# 开发模式安装
pip install -e ".[dev]"
# 运行测试
pytest
# 代码检查
ruff check .
# 使用MCP检查器调试
mcp dev src/instrument_mcp/server.py
```
## 项目结构
```
instrument-mcp/
├── src/instrument_mcp/
│ ├── server.py # MCP服务器入口点
│ ├── instruments.py # VISA通信层
│ └── commands/
│ ├── __init__.py # YAML命令加载器
│ ├── mxa.yaml # MXA频谱分析仪命令
│ ├── cmw.yaml # CMW500命令
│ ├── keysight_ps.yaml # 电源命令
│ └── generic.yaml # 通用SCPI命令
├── pyproject.toml
└── README.md
```
## 添加新仪器
1. 在`src/instrument_mcp/commands/`中创建新的YAML文件
2. 定义`instrument_type`、`model_keywords`和`commands`
3. 重启服务器 - 命令将自动加载
示例YAML结构：
```yaml
instrument_type: my_instrument
description: 我的测试仪器
model_keywords:
- "MYMODEL"
- "MYBRAND"
commands:
- name: my_command
description: 做一些有用的事情
params:
- name: param1
type: string
description: 参数
default: "default_value"
scpi_template:
query: "MY:CMD? {param1}"
```
## 故障排除
### "No module named 'pyvisa'" 或 VISA错误
安装VISA后端：
```bash
# 选项1：NI-VISA（Windows推荐）
# 从https://www.ni.com/en-us/support/downloads/drivers/download.ni-visa.html下载
# 选项2：pyvisa-py（纯Python，有限支持）
pip install pyvisa-py
```
### 连接超时
- 验证仪器是否已开机且网络可达：`ping 192.168.1.100`
- 检查仪器是否未被其他软件锁定
- 验证VISA地址格式：`TCPIP::IP::INSTR`，`GPIB0::5::INSTR`
### 保存后未找到命令
重启MCP服务器以重新加载 `.instrument_mcp/` 目录中的命令。
## 发布检查清单（维护者）
在发布到PyPI之前：
- [ ] 更新`pyproject.toml`中的版本号
- [ ] 更新`CHANGELOG.md`
- [ ] 运行测试：`pytest`
- [ ] 运行代码检查：`ruff check .`
- [ ] 构建软件包：`python -m build`
- [ ] 测试安装：`pip install dist/*.whl`
- [ ] 上传到PyPI：`twine upload dist/*`
## 许可证
MIT License
