Skip to content

hakehuang/zephyr_mcp

BranchesTags

Repository files navigation

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.

🚀 新特性 / New Features

模块化架构 / Modular Architecture

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

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

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

  • Modular Design - Split large monolithic files into focused modules for better maintainability

  • Separation of Concerns - Each module handles specific functionality for team collaboration

  • Easy to Extend - Add new features by extending corresponding modules

Agno框架集成 / Agno Framework Integration

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

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

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

  • Agno API Compatible - Uses modern Agno v2.3.2 Agent framework

  • Optimized Tool Registration - Register tools using agent.add_tool() method

  • Telemetry Support - Compatible with Agno's telemetry flag

OpenTelemetry分布式追踪 / OpenTelemetry Distributed Tracing

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

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

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

  • Configurable Tracing - Supports console and OTLP exporters

  • HTTP Request Tracing - Automatically traces API requests and tool calls

  • Graceful Degradation - Automatically disables when OpenTelemetry dependencies are not installed

多语言支持 / Multi-language Support

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

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

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

  • Internationalization - Supports Chinese and English interfaces

  • Auto-detection - Automatically detects language from HTTP request headers

  • Dynamic Switching - Switch languages at runtime

📁 项目结构 / Project Structure

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

🔧 核心功能 / Core Features

Zephyr操作 / Zephyr Operations

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

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

  • 测试框架 - 运行Twister测试并返回结构化结果

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

  • Project Initialization - Initialize Zephyr projects with authentication support

  • Firmware Flashing - Flash firmware to target boards with various flashers

  • Testing Framework - Run Twister tests with comprehensive result reporting

  • Version Management - Switch between Zephyr versions and manage updates

认证支持 / Authentication Support

  • 多种认证方法 - 嵌入式、环境变量和Git配置认证

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

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

  • Multiple Authentication Methods - Embedded, environment variable, and Git config authentication

  • Secure Credential Handling - Support for username/token authentication

  • Connection Testing - Pre-flight Git connection validation

Git操作 / Git Operations

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

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

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

  • Branch Management - Checkout specific Git references (SHA, tag, branch)

  • Mirror Management - Redirect to Zephyr Git mirrors

  • Configuration Management - Set and retrieve Git configuration status

🚀 快速开始 / Quick Start

虚拟环境自动激活 / Virtual Environment Auto-activation

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

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

启动方式 / Startup Methods

方式1: 使用启动器（推荐） / Method 1: Using Launcher (Recommended)

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

方式2: 直接运行MCP服务器 / Method 2: Direct MCP Server Execution

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

虚拟环境管理 / Virtual Environment Management

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

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

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

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

  • Auto-detection - Automatically finds virtual environment directories like .venv, venv in project root

  • Cross-platform Support - Supports virtual environment activation on Windows, Linux, and macOS

  • Dependency Checking - Automatically checks if required Python packages are installed at startup

  • Graceful Degradation - Continues with current environment if virtual environment is unavailable

环境设置 / Environment Setup

安装要求 / Prerequisites

  • Python 3.8+
  • Zephyr开发环境（包含west、git、twister）
  • Zephyr development environment (with west, git, twister)

安装步骤 / Installation Steps

  1. 克隆仓库：
git clone https://github.com/your-username/zephyr_mcp.git
cd zephyr_mcp
  1. 安装依赖：
pip install agno==2.3.2
  1. 启动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: 输出到控制台 / Output to console
  • otlp: 使用 OTLP 协议导出到远程服务 / Export to remote service using OTLP protocol

Agno Instrumentor 集成 / Agno Instrumentor Integration

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

The project now supports automatic instrumentation using Agno Instrumentor. When the openinference.instrumentation.agno package is available, the system will automatically enable Agno's automatic instrumentation.

命令行参数 / 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交互： After starting the service, you can interact with the Agent through the following API endpoints:

工具调用 / 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开发环境。 Set up a complete Zephyr RTOS development environment according to west.yml file.

参数 / Parameters：

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

west_flash - 烧录固件 / Flash Firmware

执行west flash命令将固件烧录到目标板。 Execute west flash command to flash firmware to target board.

参数 / Parameters：

  • build_dir (str): 构建输出目录 / Build output directory
  • board (Optional[str]): 目标硬件板型号 / Target hardware board model
  • runner (Optional[str]): 烧录器类型 / Flasher type

run_twister - 运行Twister测试 / Run Twister Tests

执行twister测试或构建命令并返回结构化结果。 Execute twister test or build command and return structured results.

参数 / Parameters：

  • platform (Optional[str]): 目标硬件平台 / Target hardware platform
  • tests (Optional[List[str]]): 测试路径或套件名称 / Test path or suite name
  • project_dir (str): Zephyr项目根目录 / Zephyr project root directory

Git操作工具 / Git Operation Tools

git_checkout - 切换Git引用 / Switch Git Reference

在Zephyr项目目录中切换到指定的Git引用（SHA、标签或分支）。 Switch to specified Git reference (SHA, tag or branch) in Zephyr project directory.

参数 / Parameters：

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

west_update - 更新Zephyr项目 / Update Zephyr Project

在Zephyr项目目录中运行west update命令。 Run west update command in Zephyr project directory.

参数 / Parameters：

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

switch_zephyr_version - 切换Zephyr版本 / Switch Zephyr Version

切换到指定的Zephyr版本（SHA或标签）并运行west update。 Switch to specified Zephyr version (SHA or tag) and run west update.

参数 / Parameters：

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

get_zephyr_status - 获取项目状态 / Get Project Status

获取Zephyr项目的Git状态信息。 Get Git status information of Zephyr project.

参数 / Parameters：

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

Git认证和配置工具 / Git Authentication and Configuration Tools

git_redirect_zephyr_mirror - 重定向到Git镜像 / Redirect to Git Mirror

将Zephyr Git仓库重定向到镜像地址。 Redirect Zephyr Git repository to mirror address.

参数 / Parameters：

  • project_dir (str): Zephyr项目目录 / Zephyr project directory
  • mirror_url (str): 镜像仓库URL / Mirror repository URL

get_git_redirect_status - 获取重定向状态 / Get Redirect Status

获取Git远程重定向状态。 Get Git remote redirect status.

参数 / Parameters：

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

set_git_credentials - 设置Git凭据 / Set Git Credentials

设置Git认证凭据（全局或项目特定）。 Set Git authentication credentials (global or project-specific).

参数 / Parameters：

  • username (str): Git用户名 / Git username
  • password (str): Git密码/令牌 / Git password/token
  • project_dir (Optional[str]): 项目目录（用于本地配置） / Project directory (for local config)

test_git_connection - 测试Git连接 / Test Git Connection

使用认证测试Git仓库连接。 Test Git repository connection with authentication.

参数 / Parameters：

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

get_git_config_status - 获取Git配置状态 / Get Git Configuration Status

获取Git配置状态（全局或项目特定）。 Get Git configuration status (global or project-specific).

参数 / Parameters：

  • project_dir (Optional[str]): 项目目录（用于本地配置） / Project directory (for local config)

高级Git操作 / Advanced Git Operations

fetch_branch_or_pr - 获取分支或Pull Request / Fetch Branch or Pull Request

从远程仓库获取分支或Pull Request。 Fetch a branch or pull request from a remote repository.

git_rebase - 执行Git rebase操作 / Execute Git Rebase Operation

在Zephyr项目目录中执行Git rebase操作。 Execute Git rebase operation in Zephyr project directory.

🔍 模块说明 / Module Documentation

agent_core.py

Agent核心类，包含主要的ZephyrMCPAgent类，负责： Agent core class containing the main ZephyrMCPAgent class, responsible for:

  • Agent初始化和配置加载 / Agent initialization and configuration loading
  • 工具注册和管理 / Tool registration and management
  • 语言管理 / Language management
  • 与Agno框架的集成 / Integration with Agno framework

opentelemetry_integration.py

OpenTelemetry集成模块，提供： OpenTelemetry integration module, providing:

  • 分布式追踪初始化 / Distributed tracing initialization
  • Span创建和管理 / Span creation and management
  • 多种导出器支持（控制台、OTLP） / Multiple exporter support (console, OTLP)
  • HTTP请求自动追踪 / HTTP request automatic tracing

http_server.py

HTTP服务器模块，实现： HTTP server module, implementing:

  • JSON API服务器 / JSON API server
  • 工具调用请求处理 / Tool execution request handling
  • 错误处理和追踪ID管理 / Error handling and trace ID management
  • 多语言请求头检测 / Multi-language request header detection

config_manager.py

配置管理模块，负责： Configuration management module, responsible for:

  • 配置文件加载和验证 / Configuration file loading and validation
  • 默认配置生成 / Default configuration generation
  • 配置参数覆盖 / Configuration parameter overriding

language_manager.py

语言管理模块，提供： Language management module, providing:

  • 多语言资源管理 / Multi-language resource management
  • 语言切换功能 / Language switching functionality
  • 请求头语言检测 / Request header language detection

🛠️ 开发指南 / Development Guide

添加新工具 / Adding New Tools

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

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

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

  4. 更新相关文档

  5. Create new tool module in src/tools/ directory

  6. Define tool function with appropriate decorators

  7. Register new tool in tool registry

  8. Update relevant documentation

模块开发 / Module Development

每个模块应该： Each module should:

  • 职责单一，功能专注 / Have single responsibility and focused functionality
  • 提供清晰的接口和文档 / Provide clear interfaces and documentation
  • 包含适当的错误处理 / Include proper error handling
  • 遵循项目的代码风格 / Follow project code style

测试 / Testing

# 测试模块导入 / 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

🔄 重构优势 / Refactoring Benefits

代码质量提升 / Code Quality Improvement

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

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

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

  • Readability - Modular design makes code easier to understand and maintain

  • Testability - Each module can be tested independently

  • Maintainability - Modifying one module doesn't affect other functionality

开发效率提升 / Development Efficiency Improvement

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

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

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

  • Parallel Development - Multiple developers can work on different modules simultaneously

  • Quick Troubleshooting - Faster problem identification with clear responsibilities

  • Easy Extension - Add new features by extending corresponding modules

架构现代化 / Architecture Modernization

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

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

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

  • Agno Framework - Uses modern Agent framework for better tool management

  • OpenTelemetry - Integrated distributed tracing for monitoring and debugging

  • Modular Design - Follows modern software engineering best practices

🐛 故障排除 / Troubleshooting

常见问题 / Common Issues

  1. OpenTelemetry依赖未安装 / OpenTelemetry Dependencies Not Installed

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

    解决方案：安装OpenTelemetry依赖或保持禁用状态 Solution: Install OpenTelemetry dependencies or keep disabled

  2. 工具注册警告 / Tool Registration Warnings

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

    解决方案：检查工具参数定义是否正确 Solution: Check if tool parameter definitions are correct

  3. 端口冲突 / Port Conflict

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

    解决方案：使用--port参数指定其他端口 Solution: Use --port parameter to specify different port

日志级别 / Log Levels

使用--log-level参数控制日志详细程度： Use --log-level parameter to control log verbosity:

  • DEBUG - 详细调试信息 / Detailed debug information
  • INFO - 常规运行信息（默认） / Regular runtime information (default)
  • WARNING - 警告信息 / Warning information
  • ERROR - 错误信息 / Error information

📄 许可证 / License

本项目采用MIT许可证 - 详见LICENSE文件。 This project is licensed under the MIT License - see the LICENSE file for details.

🤝 贡献 / Contributing

欢迎贡献代码！请： Contributions are welcome! Please:

  1. Fork仓库 / Fork the repository
  2. 创建功能分支 / Create a feature branch
  3. 为新功能添加测试 / Add tests for new functionality
  4. 更新文档 / Update documentation
  5. 提交Pull Request / Submit a Pull Request

📞 支持 / Support

如有问题和疑问： For issues and questions:

  • 在GitHub上创建Issue / Create an issue on GitHub
  • 查看现有文档 / Check existing documentation
  • 检查工具提供的错误消息和建议 / Review error messages and suggestions provided by tools

About

zephyr mcp

Resources

Readme

License

Apache-2.0 license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages