Yamcs MCP Server

Yamcs MCP服务器

Yamcs（又一任务控制系统）的综合模型上下文协议（MCP）服务器，将Yamcs功能作为标准化的MCP工具和资源公开。

概述

Yamcs MCP服务器通过在MCP兼容客户端和Yamcs实例之间提供桥梁，使AI助手能够通过自然语言与任务控制系统进行交互。它使用具有模块化组件架构的FastMCP 2.x实现MCP协议。

特性

• 任务数据库（MDB）：访问参数、命令、算法和空间系统
• TM/TC处理：实时遥测监控和命令执行
• 链路管理：监控数据链路
• 对象存储：管理Yamcs存储中的桶和对象
• 实例管理：控制Yamcs实例和服务
• 报警管理：使用汇总统计数据监控和确认警报

安装

先决条件

• Python 3.12或更高版本
• Yamcs服务器实例（本地或远程）
• uv包管理器（推荐）或pip

使用紫外线（推荐）

# Clone the repository
git clone https://github.com/PaulMRamirez/yamcs-mcp-server.git
cd yamcs-mcp-server

# Install dependencies
uv sync

# Run the server
uv run yamcs-mcp

使用pip

# Clone the repository
git clone https://github.com/PaulMRamirez/yamcs-mcp-server.git
cd yamcs-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

# Run the server
yamcs-mcp

运行Yamcs

您需要一个正在运行的Yamcs实例。最简单的方法是使用Docker：

docker run -d --name yamcs -p 8090:8090 yamcs/example-simulation

这将以一个字母开始Yamcs simulator 包含示例遥测数据的实例。

配置

服务器可以使用环境变量或 .env 文件：

# Yamcs connection settings
YAMCS_URL=http://localhost:8090
YAMCS_INSTANCE=simulator
YAMCS_USERNAME=admin
YAMCS_PASSWORD=password

# Server toggles
YAMCS_ENABLE_MDB=true
YAMCS_ENABLE_PROCESSOR=true
YAMCS_ENABLE_LINKS=true
YAMCS_ENABLE_STORAGE=true
YAMCS_ENABLE_INSTANCES=true
YAMCS_ENABLE_ALARMS=true
YAMCS_ENABLE_COMMANDS=true

# Server settings
MCP_TRANSPORT=stdio
MCP_HOST=127.0.0.1
MCP_PORT=8000

用法

使用克劳德桌面

将服务器添加到您的Claude Desktop配置中：

{
  "mcp-servers": {
    "yamcs": {
      "command": "uv",
      "args": ["--directory", "/path/to/yamcs-mcp-server", "run", "yamcs-mcp"],
      "env": {
        "YAMCS_URL": "http://localhost:8090",
        "YAMCS_INSTANCE": "simulator"
      }
    }
  }
}

重要:

• 替换 /path/to/yamcs-mcp-server 带有yamcs mcp服务器目录的实际路径
• 这 --directory uv需要论证才能找到正确的项目
• 如果 uv 如果不在PATH中，请使用uv的完整路径（例如。， /Users/PaulMRamirez/.local/bin/uv)

可用工具

服务器公开了许多按服务器组织的工具：

MDB工具

• mdb_list_parameters -列出可用参数
• mdb_describe_parameter -获取参数详细信息
• mdb_list_commands -列出可用命令
• mdb_describe_command -获取命令详细信息
• mdb_list_space_systems -列出空间系统
• mdb_describe_space_system -获取空间系统详细信息

处理器工具

• processors_list_processors -列出可用处理器
• processors_describe_processor -获取处理器详细信息
• processors_delete_processor -删除处理器
• processors_issue_command -发出命令
• processors_subscribe_parameters -订阅参数更新

链接工具

• links_list_links -列出所有数据链接
• links_describe_link -获取详细的链接信息
• links_enable_link -启用数据链路
• links_disable_link -禁用数据链路

实例工具

• instances_list_instances -列出Yamcs实例
• instances_describe_instance -获取实例详细信息
• instances_start_instance -启动实例
• instances_stop_instance -停止实例

存储工具

• storage_list_buckets -列出存储桶
• storage_list_objects -列出bucket中的对象
• storage_upload_object -上传一个对象
• storage_download_object -下载对象

报警工具

• alarms_list_alarms -列出活动警报及其摘要计数
• alarms_describe_alarm -获取详细的报警信息
• alarms_acknowledge_alarm -确认警报
• alarms_shelve_alarm -暂时搁置警报
• alarms_unshelve_alarm 无助和警报
• alarms_clear_alarm -清除警报
• alarms_read_log -读取报警历史记录

命令工具

• commands_list_commands -列出可执行的命令
• commands_describe_command -获取详细的命令信息
• commands_run_command -执行命令（支持模拟运行）
• commands_read_log -读取命令执行历史记录

可用资源

服务器还提供只读资源：

• mdb://parameters -列出所有参数
• processors://list -列出所有处理器及其详细信息
• links://status -显示所有链接的状态
• instances://list -列出所有实例及其详细信息
• alarms://list -显示活动警报摘要

发展

建立开发环境

# Install development dependencies
uv sync --all-extras

# Install pre-commit hooks
pre-commit install

# Run tests
uv run pytest

# Run linting
uv run ruff check .

# Run type checking
uv run mypy src/

测试

运行测试套件：

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=yamcs_mcp --cov-report=html

# Run specific test file
uv run pytest tests/test_server.py

# Run with verbose output
uv run pytest -v

在没有Yamcs服务器的情况下进行测试

服务器可以在演示模式下运行，而无需连接到真正的Yamcs服务器：

# Run in demo mode (will show a warning about connection failure but continue)
uv run python -m yamcs_mcp.server

# Or use the demo script
uv run python run_demo.py

项目结构

yamcs-mcp-server/
├── src/
│   └── yamcs_mcp/
│       ├── server.py           # Main server entry point
│       ├── servers/            # MCP servers
│       │   ├── base_server.py # Base class for all servers
│       │   ├── mdb.py         # Mission Database
│       │   ├── processors.py  # TM/TC Processing
│       │   ├── links.py       # Link management
│       │   ├── storage.py     # Object storage
│       │   ├── instances.py   # Instance management
│       │   └── alarms.py      # Alarm management
│       ├── client.py          # Yamcs client management
│       ├── config.py          # Configuration
│       └── types.py           # Type definitions
├── tests/                     # Test suite
├── scripts/                   # Test scripts
└── CLAUDE.md                  # AI assistant guidance

故障排除

常见问题

执行命令时出现“输入验证错误”

问题： 出现以下错误 '{"voltage_num": 1}' is not valid under any of the given schemas

解决方案： 这 commands/run_command 该工具现在接受这两种格式。服务器将自动将JSON字符串解析为对象。

现在支持这两种格式：

✅ Args作为对象（首选）：

{
  "command": "/YSS/SIMULATOR/SWITCH_VOLTAGE_OFF",
  "args": {"voltage_num": 1}
}

✅ 参数为JSON字符串（自动解析）：

{
  "command": "/YSS/SIMULATOR/SWITCH_VOLTAGE_OFF",
  "args": "{\"voltage_num\": 1}"
}

✅ 无参数命令：

{
  "command": "/TSE/simulator/get_identification"
}

✅ 多个参数：

{
  "command": "/YSS/SIMULATOR/SET_HEATER",
  "args": {
    "heater_id": 2,
    "temperature": 25.5,
    "duration": 300
  }
}

与Yamcs的连接失败

问题： 服务器启动时无法连接到Yamcs

解决方案：

1. 确保Yamcs正在运行： docker ps | grep yamcs
2. 检查URL是否正确： curl http://localhost:8090/api
3. 即使Yamcs不可用，服务器也将继续处于演示模式

枚举序列化错误

问题： 无法序列化枚举类型的错误

解决方案： 此问题已在最新版本中修复。更新到服务器的最新版本。

贡献

欢迎投稿！请阅读我们的 贡献指南 在提交pull请求之前。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 内置于 FastMCP
• 由...驱动 Yamcs