使用说明

项目简介

• 本项目实现一个 MCP 服务器，专注于 Oracle 数据库的后端能力。它通过一组工具（Tools）向 AI 客户端暴露数据库查询、描述、DDL、索引等操作，支撑多数据库连接、连接池管理、SYSDBA 模式、查询日志等功能，并提供会话监控与安全控制。

主要功能点

• 多数据库支持：可同时连接并管理多个 Oracle 数据库，统一在一个 MCP 服务中调度。
• Discovery 与查询工具：locate_table、list_databases、list_tables、describe_table、get_object_ddl、list_constraints、list_indexes 等，帮助 AI 客户端快速发现并分析数据对象。
• 数据操作与查询：run_read_only_query、run_query_with_pagination、run_modification_query 等，覆盖只读、分页查询及 DML/DDL 操作（带提交控制与回滚机制）。
• DDL 与元数据：get_object_ddl、get_table_ddl（兼容性工具）、describe_table、list_constraints、list_indexes 等，便于提取结构和定义。
• 性能与监控：explain_query_plan、inspect_locks、get_session_info 等，辅助优化与排错。
• 安全性与治理：对标识符进行校验，限制危险关键词，保护表、可配置的保护表清单，参数化查询，锁定高危操作。
• 导出与记录：export_query_to_csv、query 日志、结果以 Markdown 表格呈现，便于在 MCP 客户端直接展示。

安装步骤

• 环境与依赖
  • 需要 Python 3.x 环境，安装 oracledb 驱动，以及 dotenv 等依赖（仓库中已有实现，具体依赖可在环境中通过 pip 安装）。
  • Oracle Instant Client 放置在仓库的 instantclient_23_0 目录下，确保客户端库能被正确加载。
• 运行服务器
  • 进入项目根目录，确保 Python 解释器能够找到 src 包（如果需要，设置 PYTHONPATH 指向 src）。
  • 启动命令示例（请在 MCP 客户端配置中使用相同入口）：
    • python -m mcp_oracle_server
  • 第一次运行前，请准备 oracle_config.json 来配置数据库连接信息（如果没有使用单数据库模式，则需要提供多数据库配置）。
• 配置示例（数据库、全局设置等）
  • Oracle 数据库连接信息通常放在 oracle_config.json，包含名称、用户名、密码、DSN 等；全局设置包括默认数据库、连接池参数、导出目录等。
  • 也支持通过环境变量覆盖少量全局设置，如 ORACLE_CLIENT_PATH、EXPORT_DIRECTORY、LOG_LEVEL 等。
• MCP 客户端连接配置（服务器端并不需要客户端代码，客户端只需知道如何启动服务器）
  • MCP 客户端需配置服务器的启动命令和参数，让客户端可通过 JSON-RPC 与服务器通信。以下为可用于 MCP 客户端配置的示例（请勿直接用于代码块，仅作参考文本描述）：
  • JSON 配置（示例文本）: { "mcpServers": { "oracle-server": { "command": "python", "args": ["-m", "mcp_oracle_server"], "env": { "PYTHONIOENCODING": "utf-8", "PYTHONPATH": "/path/to/mcp-oracle-server/src", "ORACLE_CONFIG_DIR": "/path/to/mcp-oracle-server" } } } } 说明
  • server name 对应 MCP 客户端中的服务器标识（如 oracle-server）。
  • command 指定启动服务器的方式（此处为 Python 解释器）。
  • args 指定启动参数，使用 -m mcp_oracle_server 作为入口模块。
  • env 的 PYTHONPATH 指向源码中的 src 目录，ORACLE_CONFIG_DIR 指向 oracle_config.json 所在目录。
  • 这是免代码的配置信息，客户端需要此信息来启动并连接 MCP 服务器。
• 基本使用方法
  • 启动后，MCP 客户端即可向服务器发起请求，调用工具、查询数据库、获取元数据、导出数据等。
  • 使用时请确保 oracle_config.json 配置正确，数据库可达且凭据有效；若使用 SYSDBA，请在配置中开启 SYSDBA 模式。
  • 通过客户端工具提供的 UI/控制台或 JSON-RPC 方式发送请求，服务器将按工具实现返回格式化结果（Markdown 风格文本等），并在必要时输出可视化表格或 CSV 文件。