🛠️ MCP-FreeCAD 統合

**注:**このリポジトリは現在開発中です。毎日コミットが行われ、互換性を破る変更が発生する可能性があります。

このプロジェクトは**、モデルコンテキストプロトコル（MCP）**を用いて、AIアシスタントとFreeCAD CADソフトウェア間の堅牢な統合を実現します。これにより、外部アプリケーションは標準化されたインターフェースを介してFreeCADと連携できるようになり、複数の接続方法と専用ツールが提供されます。

クイックスタート（推奨：AppImage + ランチャー）

最も信頼性の高いセットアップを行うには、次の手順に従ってください。

1. 環境設定（1回限り） ：セットアップスクリプトを実行します。これにより、リポジトリが~/.mcp-freecadにクローンされ、Python仮想環境が作成され、最新の安定版FreeCAD AppImageがダウンロード・解凍され、サーバーがそれを使用するように設定されます。

   curl -sSL https://raw.githubusercontent.com/jango-blockchained/mcp-freecad/main/scripts/bin/setup_freecad_env.sh | bash

   または、リポジトリのクローンを作成し、

2. MCP サーバーを実行します。インストーラー スクリプト (venv がアクティブであることを確認してサーバーを実行するだけ) またはインストールされている場合はグローバル コマンドを使用します。

   # Option A: Run via the installer script in the default location ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.sh # Option B: Run the global command (if installed via install-global.sh) mcp-freecad

これにより、ダウンロードして抽出した AppImage を使用して、推奨されるlauncherメソッドを使用して MCP サーバーが起動します。

Docker サポート

展開と分離を容易にするために、MCP-FreeCAD を Docker コンテナで実行することもできます。

Docker Compose で実行

1. コンテナを起動します:

   docker compose up

2. 最初から構築する(変更を加えた場合):

   docker compose build --no-cache docker compose up

Docker コンテナは次のポートを公開します。

• 8080: MCPサーバー

• 12345: FreeCAD サーバー

Dockerの設定

Docker のセットアップは次のものから構成されます。

• Dockerfile : Python 3.12でコンテナを定義し、依存関係をインストールし、環境をセットアップします

• docker-compose.yml : サービス、ポート、ボリューム、再起動ポリシーを設定します

• .dockerignore : コンテナから不要なファイルを除外します

このアプローチは、CI/CD パイプラインや、MCP-FreeCAD 環境をシステムから分離する必要がある場合に特に役立ちます。

🔄 MCP フローチャート

このフローチャートは、主要なコンポーネントと、 freecad_connection_manager.pyによって選択された様々な接続方法が、FreeCAD 内でどのように様々なコマンド実行方法をもたらすかを示しています。信頼性の観点から推奨されるのは、 AppRunを介して抽出された AppImage でよく使用されるlauncher方式です。

より詳細なフローチャートについては、 FLOWCHART.md を参照してください。

🔄 コアコンポーネント

1. FreeCAD MCP サーバー ( freecad_mcp_server.py )

• 説明：モデルコンテキストプロトコル（MCP）を実装したメインサーバー。AIアシスタントやその他のクライアントがMCPを介してFreeCADと通信するための中央ハブとして機能します。

• 特徴：

  • 標準の MCP リクエスト ( mcp/listTools 、 mcp/executeTool ) を処理します。

  • FreeCADConnectionを利用し、設定された方法で FreeCAD と対話します。

  • 構成に基づいてさまざまなツールセット (プリミティブ、操作、エクスポートなど) を公開します。

  • config.jsonで設定可能です。

• 使用法：

  # Start the server (uses config.json by default) python src/mcp_freecad/server/freecad_mcp_server.py # Start with a specific config python src/mcp_freecad/server/freecad_mcp_server.py --config my_config.json

2. FreeCAD 接続 ( src/mcp_freecad/freecad_connection_manager.py )

• 説明: FreeCADへの接続ロジックをカプセル化した統合Pythonインターフェース。MCPサーバー内部で使用され、直接スクリプトを記述することも可能です。

• 特徴：

  • 構成と可用性に基づいて最適な接続方法をインテリジェントに選択します。

• 方法:

  • ランチャー: (推奨) freecad_connection_launcher.pyとAppRunを使用します。

  • ラッパー: freecad_connection_wrapper.pyとfreecad_subprocess.pyを使用します。

  • サーバー: ソケット経由で実行中のfreecad_socket_server.pyに接続します。

  • ブリッジ: freecad_connection_bridge.pyを介して FreeCAD CLI を使用します。

  • Mock : テスト用に FreeCAD をシミュレートします。

  • 自動: 推奨順序 (ランチャー > ラッパー > サーバー > ブリッジ > モック) でメソッドを試行します。

• 使用方法（直接スクリプトの例） :

  from freecad_connection_manager import FreeCADConnection # Auto-connect using settings potentially from config.json # (Ensure config.json is present or provide args) fc = FreeCADConnection(auto_connect=True) if fc.is_connected(): print(f"Connected via: {fc.get_connection_type()}") version_info = fc.get_version() print(f"FreeCAD Version: {version_info}") fc.create_document("TestDocFromScript") else: print("Failed to connect to FreeCAD.")

3. FreeCAD ランチャー ( freecad_connection_launcher.py )

• 説明：FreeCAD環境の起動を処理します。通常は、抽出したAppImageからAppRunを使用します。起動された環境内でfreecad_launcher_script.pyを実行します。

• 特徴：

  • FreeCAD/AppRun のサブプロセス実行を管理します。

  • コマンドとパラメータを内部 FreeCAD スクリプトに渡します。

  • スクリプトの出力から JSON 結果を解析します。

• 使用方法：主に、 launcherメソッド（ config.jsonで設定）が選択された場合、 FreeCADConnectionによって内部的に使用されます。通常、ユーザーが直接実行することはありません。

4. FreeCAD ラッパー ( freecad_connection_wrapper.py ) とサブプロセス ( freecad_subprocess.py )

• 説明: freecad_connection_wrapper.pyは、別の Python プロセスでfreecad_subprocess.pyを起動します。freecad_subprocess.py freecad_subprocess.py FreeCAD モジュールをインポートし、stdio パイプを介してラッパーと通信します。

• 特徴：

  • FreeCAD モジュールのインポートを専用のプロセスに分離します。

  • 直接モジュールのインポートは可能だが、AppRun/launcher に問題がある場合、代替の接続方法を提供します。

• 使用方法： wrapperメソッドが選択されている場合（ config.jsonで設定）、 FreeCADConnectionによって内部的に使用されます。サブプロセスがimport FreeCADできるPython環境が必要です。

5. FreeCAD サーバー ( freecad_socket_server.py )

• 説明: FreeCADインスタンス内で動作するように設計されたスタンドアロンソケットサーバーFreeCADConnection 。FreeCADConnectionからの接続をリッスンします。

• 特徴：

  • 潜在的に永続的な FreeCAD インスタンスへの接続を許可します。

  • --connectモードで実行すると GUI と対話できます。

• 使用方法（FreeCAD内での手動起動） :

  # Inside FreeCAD Python Console: exec(open("/path/to/mcp-freecad/freecad_socket_server.py").read())

  MCPサーバーに接続するには、 （ docs/FREECAD_SERVER_SETUP.mdを参照）

6. FreeCAD ブリッジ ( freecad_connection_bridge.py )

• 説明: FreeCAD実行ファイルとのコマンドラインインタラクションを可能にします。モジュールの直接インポートの問題を回避しますが、速度が低下する可能性があります。

• 特徴：

  • freecad実行可能ファイルへのサブプロセス呼び出しを介して FreeCAD コマンドを実行します。

• 使用方法： bridge方式（ config.jsonで設定）が選択されている場合、 FreeCADConnectionによって内部的に使用されます。freecad freecadシステム PATH 内に存在するか、config で正しく設定されているpath内に存在している必要があります。

7. FreeCAD クライアント ( freecad_client.py )

• 説明: FreeCADConnectionインターフェイスと直接対話するためのコマンドライン ユーティリティ (MCP サーバーではなく、接続方法のテスト/デバッグ用)。

• 特徴：

  • ターミナルから特定のFreeCADConnectionコマンド (プリミティブの作成、バージョンの取得など) をテストできます。

  • config.jsonを使用して接続設定を決定します。

• 使用例：

  # Test connection and get version python freecad_client.py version # Create a box using the configured connection method python freecad_client.py create-box --length 20 --width 10

🔄 プロジェクト構造

MCP-FreeCAD プロジェクトは、次のディレクトリ構造で構成されています。

スクリプトの詳細については、 scripts/README.md を参照してください。

⚙️ インストールとセットアップの詳細

このセクションでは、さまざまなインストールおよびセットアップ オプションについて詳しく説明します。

推奨設定: AppImage + ランチャー (詳細な手順)

これには 2 つの主なスクリプトが含まれます。

1. scripts/bin/setup_freecad_env.sh : 環境を準備します。

   • リポジトリを~/.mcp-freecadに複製または更新します。

   • Python 仮想環境 ( .venv ) を作成/更新し、要件をインストールします。

   • download_appimage.pyを実行して、最新の安定した FreeCAD Linux AppImage を~/.mcp-freecadに取得します。

   • extract_appimage.pyを実行します。

     • ダウンロードした AppImage を~/.mcp-freecad/squashfs-rootに抽出します。

     • 正しい絶対パスでconnection_method: launcherとuse_apprun: trueを使用するように~/.mcp-freecad/config.jsonを更新します。

   • 実行方法: curl -sSL <URL>/setup_freecad_env.sh | bashまたは./scripts/bin/setup_freecad_env.sh

2. scripts/bin/mcp-freecad-installer.sh : サーバーを実行します。

   • 注：名前にもかかわらず、このスクリプトは完全なインストールを実行しません。主にリポジトリが最新であることを確認し、仮想環境をアクティブ化し、 freecad_mcp_server.pyを起動します。

   • 環境 (AppImage のダウンロード/抽出) がsetup_freecad_env.shまたは手動で準備されていることを前提としています。

   • 実行方法: ~/.mcp-freecad/scripts/bin/mcp-freecad-installer.shまたはmcp-freecad (グローバル コマンド)。

その他のインストール方法

グローバルインストール ( install-global.sh )

• リポジトリ内のmcp-freecad-installer.shを指すシンボリック リンクmcp-freecadを/usr/local/binに作成します。

• どこからでもmcp-freecad実行できます。

• 推奨されるランチャー方法を使用する場合は、最初にsetup_freecad_env.shを使用して環境を設定する必要があります。

手動インストール

• リポジトリをクローンします。

• venv を作成し、要件をインストールします。

• AppImage を手動でダウンロードして抽出します。python python download_appimage.pyとpython extract_appimage.py /path/to/downloaded.AppImage自分で実行します。

• サーバーを実行します: python freecad_mcp_server.py 。

🚀 MCP サーバーの使用

これは、Claude などの AI アシスタントを使用して FreeCAD と対話する主な方法です。

MCPサーバーの起動

サーバーが実行され、MCP クライアントからの接続をリッスンします。

MCPクライアントの接続

MCP互換クライアントを使用してください。リファレンスmcp clientを使用した例:

または、MCP ドキュメントにあるようなクライアント スクリプトがある場合は、 uvを使用します。

代替案: 統合サーバーでFreeCADを起動する

次のコマンドを使用して、統合サーバーで FreeCAD を起動することもできます。

これにより FreeCAD が起動し、内部のサーバーが自動的に起動します。

MCP サーバー構成 ( config.json )

config.jsonファイルはサーバーのさまざまな側面を制御します。以下は、 extract_appimage.py実行した後の推奨ランチャー設定を反映した例です。

注: 例のパスを実際の絶対パスに置き換えてください。

統合オプションの詳細については、 FREECAD_INTEGRATION.md を参照してください。

🛠️ 利用可能なMCPツール

MCPサーバーは現在、以下のコアツールを公開しています。追加のツールセットも計画されています。

• freecad.create_document : 新しいドキュメントを作成します。

• freecad.list_documents : 開いているすべてのドキュメントを一覧表示します。

• freecad.list_objects : 特定のドキュメント(またはアクティブなドキュメント)内のオブジェクトを一覧表示します。

• freecad.create_box : ボックス プリミティブを作成します。

• freecad.create_cylinder : 円柱プリミティブを作成します。

• freecad.create_sphere : 球プリミティブを作成します。

• freecad.create_cone : 円錐プリミティブを作成します。

• freecad.boolean_union : 2 つのオブジェクト間でブール結合 (結合) を実行します。

• freecad.boolean_cut : 2 つのオブジェクト間でブールカット (差異) を実行します。

• freecad.boolean_intersection : 2 つのオブジェクト間のブール交差 (共通) を実行します。

• freecad.move_object : オブジェクトを新しい絶対位置に移動します。

• freecad.rotate_object : 指定された角度でオブジェクトを回転します。

• freecad.export_stl : 指定されたオブジェクト (またはすべて) を STL ファイルにエクスポートします。

(注: MCP リクエストで使用されるツール名は、クライアントとサーバーの実装の詳細に応じて、ドットの代わりにアンダースコアを使用するなど、若干異なる場合があります。正確な名前については、サーバーのmcp/listTools出力を参照してください。)

📝 MCPインタラクションの例

AI アシスタントで MCP サーバーを使用する概念的な例を次に示します。

ボックスの作成とエクスポート

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

• MCP サーバー接続の問題:

  • python src/mcp_freecad/server/freecad_mcp_server.pyエラーなしで実行できることを確認してください。ターミナルの出力を確認してください。

  • 関連する場合はファイアウォールの設定を確認してください ( stdioの場合はそうではありません)。

  • config.jsonが有効な JSON であることを確認します。

• FreeCAD 接続の問題 (特に :

  • extract_appimage.py。AppImage が正しく抽出され、 config.jsonが更新されたことを確認します。

  • config.json: freecadセクション内のすべての絶対パスがシステムに正しいことを確認します。

  • 権限の確認: squashfs-root/AppRunに実行権限 ( chmod +x ) があることを確認します。

  • ログを確認する: mcp_freecad.log (ログ記録が開始されるとプロジェクト ルートに作成されます)、 freecad_server_stdout.log 、 freecad_server_stderr.logを調べて、 freecad_connection_launcher.py 、 AppRun 、または FreeCAD プロセス自体からのエラーを確認します。

  • 環境変数： AppRunライブラリを見つけられない場合は、 LD_LIBRARY_PATHとPYTHONPATHが正しく設定されていることを確認してください。Cursorを使用している場合は.cursor/mcp.json内で、ターミナルでテストしている場合は手動でエクスポートされている可能性があります。extract_appimage.pyスクリプトextract_appimage.py 、この必要性を軽減することを目的としていますが、影響が出る可能性があります。

  • ヘッドレスの問題：FreeCAD は、完全にヘッドレス（ QT_QPA_PLATFORM=offscreen ）で動作する場合、問題が発生することがあります。ログで GUI 関連のエラーを確認してください。

• server: freecad_socket_server.pyがアクティブな FreeCAD インスタンス内で実行され、 config.jsonで設定された正しいホスト/ポートでリッスンしていることを確認します。

• bridge：FreeCADがシステム全体にインストールされ、ターミナルでfreecadコマンドが動作することを確認してくださいconfig.jsonのfreecad_pathを確認してください。

• MCP SDK が見つかりません: pip install modelcontextprotocolでインストールしてください。

• Python パスの問題: 推奨される AppImage セットアップを使用していない場合に FreeCAD モジュールが見つからない場合は、 PYTHON_INTERPRETER_SETUP.mdを参照してください。

📄 ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。

🖥️ カーソル統合

MCP サーバーは、Cursor IDE などのツールとの統合用に設計されています。

1. Cursor の設定：Cursor の設定（設定 > 機能 > MCP サーバー > 新しい MCP サーバーの追加）で MCP サーバーを追加します。必要な環境変数と作業ディレクトリを設定し、Python スクリプトを直接実行するように設定します。.cursor .cursor/mcp.jsonの設定例は以下のとおりです。

   { "mcpServers": { "mcp-freecad": { "command": "python3", // Command to run python "args": [ "src/mcp_freecad/server/freecad_mcp_server.py" // Corrected script path ], "env": { // Environment variables needed for headless AppRun "QT_QPA_PLATFORM": "offscreen", "DISPLAY": "", "FREECAD_CONSOLE": "1", "PYTHONNOUSERSITE": "1", // These might be needed if AppRun doesn't set them automatically "LD_LIBRARY_PATH": "/path/to/mcp-freecad/squashfs-root/usr/lib:/path/to/mcp-freecad/squashfs-root/usr/Ext:...", "PYTHONPATH": "/path/to/mcp-freecad/squashfs-root/usr/lib/python3.11/site-packages:..." }, "cwd": "/path/to/mcp-freecad" // Set working directory to project root } // ... other servers like memory ... } }

   /path/to/mcp-freecad 必要に応じて、

2. カーソルを再起動: 構成の変更を有効にするには、カーソルを完全に再起動します。

3. サーバー通信: サーバーはデフォルトでstdioトランスポートを使用します（ config.jsonのserver.mcp.transportで設定）。これはCursorの通信プロトコルと互換性があります。エラーはMCPエラーレスポンスを介してCursorに報告されます。

カーソル固有の考慮事項

• freecad_mcp_server.pyスクリプトはデフォルトでconfig.json読み込みます。このファイル、特にextract_appimage.pyによって更新されたfreecadセクションの設定が正しいことを確認してください。

• .cursor/mcp.jsonに設定された環境変数は、Cursor が提供する環境内でlauncherメソッドが正しく動作できるようにするために重要です。

📋 利用可能なオプションとユースケース

🔧 接続方法

1. ランチャー接続（推奨）

   • 抽出したAppImageからAppRunを使用します。最も信頼性が高いです。

   • extract_appimage.pyによって自動的に構成されます。

   • 設定（ config.json ）：GXP19

2. ラッパー接続

   • FreeCAD ロジックを別の Python サブプロセスで実行します。AppImage/AppRun で問題が発生する場合に適した代替手段です。

   • 設定（ config.json ）：GXP20

3. ソケットサーバー接続

   • FreeCAD 内でfreecad_socket_server.pyを実行する必要があります。

   • FreeCAD を永続的なバックグラウンド サーバーとして実行する場合使用します。

   • 設定（ config.json ）：GXP21

4. CLI ブリッジ接続

   • freecadコマンドラインツールを使用します。速度が遅くなり、信頼性が低くなる可能性があります。

   • 設定（ config.json ）：GXP22

5. 模擬接続

   • FreeCAD なしでのテスト用。

   • 設定（ config.json ）：GXP23

6. 自動接続

   • 利用可能な最適な方法 (ランチャー > ラッパー > サーバー > ブリッジ > モック) を自動的に選択します。

   • connection_methodが欠落しているか、 "auto"に設定されている場合のデフォルト。

🛠️ ツールのカテゴリーとユースケース

1. FreeCADの基本操作

   • 必須文書管理

   • 使用例:

     • 新しいドキュメントを作成する

     • プロジェクトの保存と読み込み

     • さまざまな形式へのエクスポート

     • ドキュメント構造の管理

2. モデル操作

   • オブジェクトの変換と変更

   • 使用例:

     • オブジェクトを正確に回転させる

     • 3D空間でオブジェクトを移動する

     • スケーリングモデル

     • ミラーとコピーの作成

     • ブール演算（結合、切断、交差）

3. 測定ツール

   • 分析と検証

   • 使用例:

     • 距離測定

     • 角度計算

     • 表面積分析

     • 体積計算

     • 質量特性

4. 原始創造

   • 基本的な形状生成

   • 使用例:

     • 箱と円柱の作成

     • 球体を生成する

     • 円錐とトーラスを作る

     • 正多角形の作成

     • 楕円を描く

5. 輸出入業務

   • ファイル形式の変換

   • 使用例:

     • STEPファイルのエクスポート/インポート

     • IGES形式の処理

     • DXFファイルの処理

     • 3Dプリント用のSTLエクスポート

6. コード生成

   • 自動コード作成

   • 使用例:

     • Pythonスクリプト生成

     • OpenSCADコードエクスポート

     • CNC用Gコード生成

     • 3Dプリンター設定の最適化

💻 統合シナリオ

1. カーソルIDE統合

   • 開発環境の統合

   • 使用例:

     • IDEからの直接モデル操作

     • リアルタイムフィードバック

     • デバッグログ

     • エラー追跡

2. AIアシスタント統合

   • AIを活用した設計自動化

   • 使用例:

     • 自然言語モデルの作成

     • 自動化された設計変更

     • パラメータの最適化

     • 設計検証

3. コマンドラインの使用

   • スクリプトと自動化

   • 使用例:

     • バッチ処理

     • 自動テスト

     • CI/CD統合

     • コマンドラインツール

🎯 一般的なユースケースの例

1. ラピッドプロトタイピング

2. 自動処理

⚙️ 設定オプション

1. サーバー構成

2. ツールの有効化

3. デバッグ構成

特徴

• MCPプロトコルを介してAIアシスタントをFreeCADに接続します

• プログラムで 3D モデルを作成および操作する

• プリミティブ形状（ボックス、円柱、球、円錐）のサポート

• ブール演算（和、積、切取り）

• オブジェクトの変換（移動、回転）

• モデルをSTL形式にエクスポート

• 文書とオブジェクトの管理

前提条件

• Python 3.8以降

• 推奨: 信頼性の高いlauncher接続方法のための FreeCAD AppImage ( scripts/bin/setup_freecad_env.shを使用してダウンロードおよび抽出)。

• あるいは、FreeCAD 0.20+ のシステム インストール ( bridgeまたはserverメソッドの場合、信頼性が低くなる可能性があります)。

• Git (リポジトリのクローン作成用)。

依存関係はpyproject.tomlを介して管理され、セットアップ中に仮想環境にインストールされます。

利用可能なツール

（このセクションは上記のリストと重複しており、わかりやすくするために統合しています）

MCP 経由で利用できる現在実装されているツールは次のとおりです。

ドキュメント管理

• freecad.create_document

• freecad.list_documents

• freecad.list_objects

3Dプリミティブ

• freecad.create_box

• freecad.create_cylinder

• freecad.create_sphere

• freecad.create_cone

ブール演算

• freecad.boolean_union

• freecad.boolean_cut

• freecad.boolean_intersection

変革

• freecad.move_object

• freecad.rotate_object

輸出

• freecad.export_stl

測定、その他のインポート/エクスポート形式、およびコード生成をカバーする追加ツールは、将来のリリースで計画されています。

テスト

このプロジェクトには、システムの機能を検証するためのエンドツーエンド (E2E) テストが含まれています。

エンドツーエンドテスト

これらのテストでは、MCP プロトコルを使用して、クライアントの観点から相互作用を検証します。

すべての E2E テストを実行するには:

E2E テストはtests/e2e/ディレクトリにあり、機能別に整理されています。

新しいE2Eテストの作成

新しい E2E テストを追加するには:

1. tests/e2e/ディレクトリに新しいテストファイルを作成します。

2. 適切な基本テストクラス（ MCPClientTestBase ）を拡張します。

3. MCPクライアントを使用してツールと対話するテストメソッドを追加します

4. テストランナーでテストを実行する

例については、既存のテスト ファイルを参照してください。

ドキュメント

このプロジェクトには、さまざまな側面に関するいくつかのドキュメント ファイルが含まれています。

• PYTHON_INTERPRETER_SETUP.md - Pythonインタープリターの設定方法

• FREECAD_SERVER_SETUP.md - サーバーセットアップガイド

• FREECAD_INTEGRATION.md - FreeCAD の統合方法

• FLOWCHART.md - 詳細なフロー図

• OPTIMIZATION_FEATURES.md - パフォーマンス最適化ガイド

• scripts/README.md - スクリプトのドキュメント

AI アシスタントの詳細な使用方法と例については、 AI_ASSISTANT_GUIDE.mdを参照してください。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

謝辞

• 素晴らしいCADソフトウェアを開発するFreeCAD開発チーム

• モデルコンテキストプロトコル（MCP）SDKのAnthropicとClaude