Joern MCP Server

Joern MCP サーバー

Joern 用のシンプルな MCP サーバーです。

プロジェクトの紹介

このプロジェクトは Joern を基盤とする MCP サーバーで、開発者のコードレビューやセキュリティ分析に役立つ一連の機能を提供します。

環境要件

• Python >= 3.10（デフォルトは 3.12）および uv
• Joern

インストール手順

1. プロジェクトをローカルにクローンします。

   git clone https://github.com/sfncat/mcp-joern.git
   cd mcp-joern
   

2. Python の依存関係をインストールします。

   uv venv .venv
   source .venv/bin/activate
   uv sync
   

プロジェクト構成

├── server.py                       # MCP Server main program
├── test_mcp_client.py              # Test program for joern server and mcp tool
├── test_sc_tools.py                # Direct test program for sc tools
├── common_tools.py                 # Common utility functions
├── server_tools.py                 # Server utility functions
├── server_tools.sc                 # Scala implementation of server utility functions
├── server_tools_source.sc          # Scala implementation of server utility functions,use sourceCode to get the source code of method
├── requirements.txt                # Python dependency file
├── sample_cline_mcp_settings.json  # Sample cline mcp configuration file
└── env_example.txt                 # Environment variables example file

使用方法

1. Joern サーバーを起動します。

   joern -J-Xmx40G -J-XX:CompressedClassSpaceSize=1g -J-XX:MaxMetaspaceSize=2g \
         --server --server-host 127.0.0.1 --server-port 16162 \
         --server-auth-username user --server-auth-password password --import server_tools.sc
   Or
   joern -J-Xmx40G -J-XX:CompressedClassSpaceSize=1g -J-XX:MaxMetaspaceSize=2g \
         --server --server-host 127.0.0.1 --server-port 16162 \
         --server-auth-username user --server-auth-password password --import server_tools_source.sc
   

   JVM フラグを追加する理由。 デフォルト値はいずれも小さすぎますが、問題が発生するのは長時間使用した後だけなので、JVM のサイズ設定の問題ではなく、サーバーが停止したように見えます。

   • -XX:CompressedClassSpaceSize=1g — Joern REPL はクエリごとに 1 つのクラス（rs$line$N）をコンパイルします。デフォルトのクラス領域（128m）は数千件のクエリ後に使い果たされ、その後はすべてのクエリが NoClassDefFoundError: Could not initialize class rs$line$NNNN で失敗します。
   • -XX:MaxMetaspaceSize=2g — クラス領域に合わせてメタスペースに余裕を持たせます。
   • -J-Xmx… — CPG に応じてヒープサイズを設定します。ヒープサイズが小さすぎる場合、OOM ではなくクエリのタイムアウトが発生します。約 400 MB の CPG に対して、こちらでは -Xmx60G を使用しています。 Windows で使用する場合は、コマンドラインまたはシステム環境変数を通じて JVM のシステム変数を設定する必要がある場合があります。

   set _JAVA_OPTIONS=-Dfile.encoding=UTF-8
   

   Joern のログレベルを ERROR に設定します

   set SL_LOGGING_LEVEL=ERROR //windows
   export SL_LOGGING_LEVEL=ERROR //linux
   

   次の警告が表示される場合

   Unable to create a system terminal, creating a dumb terminal (enable debug logging for more information)
   

   環境変数を設定すると無効にできます

   set TERM=dumb
   export TERM=dumb
   

   デフォルトの動作に戻すには

   set TERM=xterm-256color
   export TERM=xterm-256color
   

2. env_example.txt を .env にコピーします。 Joern サーバーの起動設定に合わせて設定情報を変更します。

3. 接続テストを実行します。 test_mcp_client.py の情報を変更して、Joern サーバーが正常に動作していることを確認します。

   uv run test_mcp_client.py
   Starting MCP server test...
   ==================================================
   Testing server connection...
   [04/16/25 20:38:54] INFO     Processing request of type CallToolRequest                                                                                                                     server.py:534
   Connection test result: Successfully connected to Joern MCP, joern server version is XXX
   

4. MCP サーバーを設定します。 cline で MCP サーバーを設定します。sample_cline_mcp_settings.json を参照してください。

5. MCP サーバーを使用します。 LLM に質問します。prompts_en.md を参照してください。

開発に関する注意事項

• .env ファイルは環境変数の保存に使用します。
• .gitignore ファイルは、Git のバージョン管理で無視するファイルを定義します。
• pyproject.toml はプロジェクトの Python 設定を定義します。
• MCP ツールの開発
  • server_tools.sc に実装し、server_tools.py に定義を追加して、test_mcp_client.py にテストを追加します。

貢献ガイドライン

プロジェクトの改善に役立つ Issue や Pull Request の投稿を歓迎します。

ツールの追加も歓迎します。

参考資料

https://github.com/flankerhqd/jebmcp

https://docs.joern.io/server/

https://docs.joern.io/interpreter/

変更履歴

v1.2.0 (2026-09-10)

サーバー側のコールグラフツール（パフォーマンス）

• server_tools.sc に新しい Scala ヘルパーを追加しました：get_methods_by_name（インデックス付きの nameExact 検索。大規模な CPG でタイムアウトする、CPG 全体を対象とした .filter(_.fullName.contains(...)) のスキャンを置き換えます）、get_callee_chain（サーバー側で BFS を実行し、メソッドの完全修飾名とコードを含むコールチェーン全体を返します。JDK／フレームワークの呼び出し先はスキップし、HTTP の往復は 1 回です）、および get_callee_chain_names（コードなしで名前のみを返します）。
• これらを公開する新しい MCP ツールを追加しました：get_callee_chain_server、get_methods_by_name。
• 効果：1 つのコールチェーンの解決に必要な HTTP の往復が、約 30 回から 1 回に減ります。

HTTP クライアントの堅牢性向上（server.py）

• joern_remote は、接続プールを備えた keep-alive 対応の requests.Session を使用するようになりました。
• 一時的な障害は 3 回再試行しますが、401／403 の場合はすぐに失敗します（認証エラーは一時的な障害ではありません）。
• 失敗時に None ではなく明示的な ERROR: ... 文字列を返すため、呼び出し元は失敗と正当な空の結果を区別できます。

修正

• 認証情報キーの互換性：同梱の .env では USER_NAME／PASSWORD を使用していますが、ホスト設定では JOERN_AUTH_USERNAME／JOERN_AUTH_PASSWORD が注入されます。後者だけが読み込まれていたため、ホストから環境変数が注入されない状態で起動すると（同梱の test_mcp_client.py を含む）、401 が発生しても通知されず失敗していました。どちらの名前も受け付けるようになりました。
• FastMCP との互換性：fastmcp 2.x ではコンストラクター引数の log_level が削除されたため、try/except 内で渡し、FASTMCP_LOG_LEVEL にフォールバックするようになりました。

ドキュメントと整理

• 起動コマンドに -XX:CompressedClassSpaceSize=1g -XX:MaxMetaspaceSize=2g が追加されました（デフォルト設定では長時間使用した後にのみ問題が発生する理由については、「Joern サーバーの起動」の注記を参照してください）。
• コードコメントは英語のみとし、中国語は README_cn.md と prompts_cn.md に限定しています。
• .gitignore：ローカルの CPG アーティファクト（*.cpg）、バックアップ（*.bak-*）、およびローカルの認証情報注入用 run_verify.sh ラッパーを無視するようにしました。
• バージョンを 1.2.0 に更新しました。

v1.3.0 (2026-09-10)

• tests/fixture/：自己完結型の Android フィクスチャ（作成したソースと build_fixture.sh）を追加しました。API 36 / SDK 拡張レベル 17 向けの約 12 KB の APK と、対応する CPG をビルドします。これまでツールで問題を起こしたすべての構成を、それぞれ 1 回ずつ含んでいます。ビジネス処理のエントリーポイントが onReceive ではなく handleBroadCastReceive() である独自のベースレシーバー、クラスとインターフェースをまたぐ 4 ホップの委譲チェーン、単純名が重複するメソッド、匿名内部クラス、チェーンの末尾にある SharedPreferences への書き込み（hd_member）、チェーンツールがスキップする必要のあるフレームワーク呼び出し、および権限で保護されたレシーバーです。
• test_mcp_client.py は、このフィクスチャに対するアサーションベースのリグレッションゲートになりました。チェーン／検索ツール、従来のクエリ、エラーパスを検証し、失敗時にはゼロ以外の終了コードを返します。臨時の verify_mcp.py は統合されました。
• フィクスチャ APK は、このパッケージ（pyproject.toml）と同じバージョンを持つため、tests/fixture/fixture.apk と fixture.cpg はサーバーと一緒にバージョン管理されます。
• ドキュメントとツールのヘルプで、古い NFC のサンプルを使わず、フィクスチャを使うようになりました。
• バージョンを 1.2.0 から 1.3.0 に更新しました。

テスト

cd tests/fixture && ./build_fixture.sh --cpg   # fixture.apk + fixture.cpg
cd ../.. && uv run test_mcp_client.py          # protocol-level regression gate