服务注册与分布式协调 / 系统课时

用 Java 框架自动注册 MCP

用 Java 框架自动注册 MCP

这一篇把一个最小 Java MCP Server 接到 Nacos:定义一个工具、启用 Spring AI Alibaba 的 Nacos 注册能力、启动应用,再通过管理 API 验证服务目录中已经出现对应条目。完成后,新实例启动即可走同一条标准注册路径。

学习目标

  • 配置 Spring AI Alibaba 与 Spring AI MCP Server 的最小依赖。
  • 将 Java 方法暴露为 MCP Tool,并在应用启动时自动注册到 Nacos。
  • 用目录 API 验证服务名称、版本和注册结果是否已经进入 Nacos。

准备兼容的工程依赖

Nacos 当前自动注册手册使用 spring-ai-alibaba-starter-mcp-registry 配合 Spring AI 的 MCP Server starter,并通过 spring.ai.alibaba.mcp.nacos.register.enabled 开启注册。([Nacos 官网][2]) 本示例固定在 Spring AI Alibaba 1.1.2.2、Spring AI 1.1.2 与 Spring Boot 3.5.8 这一组对齐版本;Spring AI Alibaba 1.1.2.x 的发布与主仓库都将 Spring AI 基线对齐到 1.1.2。([GitHub][3])

pom.xml 使用完整的可启动配置:

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.8</version>
    <relativePath/>
  </parent>

  <groupId>dev.anystack</groupId>
  <artifactId>nacos-mcp-server</artifactId>
  <version>0.0.1-SNAPSHOT</version>

  <properties>
    <java.version>17</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>com.alibaba.cloud.ai</groupId>
      <artifactId>spring-ai-alibaba-starter-mcp-registry</artifactId>
      <version>1.1.2.2</version>
    </dependency>
    <dependency>
      <groupId>org.springframework.ai</groupId>
      <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
      <version>1.1.2</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

这是工程配置,不单独产生控制台输出。验证方法是执行后文的 mvn spring-boot:run;若依赖解析失败,先用 mvn dependency:tree 检查是否被父工程覆盖了上述版本。

定义工具并交给 MCP Server

创建 src/main/java/dev/anystack/mcp/Application.java。@Tool 决定要暴露的方法,MethodToolCallbackProvider 则把这个对象交给 Spring AI MCP Server。

java
package dev.anystack.mcp;

import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Service;

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Bean
    ToolCallbackProvider weatherTools(WeatherService weatherService) {
        // 将业务对象的方法元数据交给 MCP Server 暴露。
        return MethodToolCallbackProvider.builder()
                .toolObjects(weatherService)
                .build();
    }

    @Service
    static class WeatherService {

        @Tool(description = "Get weather information by city name")
        public String getWeather(@ToolParam(description = "City name") String cityName) {
            return "Sunny in " + cityName;
        }
    }
}

这段代码依赖后面的 Nacos 与 MCP Server 配置才会形成完整注册流程;单独编译只会得到一个带 Tool 元数据的 Spring Boot 应用。

配置启动即注册

创建 src/main/resources/application.yml。服务名与版本会成为目录中识别 MCP Server 的关键字段,Nacos 地址和凭据用环境变量覆盖,避免把环境信息写死在代码仓库。

yaml
server:
  port: 8080

spring:
  application:
    name: mcp-nacos-registry-example
  ai:
    mcp:
      server:
        name: weather-mcp
        version: 1.0.0
        type: SYNC
        instructions: "Provides a weather lookup tool"
    alibaba:
      mcp:
        nacos:
          server-addr: ${NACOS_ADDR:127.0.0.1:8848}
          namespace: ${NACOS_NAMESPACE:public}
          username: ${NACOS_USERNAME:}
          password: ${NACOS_PASSWORD:}
          register:
            enabled: true

Nacos 的自动注册机制会在 MCP Server 启动后把服务信息纳入统一 MCP 管理,并同步到相关注册与配置能力中。([Nacos 官网][2])

Spring AI Alibaba MCP 自动注册到 Nacos 的数据流

启动并验证注册结果

先确认 Nacos 可访问,再在项目根目录启动应用。若部署开启鉴权,同时设置具有目标 namespace 权限的用户名和密码。

bash
export NACOS_ADDR="127.0.0.1:8848"
export NACOS_NAMESPACE="public"

mvn spring-boot:run

预期输出:应用完成启动并持续运行;启动耗时、线程名等动态值会不同。若这里出现 Nacos 连接或 MCP 注册异常,应先解决地址、权限或依赖版本问题,不要继续做目录验证。

text
... Started Application in <TIME> seconds ...

随后用管理 API 精确查询刚注册的服务:

bash
curl -sS -G \
  -w '\nHTTP_STATUS:%{http_code}\n' \
  "http://$NACOS_ADDR/nacos/v3/admin/ai/mcp/list" \
  --data-urlencode "pageNo=1" \
  --data-urlencode "pageSize=20" \
  --data-urlencode "namespaceId=$NACOS_NAMESPACE" \
  --data-urlencode "mcpName=weather-mcp" \
  --data-urlencode "search=accurate"

预期结果:HTTP 状态为 200,code 为 0,并且 pageItems 中存在名称为 weather-mcp、最新版本为 1.0.0 的条目;ID 和协议由实际运行时生成或推导。

text
{"code":0,"message":"success","data":{"totalCount":1,"pageNumber":1,"pagesAvailable":1,"pageItems":[{"id":"<ID>","name":"weather-mcp","protocol":"<PROTOCOL>","latestPublishedVersion":"1.0.0"}]}}
HTTP_STATUS:200

如果列表中没有条目,按“应用是否真正启动 → register.enabled 是否为 true → Nacos 地址与 namespace 是否一致 → 当前身份是否有权限”的顺序定位。若服务名已存在但启动时报兼容错误,还要检查该名称和版本下已有的协议、服务引用与 Tool 结构是否和当前实例一致;Nacos 会对这些关键信息做兼容性校验。([Nacos 官网][2])

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Java 框架自动注册 MCP

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通