# 克隆项目
git clone https://github.com/your-username/oceanbase-oracle-mcp.git
cd oceanbase-oracle-mcp

# 全局安装（推荐，安装后 oceanbase-oracle-mcp 命令全局可用）
uv tool install .

# 或使用 pip
pip install .

{
  "mcpServers": {
    "oceanbase": {
      "command": "oceanbase-oracle-mcp",
      "args": [],
      "env": {
        "OB_HOST": "你的数据库地址",
        "OB_PORT": "2883",
        "OB_USER": "用户名@租户名#集群名",
        "OB_PASS": "密码",
        "OB_BACKUP_DIR": "<你的备份目录>"
      }
    }
  }
}

{
  "mcpServers": {
    "oceanbase": {
      "command": "oceanbase-oracle-mcp",
      "args": [],
      "env": {
        "OB_HOST": "127.0.0.1",
        "OB_PORT": "2883",
        "OB_USER": "用户名@租户名#集群名",
        "OB_PASS": "密码"
      }
    }
  }
}

/mcp

查询 employee 表的前 5 条数据

查看 employee 表的字段信息

搜索所有名称中包含 employee 的表

分析这条 SQL 的执行计划：SELECT * FROM employee WHERE hire_date > '2026-01-01'

导出 pkg_employee_mgmt 的包体

查看 employee 表的统计信息

┌─────────────────────────────────────────────────────────────┐
│                   Claude Code / AI 客户端                     │
│                    (MCP Client, stdio)                       │
└─────────────────────────┬───────────────────────────────────┘
                          │ JSON-RPC (stdin/stdout)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                 Python MCP Server (server.py)                │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐    │
│  │  JavaProcess 管理器                                    │    │
│  │  • 启动/守护 Java 长进程                               │    │
│  │  • 通过 stdin 发送 JSON 命令                           │    │
│  │  • 从 stdout 读取响应（以 ---END--- 分隔）             │    │
│  │  • 连接断开自动重启                                    │    │
│  └──────────────────────┬───────────────────────────────┘    │
└─────────────────────────┼───────────────────────────────────┘
                          │ JSON 行协议 (stdin/stdout)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│               Java 长进程 (MCPWorker)                        │
│                                                              │
│  ┌─────────────┐    ┌──────────────┐    ┌───────────────┐   │
│  │ 命令路由     │───▶│ QueryRunner  │───▶│ OceanBase DB  │   │
│  │ (MCPWorker) │    │ (JDBC 查询)  │    │ (长连接)      │   │
│  └─────────────┘    └──────────────┘    └───────────────┘   │
│                                                              │
│  进程内存: ~42MB   │  查询延迟: 100~300ms                    │
│  数据库连接: 长连接  │  连接断开: 自动重连                   │
└─────────────────────────────────────────────────────────────┘

用户输入
    │
    ▼
┌──────────────────────┐
│  Python 层            │  正则匹配危险关键字
│  • DDL: DROP, ALTER   │  (不区分大小写)
│  • DML: INSERT, UPDATE │
│  • 管理: GRANT, REVOKE │
│  • 其他: EXEC, CALL    │
└──────┬───────────────┘
       │ 通过
       ▼
┌──────────────────────┐
│  Java 层              │  关键词匹配（兜底）
│  • 同样的关键字检查    │
│  • 区分大小写          │
│  • 双重保险            │
└──────┬───────────────┘
       │ 通过
       ▼
    SQL 执行

oceanbase-oracle-mcp/
│
├── oceanbase_oracle_mcp.py          ← 入口文件（根目录转发器）
├── pyproject.toml                   ← 项目配置 + 打包配置
├── README.md                        ← 文档（含更新日志）
├── .gitignore                       ← Git 忽略规则
├── .mcp.json                        ← 项目级 MCP 配置（含数据库密码，已加入 .gitignore）
├── .python-version                  ← Python 版本声明
├── uv.lock                          ← uv 依赖锁文件
│
├── src/oceanbase_mcp/               ← ★ Python 源码包（打包部署用）
│   ├── __init__.py                  ←   包标记
│   ├── server.py                    ←   MCP Server 实现（工具定义 + Java 进程管理）
│   └── jdbc_helper/                 ←   ★ Java 运行文件（打包时自动包含）
│       ├── MCPWorker.class          ←     长进程 Worker（编译后）
│       ├── MCPWorker.java           ←     长进程 Worker（源码，供参考）
│       ├── QueryRunner.class        ←     JDBC 查询工具（编译后）
│       ├── QueryRunner$QueryResult.class ← 查询结果包装类（编译后）
│       ├── QueryRunner.java         ←     JDBC 查询工具（源码，供参考）
│       └── oceanbase-client.jar     ←     OceanBase JDBC 驱动
│
├── jdbc_helper/                     ← ★ Java 源码开发目录（改代码在这里）
│   ├── MCPWorker.java               ←   长进程 Worker
│   ├── QueryRunner.java             ←   JDBC 查询工具
│   ├── MCPWorker.class              ←   编译产物
│   ├── QueryRunner.class            ←   编译产物
│   ├── QueryRunner$QueryResult.class←   编译产物
│   └── oceanbase-client.jar         ←   OceanBase JDBC 驱动
│
├── dist/                            ← 打包产物（执行 uv build 后生成）
│   └── oceanbase_oracle_mcp-0.1.0-py3-none-any.whl
│
└── .claude/                         ← Claude Code 本地配置
    └── settings.local.json

# 克隆项目
git clone https://github.com/your-username/oceanbase-oracle-mcp.git
cd oceanbase-oracle-mcp

# 安装开发依赖
uv sync

# 修改 Java 后重新编译
cd jdbc_helper
javac -encoding utf-8 -cp oceanbase-client.jar QueryRunner.java MCPWorker.java

# 编译后复制到包内（重要！否则打包时不会包含新 class）
cp *.class ../src/oceanbase_mcp/jdbc_helper/

# 重新打包并全局安装
cd ..
uv build --wheel
uv tool install --force dist/*.whl

# 其他窗口 /mcp 重连即可生效

{"command": "query", "sql": "SELECT * FROM DUAL", "max_rows": 100}

{"columns": ["ID", "NAME"], "rows": [["1", "test"]], "rowCount": 1, "truncated": false}

Error: [WinError 267] 目录名称无效。

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/oceanbase_mcp"]
include = [
    "src/oceanbase_mcp/**",    # 包含所有文件，不再逐个枚举类型
]

oceanbase_mcp/__init__.py
oceanbase_mcp/server.py
oceanbase_mcp/jdbc_helper/MCPWorker.class
oceanbase_mcp/jdbc_helper/MCPWorker.java
oceanbase_mcp/jdbc_helper/QueryRunner$QueryResult.class
oceanbase_mcp/jdbc_helper/QueryRunner.class
oceanbase_mcp/jdbc_helper/QueryRunner.java
oceanbase_mcp/jdbc_helper/oceanbase-client.jar

conn = DriverManager.getConnection(url, props);
conn.setAutoCommit(true);                                    // 新增：每次查询后自动提交
conn.setTransactionIsolation(Connection.TRANSACTION_READ_COMMITTED); // 新增：读已提交隔离级别

private void maybeReconnect() {
    long now = System.currentTimeMillis();
    if (lastQueryTime > 0 && (now - lastQueryTime) < RECONNECT_INTERVAL) return;
    // 发送快速 ping 检测连接
    Statement stmt = conn.createStatement();
    stmt.setQueryTimeout(3);
    stmt.executeQuery("SELECT 1 FROM DUAL").close();
    // 连接异常时自动重建
}

public static final int QUERY_TIMEOUT = 15;

// executeQuery
stmt.setQueryTimeout(QUERY_TIMEOUT);

// exportSource
ps.setQueryTimeout(QUERY_TIMEOUT);

// getTableStats（所有子查询）
ps.setQueryTimeout(QUERY_TIMEOUT);
stmt.setQueryTimeout(QUERY_TIMEOUT);

// getExplainPlan
stmt.setQueryTimeout(QUERY_TIMEOUT);

def send(self, cmd: dict, timeout: int = 15) -> str:
    # ... 正常发送和等待 ...
    
    # 超时：杀掉 Java 进程（数据库查询也会被终止），下次自动重建
    self._kill()
    raise TimeoutError(f"查询超时 ({timeout}秒)，已终止查询。")

def _kill(self):
    """强制杀掉 Java 进程"""
    if self._process is not None:
        try:
            self._process.kill()
            self._process.wait(timeout=5)
        except Exception:
            pass
        self._process = None

查询发起
    │
    ▼
┌──────────────────────┐
│  Java 端              │  第一道防线
│  setQueryTimeout(15)  │  数据库主动终止 SQL
│  → SQL 被 kill        │  （正常情况）
└──────┬───────────────┘
       │ 如果 JVM 也卡死了
       ▼
┌──────────────────────┐
│  Python 端             │  第二道防线
│  15 秒超时 → _kill()   │  强制杀进程 + 重建
│  → Java 进程终止       │  （极端兜底）
└──────────────────────┘

} catch (IllegalArgumentException e) {
    return "ERROR: " + e.getMessage();
} catch (SQLException e) {
    // SQL 执行错误（语法错误、表不存在等），直接返回不重试
    String msg = e.getMessage();
    if (msg != null && msg.contains("\n")) msg = msg.substring(0, msg.indexOf("\n"));
    return "ERROR: SQL 执行失败: " + (msg != null ? msg : "未知错误");
} catch (Exception e) {
    // 连接可能断开，尝试重连一次（真正的系统级异常）
    // ... 原有重试逻辑不变 ...
}

① preview_write(sql)
   ├─ 解析 SQL 类型和表名
   ├─ UPDATE/DELETE → SELECT 预览受影响数据（最多 10 行）
   ├─ INSERT → 显示目标表结构 + 待插入值
   ├─ DDL → 高危警告 + 完整 DDL
   └─ 返回：预览信息 + 一次性令牌 token

② 用户确认后 → confirm_write(token)
   ├─ 验证 token 有效、未过期
   ├─ 执行写操作
   └─ 返回：影响行数

用户: "把 AA01 表 ID=5 的 NAME 改成 '测试'"
LLM: → 调用 preview_write("UPDATE AA01 SET NAME='测试' WHERE ID=5")
     → 返回:
       操作类型: UPDATE
       目标表: AA01
       将影响的数据预览: {ID:5, NAME:"旧值", ...}
       token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
     → 展示预览给用户: "将更新 AA01 表 1 行数据，确认执行吗？"

用户: "确认执行"
LLM: → 调用 confirm_write("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
     → 返回: 执行成功！影响行数: 1

private char unescapeJson(char c) {
    switch (c) {
        case 'n':  return '\n';
        case 't':  return '\t';
        case 'r':  return '\r';
        case 'b':  return '\b';
        case 'f':  return '\f';
        case '/':  return '/';
        default:   return c; // '"', '\\' 保持原样
    }
}

// 改前
value.append(json.charAt(i));
// 改后
value.append(unescapeJson(json.charAt(i)));

# 统一换行为 \n，让 write_text 的文本模式自动转为平台原生换行
clean_source = source.replace("\r\n", "\n")
file_path.write_text(clean_source, encoding="utf-8")

# 给 Java 进程一点时间初始化，检查是否立即崩溃
time.sleep(1)
if self._process.poll() is not None:
    err = self._process.stderr.read() if self._process.stderr else ""
    # 只取最后一行错误（通常是根因）
    err_lines = [l for l in err.splitlines() if l.strip()]
    root_cause = err_lines[-1] if err_lines else "未知错误"
    raise RuntimeError(f"Java 进程启动失败: {root_cause}\n完整错误:\n{err}")

# 卸载全局命令
uv tool uninstall oceanbase-oracle-mcp

# 或使用 pip
pip uninstall oceanbase-oracle-mcp