@codesys/mcp-toolkit

@codesys/mcp-toolkit

CODESYS V3 プログラミング環境向けの Model Context Protocol（MCP）サーバーです。このツールキットを使うと、MCP クライアント（Claude Desktop など）と CODESYS をシームレスに連携でき、CODESYS Scripting Engine を介して、プロジェクト管理、POU の作成、コード編集、コンパイルのタスクを自動化できます。

🌟 機能

• プロジェクト管理

  • 既存の CODESYS プロジェクトを開く（open_project）
  • 標準テンプレートから新しいプロジェクトを作成する（create_project）
  • プロジェクトの変更を保存する（save_project）

• POU 管理

  • プログラム、ファンクションブロック、ファンクションを作成する（create_pou）
  • 宣言部と実装部のコードを設定する（set_pou_code）
  • ファンクションブロックのプロパティを作成する（create_property）
  • ファンクションブロックのメソッドを作成する（create_method）
  • プロジェクトをコンパイルする（compile_project）

• MCP リソース

  • codesys://project/status：スクリプトのステータスと、現在開いているプロジェクトの状態を確認します。
  • codesys://project/{+project_path}/structure：指定したプロジェクトのオブジェクト構造を取得します。
  • codesys://project/{+project_path}/pou/{+pou_path}/code：指定した POU、メソッド、またはプロパティアクセサーの宣言部と実装部のコードを読み取ります。

📋 前提条件

• CODESYS V3：CODESYS V3 が正常にインストールされていること（3.5 SP21 でテスト済み）。インストール時に Scripting Engine コンポーネントを有効にしてください。
• Node.js：バージョン 18.0.0 以降を推奨します。
• MCP クライアント：MCP 対応アプリケーション（例：Claude Desktop）。

(注：CODESYS はスクリプトエンジンで内部的に Python 2.7 を使用しますが、このツールキットが連携を処理するため、Python を個別に管理する必要はありません。)

🚀 インストール

推奨されるインストール方法は、npm を使ったグローバルインストールです。

npm install -g @codesys/mcp-toolkit

これによりパッケージがグローバルにインストールされ、codesys-mcp-tool コマンドをシステムのターミナル PATH から利用できるようになります。

(上級ユーザーは、開発用にソースからインストールすることもできます。利用可能な場合は CONTRIBUTING.md を参照してください。)

🔧 設定（重要！）

このツールキットでは、CODESYS のインストール場所と使用するプロファイルを指定する必要があります。通常は、MCP クライアントアプリケーション（Claude Desktop など）で設定します。

推奨される設定方法（コマンドを直接指定）

一部のホストアプリケーション（Claude Desktop など）内で npx のようなラッパーを使って Node.js ツールを起動すると、環境変数（特に PATH）に問題が発生する可能性があります。そのため、MCP クライアントでは、インストール済みの codesys-mcp-tool コマンドを直接実行するように設定することを強く推奨します。

Claude Desktop の設定例（settings.json → mcpServers）：

{
  "mcpServers": {
    // ... other servers ...
    "codesys_local": {
      "command": "codesys-mcp-tool", // <<< Use the direct command name
      "args": [
        // Pass arguments directly to the tool using flags
        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile", "Your CODESYS Profile Name"
        // Optional: Add --workspace "/path/to/your/projects" if needed
      ]
    }
    // ... other servers ...
  }
}

主な手順：

1. "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe" を、使用する CODESYS.exe ファイルの正確なフルパスに置き換えます。
2. "Your CODESYS Profile Name" を、使用する CODESYS プロファイルの正確な名前に置き換えます（CODESYS の UI で確認できます）。
3. MCP クライアントアプリケーションが実行されるシステムの PATH から、codesys-mcp-tool コマンドにアクセスできることを確認します。通常、グローバルインストール（npm install -g）で利用可能になります。
4. 設定の変更を反映するため、MCP クライアントアプリケーション（例：Claude Desktop）を再起動します。

代替の設定方法（npx を使用する方法。非推奨）

一部の環境では、npx を使って起動すると、npx による実行環境の処理方法が原因と考えられる即時エラー（'C:\Program' is not recognized...）が発生することが確認されています。可能であれば、上記のコマンドを直接指定する方法を使用してください。npx を使う必要がある場合は、次のようにします。

// Example using npx (POTENTIALLY PROBLEMATIC - USE WITH CAUTION):
{
  "mcpServers": {
    "codesys_local": {
      "command": "npx",
      "args": [
        "-y", // Tells npx to install temporarily if not found globally
        "@codesys/mcp-toolkit",
        // Arguments for the tool MUST come AFTER the package name
        "--codesys-path", "C:\\Program Files\\Path\\To\\Your\\CODESYS\\Common\\CODESYS.exe",
        "--codesys-profile", "Your CODESYS Profile Name"
      ]
    }
  }
}

(注：パッケージ名の後に -- 区切り文字を追加すると npx で解決する場合がありますが、環境の問題が必ず解消されるわけではありません。)

🛠️ コマンドライン引数

codesys-mcp-toolを直接実行する場合や設定する場合は、次の引数を使用できます。

• -p, --codesys-path <path>: CODESYS.exeのフルパスです。（必須。CODESYS_PATH環境変数より優先されます。デフォルト値がありますが、これに依存することは推奨されません。）
• -f, --codesys-profile <profile>: CODESYSプロファイルの名前です。（必須。CODESYS_PROFILE環境変数より優先されます。デフォルト値がありますが、これに依存することは推奨されません。）
• -w, --workspace <dir>: ツールに渡される相対プロジェクトパスを解決するためのワークスペースディレクトリです。コマンドを起動したディレクトリがデフォルトになります（別のアプリケーションから実行した場合、予測できない場所になることがあります）。相対パスを使用する場合は、明示的に設定する必要があるかもしれません。
• -h, --help: ヘルプメッセージを表示します。
• --version: パッケージのバージョンを表示します。

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

• 接続直後に'C:\Program' is not recognized...エラーが発生する：

  • 原因： これは通常、Claude Desktopなどの環境内でnpx経由でツールを起動した場合に発生します。プロセスに渡される実行環境（PATH変数）によって、Pythonの実行など、CODESYS内部のコマンドが失敗している可能性があります。
  • 解決策： "command": "npx"ではなく、コマンドを直接（"command": "codesys-mcp-tool"）実行するようにMCPクライアントを設定してください。上記の推奨される設定方法のセクションを参照してください。

• ツールが失敗する／出力にエラーがある：

  • MCPクライアントアプリケーションのログ（例：Claude Desktopのログ）を確認してください。CODESYSスクリプトの実行時にstderrに出力されるINTEROP:メッセージやPythonのDEBUG:／ERROR:メッセージを探してください。
  • コマンドに渡した--codesys-path引数と--codesys-profile引数が正しく、スクリプトが有効なCODESYSインストールを指していることを確認してください。
  • ツールに渡すプロジェクトパスとオブジェクトパスが正しいことを確認してください（スラッシュ/を使用してください）。
  • 競合する状態（例：プロファイルをロックしている状態）で、ほかのCODESYSインスタンスが実行されていないことを確認してください。

• command not found: codesys-mcp-tool：

  • パッケージがグローバルにインストールされていることを確認してください（npm install -g @codesys/mcp-toolkit）。
  • npmのグローバルbinディレクトリがシステムのPATH環境変数に含まれていることを確認してください。npm config get prefixで場所を確認し、binサブディレクトリ（またはWindowsではメインディレクトリ自体）をPATHに追加してください。

• ログの確認：

  • Claude Desktopのログ：C:\Users\<YourUsername>\AppData\Roaming\Claude\logs\（Windows）

🤝 貢献

貢献、問題の報告、機能リクエストを歓迎します。お気軽にissuesページをご覧ください。（必要に応じて、詳細を記載したCONTRIBUTING.mdファイルを追加してください。）

📝 ライセンス

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

🙏 謝辞

• 強力なCODESYSプラットフォームとそのスクリプトエンジンを提供してくださったCODESYS GmbHチーム。
• インタラクション標準を定義したModel Context Protocolプロジェクト。
• このツールキットの改善に協力してくださるすべての貢献者とユーザー。