sr-mcp

sr-mcp 是一个 MCP（Model Context Protocol）Server，作为 AI Agent 与 StarRocks 之间的安全代理层。它解决了 StarRocks 部署在内网、办公电脑无法直连的问题——部署在阿里云 ECS 上后，AI Agent 通过 HTTP/SSE 协议即可安全地执行只读 SQL 查询。

为什么需要它

StarRocks 部署在阿里云，只开放内网 IP，办公电脑无法直接连接。sr-mcp Server 部署在一台同时具备外网 IP 和内网可达 StarRocks 的 ECS 上，作为中间代理层，通过 MCP 协议对外暴露 SQL 执行能力，供 Cowork、Claude Code 等 AI Agent 调用。

核心原则：Server 只做 SQL 执行通道，不涉及业务逻辑。SQL 的生成由分析项目的 AI 负责。

架构

┌──────────────────────┐     HTTP/SSE       ┌─────────────────────────┐
│  Cowork / Claude     │ ◄──────────────────►│  Alibaba Cloud Machine   │
│  (办公电脑)           │   公网 + API Key    │                          │
└──────────────────────┘                     │  ┌───────────────────┐  │
                                             │  │  sr-mcp Server    │  │
                                             │  │  (Spring Boot)    │  │
                                             │  └────────┬──────────┘  │
                                             │           │ MySQL协议   │
                                             │           ▼ 内网IP      │
                                             │  ┌───────────────────┐  │
                                             │  │    StarRocks      │  │
                                             │  └───────────────────┘  │
                                             └─────────────────────────┘

MCP Tools

1. execute_sql

执行 SQL 查询并返回结构化结果。

参数	类型	必填	说明
sql	String	是	要执行的 SQL 语句
database	String	否	目标数据库名，提供后自动 USE

返回示例：

{
  "columns": ["col1", "col2"],
  "rows": [
    {"col1": "val1", "col2": 42},
    {"col1": "val2", "col2": 99}
  ],
  "row_count": 2,
  "execution_time_ms": 142
}

2. list_databases

列出 StarRocks 中所有数据库。

返回示例：

{
  "databases": ["db1", "db2", "db3"]
}

3. describe_table

获取表结构信息。

参数	类型	必填	说明
database	String	是	数据库名
table	String	是	表名

返回示例：

{
  "columns": [
    {"field": "user_id", "type": "bigint", "null": "NO", "key": "PRI", "default": null, "extra": ""},
    {"field": "name", "type": "varchar(100)", "null": "YES", "key": "", "default": null, "extra": ""}
  ]
}

安全机制

API Key 认证

• API Key 通过环境变量 SR_MCP_API_KEY 注入
• 客户端在 HTTP Header X-API-Key 中传入
• 每个请求到达时校验，不匹配返回 401

SQL 安全检查（仅针对 execute_sql）

所有传入 SQL 经过以下检查，全部通过才放行：

1. 语句类型白名单：只允许 SELECT / WITH / DESCRIBE / SHOW / EXPLAIN 开头
2. 危险关键字扫描：拒绝包含 INSERT、UPDATE、DELETE、DROP、ALTER、TRUNCATE、CREATE 等写操作关键字的 SQL
3. 强制 LIMIT：SQL 中未显式包含 LIMIT 时自动追加（默认 1000，可配置）
4. 多语句拒绝：拒绝包含 ; 的 SQL，防止恶意拼接
5. 查询超时：JDBC 层面 setQueryTimeout(30) 秒，超时自动 kill

安全配置

密码和 API Key 均通过环境变量注入，不写入 jar 包：

• SR_PASSWORD：StarRocks 密码
• SR_MCP_API_KEY：API Key

技术栈

• Java 17+
• Spring Boot 3.x
• Spring AI MCP Server（spring-ai-starter-mcp-server）
• HikariCP（连接池）
• MySQL JDBC Connector
• Maven

快速开始

前置条件

• JDK 17+
• Maven 3.8+
• 阿里云 ECS（有外网 IP，内网可达 StarRocks）

配置

# application.yml
server:
  port: 8123

auth:
  api-key: ${SR_MCP_API_KEY}

sr:
  url: jdbc:mysql://{StarRocks内网IP}:9030
  username: analyst
  password: ${SR_PASSWORD}
  pool:
    max-size: 5
    connection-timeout: 10000
  query:
    timeout-seconds: 30
    default-limit: 1000

构建与运行

# 构建 fat jar
mvn clean package -DskipTests

# 设置环境变量
export SR_PASSWORD=your_starrocks_password
export SR_MCP_API_KEY=your_api_key

# 启动
java -jar target/sr-mcp.jar

MCP 客户端配置

在 Cowork 或 Claude Code 的 MCP 配置中添加：

{
  "mcpServers": {
    "starrocks": {
      "type": "sse",
      "url": "http://{ECS外网IP}:8123/sse",
      "headers": {
        "X-API-Key": "your_api_key"
      }
    }
  }
}

项目结构

sr-mcp/
├── docs/
│   └── design/                       # 设计文档
│       └── sr_mcp_server_design.md
├── src/main/java/com/mamba/sr/
│   ├── mcp/                          # MCP 协议层：HTTP/SSE 传输，tool 注册与路由
│   ├── security/                     # 安全层：API Key 认证 + SQL 安全检查
│   ├── executor/                     # 执行层：HikariCP 连接池，SQL 执行，ResultSet→JSON
│   ├── metadata/                     # 元数据查询：SHOW DATABASES / DESCRIBE TABLE
│   └── config/                       # 配置绑定
├── src/main/resources/
│   └── application.yml
└── pom.xml

错误处理

场景	返回
SQL 安全校验不通过	error: "SQL rejected: {reason}"
查询超时	error: "Query timeout after {N}s"
StarRocks 不可达	error: "StarRocks unavailable: {reason}"
StarRocks SQL 语法错误	error: "SQL error: {original message}"

所有错误通过 MCP tool 返回通道正常返回，不抛 HTTP 500，以便 AI 能读取错误信息并修正 SQL。