Spring AI 1.1.0下MCP资源无法暴露问题求助

问题背景 #

已通过如下配置为MCP客户端提供工具及HTML资源，工具可正常暴露，但HTML资源无法生效：

Java配置代码 #

@Bean
public ToolCallbackProvider toolCallbacks(ProductService tools) {
    return MethodToolCallbackProvider.builder().toolObjects(tools).build();
}

@Bean
public McpServerFeatures.SyncResourceSpecification productsCarouselResource() {

    var resource = McpSchema.Resource.builder()
        .name("products-carousel")
        .uri("ui://widget/products-carousel.html")
        .description("Product carousel UI for search results")
        .build();

    return new McpServerFeatures.SyncResourceSpecification(resource, (exchange, request) -> {
        try {
            log.info("Reading UI resource: {}", request.uri());
            String html = read("ui/products_carousel/index.html")
                .replace("/*__INLINE_CSS__*/", read("ui/products_carousel/style.css"))
                .replace("//__INLINE_JS__", read("ui/products_carousel/app.js"));

            return new McpSchema.ReadResourceResult(List.of(
                new McpSchema.TextResourceContents(
                    request.uri(),
                    "text/html+skybridge",
                    html
                )
            ));
        } catch (Exception e) {
            String fallback = "<!doctype html><meta charset='utf-8'><pre>UI load error: "
                + escape(e.getMessage()) + "</pre>";
            return new McpSchema.ReadResourceResult(List.of(
                new McpSchema.TextResourceContents(request.uri(), "text/html+skybridge", fallback)
            ));
        }
    });
}

@Bean
public List<McpServerFeatures.SyncResourceSpecification> mcpResources(
    McpServerFeatures.SyncResourceSpecification productsCarouselResource) {
    return List.of(productsCarouselResource);
}

application.yml配置 #

spring:
  ai:
    mcp:
      server:
        name: one_mcp
        version: 1.0.0
        type: SYNC
        protocol: STATELESS
        capabilities:
          tool: true
          resource: true
          prompt: false
          completion: false
        streamable-http:
          mcp-endpoint: /mcp

可能遗漏的配置与排查方向 #

1. 资源读取路径错误 #

read("ui/products_carousel/index.html")的路径可能未正确指向classpath下的资源文件：

• 确认HTML/CSS/JS文件是否放在src/main/resources/ui/products_carousel/目录下
• 替换自定义read方法，改用Spring标准的资源加载方式确保路径正确：

  @Autowired
  private ResourceLoader resourceLoader;
  
  // 读取资源的代码替换为：
  String readResource(String path) throws IOException {
      Resource resource = resourceLoader.getResource("classpath:" + path);
      return new String(resource.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
  }
  

2. MCP资源未被正确注册 #

• 检查MCP元数据端点（如/mcp/metadata），确认products-carousel资源是否出现在资源列表中
• 若使用Spring AI 0.8.x及以上版本，确保已添加@EnableMcpServer注解到配置类上

3. 资源URI协议不被客户端识别 #

• ui://widget/products-carousel.html中的ui://协议可能未被客户端支持，尝试改为标准的http://或客户端预期的协议格式，或者在MCP服务器配置中添加协议映射

4. 响应媒体类型不兼容 #

• text/html+skybridge是自定义媒体类型，客户端可能无法解析，尝试改为标准的text/html类型测试：

  new McpSchema.TextResourceContents(
      request.uri(),
      "text/html",
      html
  )
  

5. 请求未到达资源处理逻辑 #

• 查看应用日志是否输出Reading UI resource: ...：
  • 无日志：说明资源请求未路由到处理方法，检查MCP端点配置是否正确，或客户端请求的URI与配置的ui://widget/products-carousel.html是否完全匹配
  • 有日志但报错：根据异常信息排查资源读取或替换逻辑的问题

内容的提问来源于stack exchange，提问作者Monta