#MCP 服务端开发

MCP（Model Context Protocol）是一种标准化协议，用于连接 AI 模型与外部工具和数据源。通过 MCP，你可以将现有的业务接口暴露给 AI，让 AI 能够理解并调用这些接口来完成用户的自然语言请求。

flowchart LR
    A[用户提问] --> B[PIG AI]
    B --> C[MCP SSE协议]
    C --> D[已有业务controller接口]

本教程将介绍：

• 如何将现有的业务接口包装成 MCP 服务
• 如何配置让 AI 能够调用你的接口
• 如何通过自然语言让 AI 帮你查询业务数据

我们以行政区域查询为例，演示完整流程。

#实际案例：让 AI 查询行政区域

#现状分析

当前 PIGX 系统已经有一个行政区域管理模块，有对应的后台接口：

#目标效果

让用户可以直接对 AI 说：

• "帮我查一下北京市有哪些区"
• "广东省下面有多少个地级市？"
• "查询一下上海市浦东新区的行政代码"

AI 就能自动调用我们的接口，返回准确的数据：

#实现步骤

#第一步：添加 MCP 依赖

在 pigx-upms-biz 项目的 pom.xml 文件中添加依赖：

<dependency>
  <groupId>com.pig4cloud</groupId>
  <artifactId>pigx-common-mcp</artifactId>
</dependency>

#第二步：添加 @Tool 注解

找到需要暴露给 AI 的接口方法，添加 @Tool 注解：

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

@RestController
@RequestMapping("/area")
public class SysAreaController {

    @GetMapping("/page")
    @Tool(description = "查询行政区划分页数据，支持按名称、编码、父级ID等条件筛选")
    public R getSysAreaPage(
            @ParameterObject Page page,
            @ToolParam(description = "查询条件：name-区域名称，code-区域编码，parentId-父级ID")
            @ParameterObject SysAreaEntity sysArea) {
        return R.ok(sysAreaService.page(page, Wrappers.query(sysArea)));
    }
}

#第三步：配置 MCP 服务

在 PIG AI 的 MCP 模块中，添加 MCP 服务配置：

#配置端点暴露

在微服务对应的 Nacos 配置文件中增加以下配置：

security:
  oauth2:
    client:
      ignore-urls:
        - /actuator/**
        - /v2/api-docs
        - /mcp/*   # 暴露 MCP 相关端点

#微服务版本额外配置

如果是微服务版本，还需要配置路由前缀：

spring:
  ai:
    mcp:
      server:
        base-url: /admin   # 对应网关路由前缀

#验证测试

配置完成后，可以通过以下方式验证：

• "帮我查一下北京市有哪些区县"
• "广东省下面有多少个地级市？"
• "查询上海市浦东新区的行政代码"
• "显示所有直辖市的行政区划"

AI 会自动理解需求，调用对应的接口，并以友好的方式展示结果。

#扩展应用

掌握了这个方法，你可以将任何业务接口都包装成 MCP 服务：

#最佳实践

#@Tool 注解使用建议

• 描述要具体：说明接口的功能、参数含义、返回内容
• 参数要标注：使用 @ToolParam 描述每个参数的作用
• 避免歧义：不同接口的描述应有明显区分

#安全注意事项