# mcp-server

**Repository Path**: wangjinbo/mcp-server

## Basic Information

- **Project Name**: mcp-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mcp-adapter

OPM AI MCP Adapter — 基于 Model Context Protocol (MCP) 的 IT 运维智能适配服务。

将 OPM 运维平台的**组织**等能力以 MCP Tools 的形式暴露，供大语言模型（LLM）通过 MCP 协议直接调用，实现 AI 驱动的智能运维。

## 技术栈

| 组件 | 版本 |
|---|---|
| Java | 21 |
| Spring Boot | 4.0.8 |
| Spring AI (MCP) | 2.0.1 |
| Spring Security (WebFlux) | 4.0.8 |
| Project Reactor | — |
| Lombok | — |
| 运行时 | Netty (WebFlux) |
| 传输协议 | Streamable-HTTP / SSE |

## 模块结构

```
mcp-server
├── pom.xml               # 聚合根 POM（mcp-adapter）
├── mcp-common            # 通用模块：认证、安全、HTTP 客户端
│   └── com.cnbmtech.opm.ai.mcp
│       ├── client        # AuthApiClient、DownstreamApiClient、WebClientConfig、DownstreamProperties
│       └── security      # BearerTokenWebFilter、AuthService、RequestTokenContext、SecurityConfig、RSAUtil、AuthProperties
└── mcp-tool              # 工具业务模块（可独立启动的 MCP Server）
    └── com.cnbmtech.opm.ai.mcp
        ├── OpmMcpAdapterApplication   # 启动类
        ├── config/McpToolCallbackConfig
        └── tool/OrgTool
```

## 架构设计

```
┌──────────────┐      MCP (Streamable-HTTP)      ┌──────────────────────────┐
│   LLM Client │ ◄─────────────────────────────► │        mcp-adapter       │
│  (Claude等)  │                                  │                          │
└──────────────┘                                  │  ┌────────────────────┐  │
                                                  │  │   MCP Server       │  │
                                                  │  │   (Spring AI)      │  │
                                                  │  └────────┬───────────┘  │
                                                  │           │              │
                                                  │  ┌────────▼───────────┐  │
                                                  │  │   @Tool Methods    │  │
                                                  │  │   (OrgTool)        │  │
                                                  │  └────────┬───────────┘  │
                                                  │           │              │
                                                  │  ┌────────▼───────────┐  │
                                                  │  │  Bearer Token      │  │
                                                  │  │  Pass-through      │  │
                                                  │  └────────┬───────────┘  │
                                                  └───────────┼──────────────┘
                                                              │
                                                      ┌───────▼───────┐
                                                      │  opm-monitor  │
                                                      │  REST API     │
                                                      │  (下游系统)    │
                                                      └───────────────┘
```

### 关键设计决策

- **Bearer Token 透传**：适配器不验证 Token 有效性，仅捕获 MCP 客户端请求中的 `Authorization` 头并原样转发至下游 OPM 系统
- **选择性认证**：`BearerTokenWebFilter` 仅对 `tools/call` JSON-RPC 方法强制要求 Token，`initialize`、`tools/list` 等请求无需认证
- **Reactor 上下文传播**：通过 Micrometer `ContextRegistry` + `Hooks.enableAutomaticContextPropagation()` 将 Token 从 Netty 事件循环线程桥接到 MCP 工具执行的 `boundedElastic` 线程
- **工具注册**：Spring AI 2.x 不再自动扫描 `@Tool` 注解方法，需在 `McpToolCallbackConfig` 中显式通过 `MethodToolCallbackProvider` 注册

## MCP 能力总览

### Tools（共 4 个）

| 分类 | 类名 | 数量 | 说明 |
|---|---|---|---|
| **组织信息** | `OrgTool` | 4 | 组织查询、orgCodeList 获取（筛选/全量）、组织及其所有下游组织 |

| 方法 | 说明 |
|---|---|
| `queryOrgs` | 查询组织基本信息列表，支持 `orgName` / `orgShortName` 模糊查询及 `isEnable` 筛选、分页 |
| `getOrgCodeList` | 根据条件获取组织 `orgCode` 编码列表 |
| `getAllOrgCodeList` | 查询全部组织的 `orgCode` 编码列表 |
| `getOrgAndSubOrgCodeList` | 获取当前组织及其所有下游组织的 `orgCode` 列表（基于 `pid` 递归收集子孙组织） |

## 快速开始

### 环境要求

- Java 21+
- Maven 3.9+
- 下游 OPM 监控服务（通过 `opm.downstream.base-url` 配置）

### 构建

```bash
mvn clean package -DskipTests
```

### 运行

```bash
java -jar mcp-tool/target/mcp-tool-1.0.0.jar
```

服务默认启动在 **18091** 端口。

### Docker

```bash
docker build -t mcp-adapter .
docker run -p 18091:18091 mcp-adapter
```

> 注意：`Dockerfile` 中 `EXPOSE 8082`，与 `application.yml` 中的 `server.port=18091` 不一致，部署时需统一。

## 配置说明

配置文件：`mcp-tool/src/main/resources/application.yml`

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `server.port` | 18091 | 服务端口 |
| `spring.application.name` | opm-mcp-adapter | 应用名 |
| `spring.ai.mcp.server.name` | opm-mcp-server | MCP Server 名称 |
| `spring.ai.mcp.server.protocol` | STREAMABLE | 传输协议（STREAMABLE / SSE） |
| `spring.ai.mcp.server.type` | SYNC | 同步/异步模式 |
| `opm.downstream.base-url` | — | 下游 OPM 系统地址 |
| `opm.downstream.auth-header-name` | Authorization | 透传 Token 时的请求头名 |
| `opm.downstream.auth-scheme` | Bearer | 认证 Scheme |
| `opm.downstream.insecure` | true | 是否跳过 SSL 校验 |
| `opm.auth.base-url` | — | 认证网关地址（账号 token 获取） |
| `opm.auth.token-endpoint` | /sys/AuthToken/getTokenByEnc | Token 获取接口 |
| `opm.auth.encrypt-key` | Encrypt | 加密 Key |
| `opm.auth.salt` | cnbm | 盐值 |

### 日志级别

```yaml
logging:
  com.cnbmtech.opm.ai.mcp: INFO
  org.springframework.ai.mcp: INFO
  io.modelcontextprotocol: TRACE
```

## 依赖清单

| 依赖 | 用途 |
|---|---|
| `spring-boot-starter-webflux` | 响应式 Web 运行时（Netty） |
| `spring-ai-starter-mcp-server-webflux` | MCP Server（Streamable-HTTP / SSE 传输） |
| `spring-boot-starter-security` | Bearer Token 认证 & 安全过滤 |
| `jackson-databind` | JSON 序列化（工具参数解析） |
| `lombok` | 减少样板代码（可选） |
| `spring-boot-configuration-processor` | IDE 配置元数据支持（可选） |
| `junit-jupiter-api` + `junit-jupiter-engine` | 单元测试 |

BOM 管理：`spring-boot-dependencies:4.0.8`、`spring-ai-bom:2.0.1`

## 注意事项

- 所有 MCP Tools 均调用下游 OPM 监控接口（`opm-monitor`），不包含本地模拟数据
- 携带 `orgCodeList` 入参的工具在入参为空时会自动回退为该请求全部组织编码（`OrgTool.getAllOrgCodeList()`），保证下游查询始终带组织范围
- 下游 `opm.downstream.insecure=true` 跳过了 SSL 校验，生产环境建议关闭并配置有效证书
- 可通过 `application-dev.yml` 启用开发级日志（`spring.profiles.active=dev`）