Spring AI AgentがMCPを通じてローカルファイルデータを統合

> 本記事は[こちらのブログ](https://www.alibabacloud.com/blog/spring-ai-agent-integrates-local-file-data-through-mcp_602135?spm=a2c65.11461433.0.0.4ee35355DE9DWe)を参考にしています。
> 翻訳にはアリババクラウドの[ModelStudio](https://www.alibabacloud.com/en/product/modelstudio)([Qwen](https://www.alibabacloud.com/en/solutions/generative-ai/qwen))を使用しております。

# Model Context Protocol (MCP) と Spring AI MCP の紹介

**著者: Jun Liu**

## Model Context Protocol (MCP) の紹介

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) は、アプリケーションが大規模言語モデル（LLMs）にコンテキストを提供する方法を規定するオープンプロトコルです。MCPは、AIモデルをさまざまなデータソースやツールに接続するための統一された方法を提供し、統合の標準化されたアプローチを定義します。エージェントを開発する際には、データやツールとの統合が必要になることがよくありますが、MCPはこの統合を標準化することで、LLM上にエージェントや複雑なワークフローを構築する助けとなります。現在、多くのサービスが統合され、[MCPサーバーの実装](https://github.com/modelcontextprotocol/servers)が提供されています。このエコシステムは非常に急速に成長しています。

## Spring AI MCP の紹介

Spring AI MCP は、MCPに対するJavaおよびSpringフレームワークの統合を提供します。これにより、Spring AI アプリケーションは標準化されたインターフェースを通じて異なるデータソースやツールと対話できるようになり、同期および非同期の通信パターンの両方をサポートします。

![1](https://yqintl.alicdn.com/babc1b3dfcecafaf24d99adc958ac31b58d41e16.png)

Spring AI MCP はモジュール式のアーキテクチャを使用しており、以下のコンポーネントが含まれています：

- **Spring AI アプリケーション**: Spring AI フレームワークを使用して、MCP経由でデータにアクセスしたい生成AIアプリケーションを構築します。
- **Spring MCP クライアント**: MCPのSpring AI 実装で、サーバーと1:1の接続を維持します。
- **MCP サーバー**: 標準化されたMCPを通じて特定の機能を公開する軽量プログラムです。
- **ローカルデータソース**: MCPサーバーが安全にアクセスできるコンピュータファイル、データベース、サービスです。
- **リモートサービス**: MCPサーバーがインターネット経由で接続できる外部システム（APIなどを通じて）です。

## サンプルを使って Spring AI MCP を素早く体験

ここでは、MCPを介してローカルファイルシステムを照会または更新し、ファイルシステム内のデータをコンテキストとして使用してモデルと対話できるエージェントアプリケーションの例を示します。この例は、MCPを使用してSpring AIをローカルファイルシステムと統合する方法を示しています。

サンプルの完全なソースコード：[https://github.com/springaialibaba/spring-ai-alibaba-examples/spring-ai-alibaba-mcp-example](https://github.com/springaialibaba/spring-ai-alibaba-examples/spring-ai-alibaba-mcp-example)

### サンプルアーキテクチャ（ソースコードの説明）

前のセクションでは、Spring AIとMCPを統合するためのインフラストラクチャについて説明しました。次の例では、以下の主要なコンポーネントを使用します：

- **MCPクライアント**: MCPと統合する鍵となるコンポーネントで、ローカルファイルシステムと対話できます。
- **関数コールバック**: Spring AI MCPの関数呼び出し宣言方法です。
- **チャットクライアント**: Spring AIの重要なコンポーネントで、LLMモデルとの対話やエージェントプロキシに使用されます。

### ChatClient の宣言java
// List<McpFunctionCallback> functionCallbacks;
var chatClient = chatClientBuilder.defaultFunctions(functionCallbacks).build();

これまでのSpring AIアプリケーションと同様に、まずChatClient Beanを定義します。これは、LLMと対話するためのプロキシとして機能します。ここで注入した関数は、MCPコンポーネント（McpFunctionCallback）によって作成されていることに注意してください。次に、McpFunctionCallbackがどのように使用されるかを見てみましょう。

### MCP 関数コールバックの宣言

次のコードスニペットは、mcpClientを介してMCPサーバーと対話し、McpFunctionCallbackを通じてMCPツールを標準的なSpring AI関数に適合させます。MCPサーバーで利用可能なツールのリスト（Spring AIでは関数と呼ばれます）を検出します。各ツールを順番にSpring AI関数コールバックに変換し、最終的にこれらのMcpFunctionCallbacksをChatClientに登録して使用します。java
@Bean
public List<McpFunctionCallback> functionCallbacks(McpSyncClient mcpClient) {
    return mcpClient.listTools(null)
            .tools()
            .stream()
            .map(tool -> new McpFunctionCallback(mcpClient, tool))
            .toList();
}

ChatClientとモデル間の対話は変わらないことがわかります。モデルは必要に応じてChatClientに関数呼び出しを行うように指示します。ただし、Spring AIは実際の関数呼び出しプロセスをMcpFunctionCallbackを介してMCPに委任し、標準化されたMCPプロトコルを通じてローカルファイルシステムと対話します：

- 大規模モデルとの対話中に、ChatClientは関連する関数呼び出し要求を処理します。
- ChatClientはMCPツールを呼び出します（McpClientを介して）。
- McpClientはMCPサーバー（つまり、ファイルシステム）と対話します。

### McpClient の初期化

このエージェントアプリケーションは、ローカルで実行されているファイルシステムMCPサーバーと通信するために同期MCPクライアントを使用します。java
@Bean(destroyMethod = "close")
public McpSyncClient mcpClient() {
    var stdioParams = ServerParameters.builder(npx)
            .args("-y", "@modelcontextprotocol/server-filesystem", "path"))
            .build(); // 1

    var mcpClient = McpClient.sync(new StdioServerTransport(stdioParams),
            Duration.ofSeconds(10), new ObjectMapper()); //2

    var init = mcpClient.initialize(); // 3
    System.out.println("MCP Initialized: " + init);

    return mcpClient;
}

上記のコードでは：

- MCPサーバーの起動コマンドとパラメーターを設定します。
- McpClientを初期化します。これはMCPサーバーに接続し、タイムアウトなどを指定します。
- Spring AIは `npx -y @modelcontextprotocol/server-filesystem /path/to/file` を使用してローカルマシン上にスタンドアロンのサブプロセスを作成します（ローカルMCPサーバーを表します）。Spring AIはMcpClientと通信し、それがMCPサーバーへの接続を通じてローカルファイルシステムと対話します。

### 前提条件

1. **npx（Node Package eXecute）のインストール**  
   まず、ローカルマシンに[npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)がインストールされていることを確認し、次のコマンドを実行します：
   bash
   npm install -g npx
   

2. **サンプルソースコードのダウンロード**  
   bash
   git clone https://github.com/springaialibaba/spring-ai-alibaba-examples.git
   cd spring-ai-alibaba-examples/spring-ai-alibaba-mcp-example/filesystem
   

3. **環境変数の設定**  
   bash
   # Tongyi LLMのDashscope API-KEYを設定
   export AI_DASHSCOPE_API_KEY=${your-api-key-here}
   

4. **サンプルのビルド**  
   bash
   ./mvnw clean install
   

### サンプルアプリケーションの実行

サンプルを実行すると、エージェントがモデルに対してクエリを開始します（ソースコードには事前に定義された質問が含まれており、ソースファイルで確認できます）。出力結果はコンソールで確認できます。bash
./mvnw spring-boot:run

IDEでサンプルを実行している場合、ファイルシステムMCPサーバーからファイルアクセス権限の問題