Zephyr Rtos Mcp Server

Zephyr MCP Agent

一个基于 Agno 框架的模块化 Zephyr RTOS 开发工作流 MCP（Model Context Protocol）Agent。该 Agent 提供一套全面的 Zephyr 项目管理工具，包括项目初始化、固件烧录、测试、版本管理和 Git 操作。

A modular Zephyr RTOS development workflow MCP（Model Context Protocol）Agent based on the Agno framework. This Agent provides a comprehensive set of tools for Zephyr project management, including project initialization, firmware flashing, testing, version management, and Git operations.

---

🚀 新特性 / 新特性

模块化架构 / 模块化架构

• 模块化设计 - 将大型单体文件拆分为专注的模块，提高可维护性

• 职责分离 - 每个模块负责特定功能，便于团队协作开发

• 易于扩展 - 新增功能只需在相应模块中添加

• 模块化设计 - 将大型单体文件拆分为专注的模块，提高可维护性

• 职责分离 - 每个模块负责特定功能，便于团队协作开发

• 易于扩展 - 通过扩展相应模块添加新功能

Agno 框架集成 / Agno 框架集成

• Agno API 兼容 - 使用 Agno v2.3.2 的现代 Agent 框架

• 工具注册优化 - 使用agent.add_tool()方法注册工具

• Telemetry 支持 - 与 Agno 的 telemetry 标志兼容

• Agno API 兼容 - 使用现代 Agno v2.3.2 Agent 框架

• 工具注册优化 - 使用 agent.add_tool() 方法注册工具

• Telemetry 支持 - 与 Agno 的 telemetry 标志兼容

OpenTelemetry 分布式追踪 / OpenTelemetry 分布式追踪

• 可配置追踪 - 支持控制台和 OTLP 导出器

• HTTP 请求追踪 - 自动追踪 API 请求和工具调用

• 优雅降级 - 未安装 OpenTelemetry 依赖时自动禁用

• 可配置追踪 - 支持控制台和 OTLP 导出器

• HTTP 请求追踪 - 自动追踪 API 请求和工具调用

• 优雅降级 - 未安装 OpenTelemetry 依赖时自动禁用

多语言支持 / 多语言支持

• 国际化 - 支持中文和英文界面

• 自动检测 - 根据 HTTP 请求头自动检测语言

• 动态切换 - 在运行时动态切换语言

• 国际化 - 支持中文和英文界面

• 自动检测 - 根据 HTTP 请求头自动检测语言

• 动态切换 - 在运行时切换语言

---

📁 项目结构 / 项目结构

zephyr_mcp/
├── main.py                      # 主入口文件 / Main entry point
├── agent_core.py                # Agent核心类 / Agent core class
├── opentelemetry_integration.py # OpenTelemetry集成模块 / OpenTelemetry integration module
├── http_server.py               # HTTP服务器实现 / HTTP server implementation
├── config_manager.py            # 配置管理模块 / Configuration management module
├── language_manager.py          # 语言管理模块 / Language management module
├── config.json                  # 配置文件（自动生成） / Configuration file (auto-generated)
└── src/                         # 源代码目录 / Source code directory
    ├── tools/                   # 工具模块 / Tools module
    └── utils/                   # 工具类 / Utility classes

---

🔧 核心功能 / 核心功能

Zephyr 操作 / Zephyr 操作

• 项目初始化 - 支持认证的 Zephyr 项目初始化

• 固件烧录 - 使用各种烧录器将固件烧录到目标板

• 测试框架 - 运行 Twister 测试并返回全面的结果报告

• 版本管理 - 切换 Zephyr 版本并管理更新

• 项目初始化 - 支持认证的 Zephyr 项目初始化

• 固件烧录 - 使用各种烧录器将固件烧录到目标板

• 测试框架 - 运行 Twister 测试并提供全面的结果报告

• 版本管理 - 切换 Zephyr 版本并管理更新

认证支持 / 认证支持

• 多种认证方法 - 支持内嵌、环境变量和 Git 配置认证

• 安全凭据处理 - 支持用户名/令牌认证

• 连接测试 - 预先验证 Git 连接

• 多种认证方法 - 支持内嵌、环境变量和 Git 配置认证

• 安全凭据处理 - 支持用户名/令牌认证

• 连接测试 - 预先验证 Git 连接

Git 操作 / Git 操作

• 分支管理 - 检出特定 Git 引用（SHA、标签、分支）

• 镜像管理 - 重定向到 Zephyr Git 镜像

• 配置管理 - 设置和获取 Git 配置状态

• 分支管理 - 检出特定 Git 引用（SHA、标签、分支）

• 镜像管理 - 重定向到 Zephyr Git 镜像

• 配置管理 - 设置和获取 Git 配置状态

---

🚀 快速开始 / 快速开始

虚拟环境自动激活 / 虚拟环境自动激活

项目现在支持自动检测和激活虚拟环境，确保 MCP 服务始终在正确的环境中运行。

The project now supports automatic virtual environment detection and activation, ensuring the MCP server always runs in the correct environment.

启动方式 / 启动方式

方式 1：使用启动器（推荐） / 方式 1：使用启动器（推荐）

# 从项目根目录启动 / Start from project root
python start_mcp_server.py

方式 2：直接运行 MCP 服务 / 方式 2：直接运行 MCP 服务

# MCP服务器会自动检测并激活虚拟环境
# MCP server will automatically detect and activate virtual environment
python src/mcp_server.py

虚拟环境管理 / Virtual Environment Management

• 自动检测 - 自动查找项目根目录下的.venv、venv 等虚拟环境目录

• 跨平台支持 - 支持 Windows、Linux 和 macOS 上的虚拟环境激活

• 依赖检查 - 启动时自动检查必需的 Python 包是否已安装

• 优雅降级 - 如果虚拟环境不可用，则继续使用当前环境

• 自动检测 - 自动查找项目根目录下的 .venv、venv 等虚拟环境目录

• 跨平台支持 - 支持 Windows、Linux 和 macOS 上的虚拟环境激活

• 依赖检查 - 启动时自动检查必需的 Python 包是否已安装

• 优雅降级 - 如果虚拟环境不可用，则继续使用当前环境

环境设置 / Environment Setup

安装要求 / Prerequisites

• Python 3.8+
• Zephyr 开发环境（包含 west、git、twister）
• Zephyr 开发环境（包含 west、git、twister）

安装步骤 / Installation Steps

1. 克隆仓库：

git clone https://github.com/your-username/zephyr_mcp.git
cd zephyr_mcp

2. 安装依赖：

pip install agno==2.3.2

3. 启动 Agent：

python main.py

创建示例配置 / Create Sample Configuration

python main.py --create-config

---

⚙️ 配置说明 / Configuration

配置文件结构 / Configuration File Structure

{
  "agent_name": "Zephyr MCP Agent",
  "version": "1.0.0",
  "description": "Zephyr MCP Agent for Zephyr RTOS development",
  "tools_directory": "./src/tools",
  "utils_directory": "./src/utils",
  "log_level": "INFO",
  "port": 8001,
  "host": "localhost",
  "language": {
    "default": "zh",
    "available": ["zh", "en"],
    "auto_detect": true
  },
  "opentelemetry": {
    "enabled": false,
    "service_name": "zephyr_mcp_agent",
    "exporter": "console",
    "otlp_endpoint": "http://localhost:4318/v1/traces",
    "sampler": "always_on",
    "headers": {},
    "api_key": "",
    "project_name": "zephyr_mcp_agent"
  },
  "llm": {
    "enabled": false,
    "providers": {
      "openai": {
        "api_key": "your_openai_api_key_here",
        "model": "gpt-3.5-turbo"
      }
    }
  }
}

分布式追踪配置 / Distributed Tracing Configuration

基本配置 / Basic Configuration

{
  "opentelemetry": {
    "enabled": false,
    "service_name": "zephyr_mcp_agent",
    "exporter": "console",
    "otlp_endpoint": "http://localhost:4318/v1/traces",
    "sampler": "always_on",
    "headers": {},
    "api_key": "",
    "project_name": "zephyr_mcp_agent"
  }
}

LangSmith 集成配置 / LangSmith Integration Configuration

{
  "opentelemetry": {
    "enabled": true,
    "service_name": "zephyr_mcp_agent",
    "exporter": "otlp",
    "otlp_endpoint": "https://api.smith.langchain.com/otel/v1/traces",
    "sampler": "always_on",
    "headers": {
      "x-api-key": "lsv2_pt_your_api_key_here",
      "Langsmith-Project": "your_project_name"
    },
    "api_key": "lsv2_pt_your_api_key_here",
    "project_name": "your_project_name"
  }
}

支持的导出器 / Supported Exporters

• console：输出到控制台 / 输出到控制台
• otlp：使用 OTLP 协议导出到远程服务 / 使用 OTLP 协议导出到远程服务

Agno Instrumentor 集成 / Agno Instrumentor Integration

项目现在支持使用 Agno Instrumentor 进行自动埋点。当 openinference.instrumentation.agno 包可用时，系统会自动启用 Agno 的自动埋点功能。

项目现在支持使用 Agno Instrumentor 进行自动埋点。当 openinference.instrumentation.agno 包可用时，系统会自动启用 Agno 的自动埋点功能。

命令行参数 / Command Line Arguments

# 基本使用 / Basic usage
python main.py

# 指定配置文件 / Specify config file
python main.py --config custom_config.json

# 创建示例配置文件 / Create sample config
python main.py --create-config

# 覆盖配置参数 / Override config parameters
python main.py --port 8080 --host 0.0.0.0 --language en --log-level DEBUG

---

🌐 API 接口 / API Endpoints

启动服务后，可以通过以下 API 端点与 Agent 交互： 启动服务后，可以通过以下 API 端点与 Agent 交互：

工具调用 / Tool Execution

POST http://localhost:8001/api/tool
Content-Type: application/json
X-Trace-ID: your-trace-id

{
  "tool": "tool_name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

获取工具列表 / Get Tool List

GET http://localhost:8001/api/tools

获取工具信息 / Get Tool Information

GET http://localhost:8001/api/tool/info?name=tool_name

API 文档 / API Documentation

GET http://localhost:8001/api/docs

---

🔧 可用工具 / Available Tools

Zephyr 项目管理工具 / Zephyr Project Management Tools

setup_zephyr_environment - 设置 Zephyr 开发环境 / Set up Zephyr Development Environment

根据 west.yml 文件设置完整的 Zephyr RTOS 开发环境。 根据 west.yml 文件设置完整的 Zephyr RTOS 开发环境。

参数 / Parameters：

• west_yml_url (str): west.yml 文件的 URL / west.yml 文件的 URL
• project_dir (str): 项目目录路径 / 项目目录路径
• manifest_rev (Optional[str]): manifest 修订版本 / manifest 修订版本

west_flash - 烧录固件 / Flash Firmware

执行 west flash 命令将固件烧录到目标板。 执行 west flash 命令将固件烧录到目标板。

参数 / Parameters：

• build_dir (str): 构建输出目录 / 构建输出目录
• board (Optional[str]): 目标硬件板型号 / 目标硬件板型号
• runner (Optional[str]): 烧录器类型 / 烧录器类型

run_twister - 运行 Twister 测试 / Run Twister Tests

执行 twister 测试或构建命令并返回结构化结果。 执行 twister 测试或构建命令并返回结构化结果。

参数 / Parameters：

• platform (Optional[str]): 目标硬件平台 / 目标硬件平台
• tests (Optional[List[str]]): 测试路径或套件名称 / 测试路径或套件名称
• project_dir (str): Zephyr 项目根目录 / Zephyr 项目根目录

Git 操作工具 / Git Operation Tools

git_checkout - 切换 Git 引用 / Switch Git Reference

在 Zephyr 项目目录中切换到指定的 Git 引用（SHA、标签或分支）。 在 Zephyr 项目目录中切换到指定的 Git 引用（SHA、标签或分支）。

参数 / Parameters：

• project_dir (str): Zephyr 项目目录 / Zephyr 项目目录
• ref (str): Git 引用 / Git 引用

west_update - 更新 Zephyr 项目 / Update Zephyr Project

在 Zephyr 项目目录中运行 west update 命令。 在 Zephyr 项目目录中运行 west update 命令。

参数 / Parameters：

• project_dir (str): Zephyr 项目目录 / Zephyr 项目目录

switch_zephyr_version - 切换 Zephyr 版本 / 切换 Zephyr 版本

切换到指定的 Zephyr 版本（SHA 或标签）并运行 west update。 切换到指定的 Zephyr 版本（SHA 或标签）并运行 west update。

参数 / 参数：

• project_dir (str)：Zephyr 项目目录 / Zephyr 项目目录
• ref (str)：Git 引用 / Git 引用

get_zephyr_status - 获取项目状态 / 获取项目状态

获取 Zephyr 项目的 Git 状态信息。 获取 Zephyr 项目的 Git 状态信息。

参数 / 参数：

• project_dir (str)：Zephyr 项目目录 / Zephyr 项目目录

Git 认证和配置工具 / Git 认证和配置工具

git_redirect_zephyr_mirror - 重定向到 Git 镜像 / 重定向到 Git 镜像

将 Zephyr Git 仓库重定向到镜像地址。 将 Zephyr Git 仓库重定向到镜像地址。

参数 / 参数：

• project_dir (str)：Zephyr 项目目录 / Zephyr 项目目录
• mirror_url (str)：镜像仓库 URL / 镜像仓库 URL

get_git_redirect_status - 获取重定向状态 / 获取重定向状态

获取 Git 远程重定向状态。 获取 Git 远程重定向状态。

参数 / 参数：

• project_dir (str)：Zephyr 项目目录 / Zephyr 项目目录

set_git_credentials - 设置 Git 凭据 / 设置 Git 凭据

设置 Git 认证凭据（全局或项目特定）。 设置 Git 认证凭据（全局或项目特定）。

参数 / 参数：

• username (str)：Git 用户名 / Git 用户名
• password (str)：Git 密码/令牌 / Git 密码/令牌
• project_dir (Optional[str])：项目目录（用于本地配置） / 项目目录（用于本地配置）

test_git_connection - 测试 Git 连接 / 测试 Git 连接

使用认证测试 Git 仓库连接。 使用认证测试 Git 仓库连接。

参数 / 参数：

• repo_url (str)：Git 仓库 URL / Git 仓库 URL
• username (Optional[str])：Git 用户名 / Git 用户名
• password (Optional[str])：Git 密码/令牌 / Git 密码/令牌

get_git_config_status - 获取 Git 配置状态 / 获取 Git 配置状态

获取 Git 配置状态（全局或项目特定）。 获取 Git 配置状态（全局或项目特定）。

参数 / 参数：

• project_dir (Optional[str])：项目目录（用于本地配置） / 项目目录（用于本地配置）

高级 Git 操作 / 高级 Git 操作

fetch_branch_or_pr - 获取分支或 Pull Request / 获取分支或 Pull Request

从远程仓库获取分支或 Pull Request。 从远程仓库获取分支或 Pull Request。

git_rebase - 执行 Git rebase 操作 / 执行 Git rebase 操作

在 Zephyr 项目目录中执行 Git rebase 操作。 在 Zephyr 项目目录中执行 Git rebase 操作。

注意：source_branch/onto_branch 接受任意 Git 引用（分支、标签或提交 SHA）。

---

🔍 模块说明 / 模块文档

agent_core.py

Agent 核心类，包含主要的 ZephyrMCPAgent 类，负责： 包含主要的 ZephyrMCPAgent 类的 Agent 核心类，负责：

• Agent 初始化和配置加载 / Agent 初始化和配置加载
• 工具注册和管理 / 工具注册和管理
• 语言管理 / 语言管理
• 与 Agno 框架的集成 / 与 Agno 框架的集成

opentelemetry_integration.py

OpenTelemetry 集成模块，提供： OpenTelemetry 集成模块，提供：

• 分布式追踪初始化 / 分布式追踪初始化
• Span 创建和管理 / Span 创建和管理
• 多种导出器支持（控制台、OTLP） / 多种导出器支持（控制台、OTLP）
• HTTP 请求自动追踪 / HTTP 请求自动追踪

http_server.py

HTTP 服务器模块，实现： HTTP 服务器模块，实现：

• JSON API 服务器 / JSON API 服务器
• 工具调用请求处理 / 工具调用请求处理
• 错误处理和追踪 ID 管理 / 错误处理和追踪 ID 管理
• 多语言请求头检测 / 多语言请求头检测

config_manager.py

配置管理模块，负责： 配置管理模块，负责：

• 配置文件加载和验证 / 配置文件加载和验证
• 默认配置生成 / 默认配置生成
• 配置参数覆盖 / 配置参数覆盖

language_manager.py

语言管理模块，提供： 语言管理模块，提供：

• 多语言资源管理 / 多语言资源管理
• 语言切换功能 / 语言切换功能
• 请求头语言检测 / 请求头语言检测

---

🛠️ 开发指南 / 开发指南

添加新工具 / 添加新工具

1. 在src/tools/目录中创建新的工具模块

2. 定义工具函数并使用适当的装饰器

3. 在工具注册表中注册新工具

4. 更新相关文档

5. 在src/tools/目录中创建新的工具模块

6. 使用适当的装饰器定义工具函数

7. 在工具注册表中注册新工具

8. 更新相关文档

模块开发 / 模块开发

每个模块应该： 每个模块应该：

• 职责单一，功能专注 / 职责单一，功能专注
• 提供清晰的接口和文档 / 提供清晰的接口和文档
• 包含适当的错误处理 / 包含适当的错误处理
• 遵循项目的代码风格 / 遵循项目的代码风格

测试 / 测试

# 测试模块导入 / Test module imports
python -c "from agent_core import ZephyrMCPAgent; print('导入成功 / Import successful')"

# 测试配置加载 / Test configuration loading
python -c "from config_manager import load_config; config = load_config('config.json'); print('配置加载成功 / Config loaded successfully')"

# 测试Agent启动 / Test Agent startup
python main.py --help

---

🔄 重构优势 / 重构优势

代码质量提升 / 代码质量提升

• 可读性 - 模块化设计使代码更易于理解和维护

• 可测试性 - 可以单独测试每个模块

• 可维护性 - 修改一个模块不会影响其他功能

• 可读性 - 模块化设计使代码更易于理解和维护

• 可测试性 - 可以单独测试每个模块

• 可维护性 - 修改一个模块不会影响其他功能

开发效率提升 / 开发效率提升

• 并行开发 - 多个开发者可以同时开发不同模块

• 快速定位 - 问题定位更快速，职责更明确

• 扩展便捷 - 新增功能只需在相应模块中添加

• 并行开发 - 多个开发者可以同时开发不同模块

• 快速排查问题 - 职责明确，有助于更快地定位问题

• 便于扩展 - 只需在相应模块中添加新功能

架构现代化 / 架构现代化

• Agno框架 - 使用现代 Agent 框架，提供更好的工具管理

• OpenTelemetry - 集成分布式追踪，便于监控和调试

• 模块化设计 - 符合现代软件工程最佳实践

• Agno 框架 - 使用现代 Agent 框架，以便更好地管理工具

• OpenTelemetry - 集成分布式追踪，便于监控和调试

• 模块化设计 - 遵循现代软件工程最佳实践

---

🐛 故障排除 / 故障排除

常见问题 / 常见问题

1. OpenTelemetry依赖未安装 / 未安装 OpenTelemetry 依赖

   警告: OpenTelemetry 依赖未安装，将禁用分布式追踪功能
   Warning: OpenTelemetry dependencies not installed, distributed tracing will be disabled
   

   解决方案：安装OpenTelemetry依赖或保持禁用状态 解决方案：安装 OpenTelemetry 依赖或保持禁用状态

2. 工具注册警告 / 工具注册警告

   警告: 注册工具 tool_name 时出错: validation error
   Warning: Error registering tool tool_name: validation error
   

   解决方案：检查工具参数定义是否正确 解决方案：检查工具参数定义是否正确

3. 端口冲突 / 端口冲突

   错误: 端口 8001 已被占用
   Error: Port 8001 is already in use
   

   解决方案：使用--port参数指定其他端口 解决方案：使用--port参数指定其他端口

日志级别 / 日志级别

使用--log-level参数控制日志详细程度： 使用--log-level参数控制日志详细程度：

• DEBUG - 详细调试信息 / 详细调试信息
• INFO - 常规运行信息（默认） / 常规运行信息（默认）
• WARNING - 警告信息 / 警告信息
• ERROR - 错误信息 / 错误信息

---

📄 许可证 / 许可证

本项目采用MIT许可证 - 详见LICENSE文件。 本项目采用 MIT 许可证，详情请参见LICENSE文件。

🤝 贡献 / 贡献

欢迎贡献代码！请： 欢迎贡献！请：

1. Fork仓库 / Fork 仓库
2. 创建功能分支 / 创建功能分支
3. 为新功能添加测试 / 为新功能添加测试
4. 更新文档 / 更新文档
5. 提交Pull Request / 提交 Pull Request

📞 支持 / 支持

如有问题和疑问： 如有问题或疑问：

• 在GitHub上创建Issue / 在 GitHub 上创建 Issue
• 查看现有文档 / 查看现有文档
• 检查工具提供的错误消息和建议 / 查看工具提供的错误消息和建议