# 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)**
```bash
# 从项目根目录启动 / Start from project root
python start_mcp_server.py
```
**方式2: 直接运行MCP服务器 / Method 2: Direct MCP Server Execution**
```bash
# 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. 克隆仓库：
```bash
git clone https://github.com/your-username/zephyr_mcp.git
cd zephyr_mcp
```
2. 安装依赖：
```bash
pip install agno==2.3.2
```
3. 启动Agent：
```bash
python main.py
```
### 创建示例配置 / Create Sample Configuration
```bash
python main.py --create-config
```
---
## ⚙️ 配置说明 / Configuration
### 配置文件结构 / Configuration File Structure
```json
{
"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
```json
{
"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
```json
{
"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
```bash
# 基本使用 / 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
```bash
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
```bash
GET http://localhost:8001/api/tools
```
### 获取工具信息 / Get Tool Information
```bash
GET http://localhost:8001/api/tool/info?name=tool_name
```
### API文档 / API Documentation
```bash
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. 更新相关文档
1. Create new tool module in `src/tools/` directory
2. Define tool function with appropriate decorators
3. Register new tool in tool registry
4. 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
```bash
# 测试模块导入 / 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](LICENSE)文件。
This project is licensed under the MIT License - see the [LICENSE](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
