Zephyr Rtos Mcp Server

Zephyr MCP Agent

Agno フレームワークを基盤とする、モジュール型の Zephyr RTOS 開発ワークフロー用 MCP（Model Context Protocol）エージェントです。このエージェントは、プロジェクトの初期化、ファームウェアの書き込み、テスト、バージョン管理、Git 操作など、Zephyr プロジェクト管理に必要な包括的なツール一式を提供します。

Agno フレームワークを基盤とする、モジュール型の Zephyr RTOS 開発ワークフロー用 MCP（Model Context Protocol）エージェントです。このエージェントは、プロジェクトの初期化、ファームウェアの書き込み、テスト、バージョン管理、Git 操作など、Zephyr プロジェクト管理に必要な包括的なツール一式を提供します。

---

🚀 新機能 / 新機能

モジュール型アーキテクチャ / モジュール型アーキテクチャ

• モジュール型設計 - 大規模なモノリシックファイルを機能ごとのモジュールに分割し、保守性を向上させます

• 関心の分離 - 各モジュールが特定の機能を担当し、チームでの共同開発を容易にします

• 拡張が容易 - 新機能は対応するモジュールに追加するだけで実装できます

• モジュール型設計 - 大規模なモノリシックファイルを機能ごとのモジュールに分割し、保守性を向上させます

• 関心の分離 - 各モジュールが特定の機能を担当し、チームでの共同開発を容易にします

• 拡張が容易 - 新機能は対応するモジュールに追加するだけで実装できます

Agno フレームワークとの統合 / Agno フレームワークとの統合

• Agno API との互換性 - Agno v2.3.2 の最新のエージェントフレームワークを使用します

• ツール登録の最適化 - agent.add_tool() メソッドを使ってツールを登録します

• テレメトリーのサポート - Agno のテレメトリーフラグと互換性があります

• Agno API との互換性 - Agno v2.3.2 の最新のエージェントフレームワークを使用します

• ツール登録の最適化 - agent.add_tool() メソッドを使ってツールを登録します

• テレメトリーのサポート - Agno のテレメトリーフラグと互換性があります

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 サーバーが常に正しい環境で実行されます。

このプロジェクトは、仮想環境の自動検出および有効化に対応しています。これにより、MCP サーバーが常に正しい環境で実行されます。

起動方法 / 起動方法

方法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. エージェントを起動します：

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エンドポイントを通じてエージェントとやり取りできます： サービスの起動後、以下のAPIエンドポイントを通じてエージェントとやり取りできます：

ツールの実行 / 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])：マニフェストのリビジョン / マニフェストのリビジョン

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バージョンを切り替える / 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.

Note: source_branch/onto_branch accept any Git reference (branch, tag, or commit SHA).

---

🔍 モジュールのドキュメント / Module Documentation

agent_core.py

メインのZephyrMCPAgentクラスを含むエージェントのコアクラスで、次の処理を担当します。 Agent core class containing the main ZephyrMCPAgent class, responsible for:

• エージェントの初期化と設定の読み込み / 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

新しいツールの追加

1. src/tools/ディレクトリに新しいツールモジュールを作成します
2. 適切なデコレーターを使用してツール関数を定義します
3. ツールレジストリに新しいツールを登録します
4. 関連ドキュメントを更新します

モジュール開発

各モジュールは次の条件を満たす必要があります。

• 単一の責任を持ち、機能を絞り込む
• 明確なインターフェースとドキュメントを提供する
• 適切なエラー処理を含める
• プロジェクトのコードスタイルに従う

テスト

# 测试模块导入 / 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 フレームワーク - 最新のエージェントフレームワークを使用し、ツール管理を改善します
• OpenTelemetry - 分散トレーシングを統合し、監視とデバッグを容易にします
• モジュール化設計 - 最新のソフトウェアエンジニアリングのベストプラクティスに従います

---

🐛 トラブルシューティング

よくある問題

1. OpenTelemetry の依存関係がインストールされていない

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

   解決策：OpenTelemetry の依存関係をインストールするか、無効のままにします

2. ツール登録に関する警告

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

   解決策：ツールのパラメーター定義が正しいか確認します

3. ポートの競合

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

   解決策：--portパラメーターを使用して別のポートを指定します

ログレベル

--log-levelパラメーターを使用して、ログの詳細度を制御します。

• DEBUG - 詳細なデバッグ情報
• INFO - 通常の実行情報（デフォルト）
• WARNING - 警告情報
• ERROR - エラー情報

---

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細はLICENSEファイルをご覧ください。

🤝 貢献

貢献を歓迎します。次の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 新しい機能のテストを追加します
4. ドキュメントを更新します
5. プルリクエストを送信します

📞 サポート

問題や質問がある場合：

• GitHubでIssueを作成します
• 既存のドキュメントを確認します
• ツールが提供するエラーメッセージと提案を確認します