tinysa-mcp

tinysa-mcp

シリアルポート経由で TinySA を操作する MCP サーバー

申し訳ありません。現在試験中のため、正常に動作することを保証できません。

概要

このプロジェクトは、シリアルポート経由で TinySA デバイスを操作するために設計された MCP サーバーです。pyserial、httpx、numpy、Pillow、FastMCP などの Python ライブラリを活用し、デバイスへの接続、コマンドの実行、デバイスのバージョン情報の取得を行うツールベースのインターフェースを提供します。

アーキテクチャとスレッドモデル

このプロジェクトでは、Tkinter ベースの GUI と MCP サーバーの両方を使用します。Tkinter はメインスレッドで実行する必要があるため、次の設計を採用しています。

flowchart TD
    subgraph MainThread
        A[main()] --> B[tk.Tk() & TinySALogMonitor]
        B --> C[root.mainloop()]
    end
    subgraph MCPThread
        D[run_mcp_server(mcp_server)]
        D --> E[mcp_server.run()]
    end
    E -- log_callback --> F[log_monitor.log_queue]
    F -- root.afterで定期ポーリング --> B
    D -- サーバー終了時 --> G[root.after(0, root.destroy)]

• Tkinter GUI はメインスレッドで実行します：
  メインスレッドで Tkinter のルートウィンドウを初期化し、メインイベントループを開始します。すべての GUI 操作はこのスレッドで実行します。

• MCP サーバーはバックグラウンドスレッドで実行します：
  Python の threading.Thread を使用して、MCP サーバーを別のスレッドで起動します。これにより、サーバーは GUI と並行してリクエストを処理できます。

• キューを介したスレッドセーフな通信：
  MCP サーバー（またはほかのバックグラウンドスレッド）からのログメッセージやその他のデータは、queue.Queue を使って GUI に送信します。GUI は root.after を使って定期的にこのキューを確認し、安全に表示を更新します。

• 正常なシャットダウン：
  MCP サーバーが停止すると、root.after(0, root.destroy) を使って GUI の終了をスケジュールし、すべての Tkinter 操作がメインスレッドで実行されるようにします。

例（main 関数）：

def main():
    root = tk.Tk()
    log_monitor = TinySALogMonitor(root)
    mcp_server = create_mcp_server(log_monitor.add_log)
    mcp_thread = threading.Thread(target=run_mcp_server, args=(mcp_server,), daemon=True)
    mcp_thread.start()
    root.mainloop()

注意事項

• バックグラウンドスレッドから Tkinter オブジェクトにアクセスしないでください。
  スレッドセーフな通信には、必ず提供されているキューと root.after を使用してください。
• この設計により、Tkinter のスレッド要件に違反することなく、MCP サーバーと GUI を並行して実行できます。

機能

• デバイスにコマンドを送信し、応答を取得します。
• ファームウェアおよびハードウェアのバージョン情報を取得します。
• ほかのシステムと連携するための MCP ツールを提供します。
• デバイスの画面画像のキャプチャに対応し、タイムスタンプ付きでファイルに保存することもできます。

MCP ツール

以下の MCP ツールを利用できます：

• get_version：TinySA デバイスのバージョン情報を取得します。
• execute_command：TinySA デバイスにコマンドを送信し、応答を取得します。
• connect：指定したポートで TinySA デバイスに接続します。
• disconnect：TinySA デバイスを切断します。
• get_device_info：接続中のデバイスに関する詳細情報を取得します。
• capture_image：TinySA の画面画像をキャプチャし、任意でタイムスタンプ付きのファイルに保存します。

使用例

MCP クライアントを使って MCP ツールを呼び出します。たとえば、デバイスのバージョンを取得するには、次のようにします：

mcp call get_version --args '{"port": "COM4"}'

トラブルシューティング

• 接続の問題： 指定したシリアルポートが正しいこと、およびユーザーに適切な権限があることを確認してください。
• コマンドの失敗： エラーメッセージがある場合は、MCP サーバーのログを確認してください。
• 画像のキャプチャ： 画像のキャプチャ中に、デバイスから十分なデータ（307200 バイト）が返されることを確認してください。
• MCP 連携の詳細については、Model Context Protocol のドキュメントを参照してください。

資料

追加のドキュメントについては material ディレクトリを参照してください。「USB interface.txt」ファイルを AI のナレッジとして追加するとよいでしょう。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。