Content
# Zephyr MCP Agent
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 Framework Integration
- **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 Distributed Tracing
- **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
- **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 core class
├── opentelemetry_integration.py # OpenTelemetry integration module
├── http_server.py # 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 Operations
- **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
- **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 Operations
- **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
The project now supports automatic virtual environment detection and activation, ensuring the MCP server always runs in the correct environment.
#### Startup Methods
**Method 1: Using Launcher (Recommended)**
```bash
# Start from project root
python start_mcp_server.py
```
**Method 2: Direct MCP Server Execution**
```bash
# MCP server will automatically detect and activate virtual environment
python src/mcp_server.py
```
#### Virtual Environment Management
- **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 development environment (with west, git, twister)
### Installation Steps
1. Clone repository:
```bash
git clone https://github.com/your-username/zephyr_mcp.git
cd zephyr_mcp
```
2. Install dependencies:
```bash
pip install agno==2.3.2
```
3. Start 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": "en",
"available": ["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": "",
"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 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": "",
"Langsmith-Project": ""
},
"api_key": "",
"project_name": ""
}
}
```
#### Supported Exporters
- **console**: Output to console
- **otlp**: Export to remote service using OTLP protocol
#### Agno Instrumentor Integration
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 Endpoints
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 Documentation
```bash
GET http://localhost:8001/api/docs
```
## 🔧 Available Tools
### Zephyr Project Management Tools
# Tool List
### Zephyr Development Environment Tools
#### `setup_zephyr_environment` - Set up Zephyr Development Environment
Set up a complete Zephyr RTOS development environment according to west.yml file.
**Parameters:**
- `west_yml_url` (str): URL of west.yml file
- `project_dir` (str): Project directory path
- `manifest_rev` (Optional[str]): Manifest revision
#### `west_flash` - Flash Firmware
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` - Run Twister Tests
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 project root directory
### Git Operation Tools
#### `git_checkout` - Switch Git Reference
Switch to specified Git reference (SHA, tag or branch) in Zephyr project directory.
**Parameters:**
- `project_dir` (str): Zephyr project directory
- `ref` (str): Git reference
#### `west_update` - Update Zephyr Project
Run west update command in Zephyr project directory.
**Parameters:**
- `project_dir` (str): Zephyr project directory
#### `switch_zephyr_version` - Switch Zephyr Version
Switch to specified Zephyr version (SHA or tag) and run west update.
**Parameters:**
- `project_dir` (str): Zephyr project directory
- `ref` (str): Git reference
#### `get_zephyr_status` - Get Project Status
Get Git status information of Zephyr project.
**Parameters:**
- `project_dir` (str): Zephyr project directory
### Git Authentication and Configuration Tools
#### `git_redirect_zephyr_mirror` - Redirect to Git Mirror
Redirect Zephyr Git repository to mirror address.
**Parameters:**
- `project_dir` (str): Zephyr project directory
- `mirror_url` (str): Mirror repository URL
#### `get_git_redirect_status` - Get Redirect Status
Get Git remote redirect status.
**Parameters:**
- `project_dir` (str): Zephyr project directory
#### `set_git_credentials` - Set Git Credentials
Set Git authentication credentials (global or project-specific).
**Parameters:**
- `username` (str): Git username
- `password` (str): Git password/token
- `project_dir` (Optional[str]): Project directory (for local config)
#### `test_git_connection` - Test Git Connection
Test Git repository connection with authentication.
**Parameters:**
- `repo_url` (str): Git repository URL
- `username` (Optional[str]): Git username
- `password` (Optional[str]): Git password/token
#### `get_git_config_status` - Get Git Configuration Status
Get Git configuration status (global or project-specific).
**Parameters:**
- `project_dir` (Optional[str]): Project directory (for local config)
### Advanced Git Operations
#### `fetch_branch_or_pr` - Fetch Branch or Pull Request
Fetch a branch or pull request from a remote repository.
#### `git_rebase` - Execute Git Rebase Operation
Execute Git rebase operation in Zephyr project directory.
> Note: `source_branch`/`onto_branch` accept any Git reference (branch, tag, or commit SHA).
---
## 🔍 Module Documentation
### agent_core.py
Agent core class containing the main `ZephyrMCPAgent` class, responsible for:
- Agent initialization and configuration loading
- Tool registration and management
- Language management
- Integration with Agno framework
### opentelemetry_integration.py
OpenTelemetry integration module, providing:
- Distributed tracing initialization
- Span creation and management
- Multiple exporter support (console, OTLP)
- HTTP request automatic tracing
### http_server.py
HTTP server module, implementing:
- JSON API server
- Tool execution request handling
- 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. 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')"
# 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 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 Dependencies Not Installed**
```
Warning: OpenTelemetry dependencies not installed, distributed tracing will be disabled
```
Solution: Install OpenTelemetry dependencies or keep disabled
2. **Tool Registration Warnings**
```
Warning: Error registering tool tool_name: validation error
```
Solution: Check if tool parameter definitions are correct
3. **Port Conflict**
```
Error: Port 8001 is already in use
```
Solution: Use `--port` parameter to specify different port
### Log Levels
Use `--log-level` parameter to control log verbosity:
- `DEBUG` - Detailed debug information
- `INFO` - Regular runtime information (default)
- `WARNING` - Warning information
- `ERROR` - Error information
---
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Update documentation
5. Submit a Pull Request
## Support
For issues and questions:
- Create an issue on GitHub
- Check existing documentation
- Review error messages and suggestions provided by tools
