关键词

Spring AIMCPModel Context Protocol元素周期表文件系统地图服务工具调用LLM应用

使用说明

项目简介

本示例项目 'hello-spring-ai' 演示了如何使用 Spring AI 框架构建 MCP (Model Context Protocol) 服务器。该项目包含 MCP 服务器端 ('mcp-server') 和客户端 ('mcp-client')，展示了如何通过 MCP 协议提供和消费工具服务。

主要功能点

  • 元素周期表查询服务 (Hello Mcp Server): 提供元素周期表数据查询，可以通过元素名称或原子序数查询元素详细信息。
  • 文件系统访问服务 (Filesystem Mcp Server): 允许 LLM 客户端读取服务器端文件系统上的文件内容。
  • 地图路线规划服务 (Amap Mcp Server): 集成高德地图 API，提供驾车路线规划服务，并能将结果保存到服务器端文件系统中。

安装步骤

  1. 克隆仓库: 
    git clone https://github.com/feuyeux/hello-spring-ai
cd hello-spring-ai
  2. 创建 '.env' 文件: 在项目根目录下创建 '.env' 文件。 
    touch .env
  3. 配置 '.env' 文件: 编辑 '.env' 文件，填入以下 API 密钥。请自行申请智谱 AI 和高德地图的 API Key。 
    ZHIPUAI_API_KEY=你的智谱大模型APIKEY
AMAP_MAPS_API_KEY=你的高德地图APIKEY

服务器配置

本示例包含三种 MCP 服务器，客户端需要根据需要配置连接信息。以下是针对每种服务器的配置信息，以 JSON 格式展示，用于 MCP 客户端配置 (例如 'McpClient.sync()' 方法的参数配置)。

1. Hello Mcp Server 配置 (元素周期表查询服务)

此服务器基于 SSE 协议提供服务，无需额外启动命令，客户端直接连接即可。

{
  "serverName": "hello-mcp-server",
  "transport": "sse",
  "baseUrl": "http://localhost:8061"
}

参数注释:

  • 'serverName': 服务器名称，用于标识服务器类型 (仅供参考)。
  • 'transport': 传输协议，这里使用 'sse' (Server-Sent Events)。
  • 'baseUrl': 服务器基础 URL，客户端通过此 URL 与服务器建立 SSE 连接。请注意，此服务器端代码 ('mcp-server') 默认监听 8061 端口，无需额外配置启动命令。

2. Filesystem Mcp Server 配置 (文件系统访问服务)

此服务器基于 Stdio 协议提供服务，需要配置启动命令和参数。

{
  "serverName": "filesystem-mcp-server",
  "transport": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "your_user_directory"
  ]
}

参数注释:

  • 'serverName': 服务器名称，用于标识服务器类型 (仅供参考)。
  • 'transport': 传输协议，这里使用 'stdio' (标准输入输出)。
  • 'command': 启动服务器的命令，这里使用 'npx' (Node Package Execute)，用于执行 npm 包。
  • 'args': 传递给 'npx' 命令的参数列表。
    • '-y': 'npx' 参数，表示自动同意安装依赖包。
    • '@modelcontextprotocol/server-filesystem': 要执行的 npm 包，即文件系统 MCP 服务器。
    • '"your_user_directory"': 文件系统 MCP 服务器的根目录参数，请将 '"your_user_directory"' 替换为实际的用户目录路径，例如 Windows 下的 '"D:\ai\hello-spring-ai\mcp-client"' 或 Linux/macOS 下的 '"/home/user/hello-spring-ai/mcp-client"'。注意路径分隔符，Windows 使用 '\'，其他系统使用 '/'。

3. Amap Mcp Server 配置 (地图路线规划服务)

此服务器基于 Stdio 协议提供服务，同样需要配置启动命令和参数，并需设置高德地图 API Key 环境变量。

{
  "serverName": "amap-mcp-server",
  "transport": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@amap/amap-maps-mcp-server"
  ],
  "env": {
    "AMAP_MAPS_API_KEY": "YOUR_AMAP_MAPS_API_KEY"
  }
}

参数注释:

  • 'serverName': 服务器名称，用于标识服务器类型 (仅供参考)。
  • 'transport': 传输协议，这里使用 'stdio' (标准输入输出)。
  • 'command': 启动服务器的命令，同样使用 'npx'。
  • 'args': 传递给 'npx' 命令的参数列表。
    • '-y': 'npx' 参数，自动同意安装依赖包。
    • '@amap/amap-maps-mcp-server': 要执行的 npm 包，即高德地图 MCP 服务器。
  • 'env': 环境变量配置。
    • 'AMAP_MAPS_API_KEY': 高德地图 API Key，请将 '"YOUR_AMAP_MAPS_API_KEY"' 替换为你在高德地图开发者平台申请的 API Key。 请注意，虽然这里也提供配置，但示例代码中客户端是从 '.env' 文件读取 API Key，建议保持一致，在 '.env' 文件中配置 'AMAP_MAPS_API_KEY'。

基本使用方法

  1. 启动 MCP 服务器:

    • Hello Mcp Server: 无需手动启动，'mcp-client' 会自动连接到 'mcp-server' 提供的 SSE 服务 (端口 8061)。
    • Filesystem Mcp Server & Amap Mcp Server: 客户端在运行时会自动通过 'npx' 命令启动 Stdio 服务器。 请确保你的系统已安装 Node.js 和 npm (或 npx)。

  2. 运行 MCP 客户端测试: 打开终端，进入 'mcp-client' 目录。

    cd mcp-client

    使用 Maven 命令运行不同的测试用例，测试不同的 MCP 功能。

    • 测试 Hello Mcp (元素周期表查询): 
      mvn test "-Dtest=org.feuyeux.ai.hello.McpTests#testHelloMcp"
    • 测试 Filesystem Mcp (文件系统访问): 
      mvn test "-Dtest=org.feuyeux.ai.hello.McpTests#testFSMcp"
    • 测试 Amap Mcp (地图路线规划) + Filesystem Mcp (结果保存): 
      mvn test "-Dtest=org.feuyeux.ai.hello.McpTests#testMapMcp"

    查看控制台输出和 'mcp-client' 目录下的生成的文件 (例如 'amap.md')，验证 MCP 功能是否正常工作。

注意:

  • 运行 'Filesystem Mcp Server' 和 'Amap Mcp Server' 需要确保你的环境中安装了 Node.js 和 npm (或 npx)。
  • 高德地图 API Key 和 智谱 AI API Key 需要提前申请并在 '.env' 文件中正确配置。
  • 文件系统访问服务默认根目录为启动命令中指定的目录 (示例中为 'mcp-client' 目录)，请根据实际需要修改。

信息

分类

AI与计算

访问项目