ApiHug MCP

ApiHug 的 MCP 支持，本质上是一个面向企业场景的适配层：让已有服务可以通过 Model Context Protocol 对外暴露，同时继续沿用原有认证、鉴权和服务边界。

它是什么

ApiHug 在常规应用栈之上补了一层 MCP 集成能力：

• 可插入认证与会话控制的传输层
• 把既有后端服务映射成 MCP 暴露面的适配层
• 精细到 service 与 method 的过滤控制
• 与 Spring AI MCP server 的集成

为什么重要

裸 MCP 很有价值，但企业系统通常还需要更多东西：

• 要和现有访问控制体系对齐
• 不能为了暴露 MCP 就重写服务架构
• 必须精确控制哪些 API 真正对 MCP 开放

它如何融入整体流程

对于老项目，通常需要在三个位置启用 MCP。

1. 更新版本目录

在 libs.versions.toml 中补充或更新这些依赖定义：

• apihug-spring-ai-mcp = { group = "com.apihug", name = "it-common-spring-ai-mcp" }
• spring-ai-bom = { group = "org.springframework.ai", name = "spring-ai-bom", version.ref = "springAiVersion" }
• spring-ai-starter-mcp-server = { group = "org.springframework.ai", name = "spring-ai-starter-mcp-server" }

2. 在应用模块启用 MCP

在 hopeStub 中打开 MCP，并加入运行时依赖：

hopeStub {
  enableMcp = true
}

dependencies {
  implementation(libs.apihug.spring.ai.mcp)
  implementation platform(libs.spring.ai.bom)
  implementation(libs.spring.ai.starter.mcp.server)
}

3. 定义服务暴露范围

扩展 hope.common.service.contract.ContractAdapter，明确三件事：

• moduleClassName：运行时 proto 模块类
• mcp：哪些 service 与 method 对 MCP 暴露
• contract：依赖了哪些第三方模块契约

示例 DSL：

return myModule.service()
    .apiContext()
    .orderService(
        svc -> {
          svc.keepAll();
          svc.startsWith("add");
          svc.methods(
              methods -> {
                methods.PlaceOrder();
                methods._DeleteOrder();
              });
        })
    .build();

4. 配置 Spring AI MCP Server

spring:
  ai:
    mcp:
      server:
        enabled: true
        sse-endpoint: /api/mcp/sse
        sse-message-endpoint: /api/mcp/message
        name: okai-app-mcp-server
        stdio: false
hope:
  ai:
    mcp:
      enabled: true
      auth-key: token

这样会暴露两个主要路由：

1. GET /api/mcp/sse
2. POST /api/mcp/message

新模板可以把这些配置直接带出来；老项目则按上面的迁移步骤处理。

下一步

1. 如果还需要了解其他运行时工具，继续看 工具链
2. 调整传输层细节前，建议先读 Spring AI 官方 MCP server 文档