MCP Server - Oracle DB Context

MCP 服务 - Oracle DB Context

English | 中文

一款功能强大的 Model Context Protocol（MCP）服务，可为大型 Oracle 数据库提供上下文数据库架构信息，帮助 AI 助手理解并处理包含数千张表的数据库。

目录

• 概述
• 功能
• 用法
  • 与 VSCode Insiders 中的 GitHub Copilot 集成
    • 选项 1：使用 Docker（推荐）
    • 选项 2：使用 UV（本地安装）
  • 在本地启动服务
  • 可用工具
• 架构
• 连接模式
  • Thin 模式（默认）
  • Thick 模式
• 系统要求
• 性能注意事项
• 参与贡献
• 许可证
• 支持

概述

MCP Oracle DB Context 服务解决了处理超大型 Oracle 数据库时的一项关键挑战：如何向 AI 模型提供准确且相关的数据库架构信息，同时避免让数万张表和关系造成信息过载。

通过智能缓存和提供数据库架构信息，该服务使 AI 助手能够：

• 按需查询特定表的架构
• 搜索符合特定模式的表
• 了解表之间的关系和外键
• 获取数据库供应商信息

功能

• 智能架构缓存：构建并维护数据库架构的本地缓存，以尽量减少数据库查询
• 定向架构查询：无需加载整个数据库结构，即可获取特定表的架构
• 表搜索：通过名称模式匹配查找表
• 关系映射：了解表之间的外键关系
• Oracle 数据库支持：专为 Oracle 数据库打造
• MCP 集成：可与 VSCode 中的 GitHub Copilot、Claude、ChatGPT 以及其他支持 MCP 的 AI 助手无缝协作
• 只读模式：默认安全模式，可防止写入操作，同时允许完整读取

用法

与 VSCode Insiders 中的 GitHub Copilot 集成

要在 VSCode Insiders 中将此 MCP 服务与 GitHub Copilot 配合使用，请按以下步骤操作：

1. 安装 VSCode Insiders

   • 下载并安装最新版本的 VSCode Insiders

2. 安装 GitHub Copilot 扩展

   • 打开 VSCode Insiders
   • 前往扩展市场
   • 搜索并安装“GitHub Copilot”

3. 配置 MCP 服务

   • 推荐：使用 Docker
   • 备选：使用 UV

4. 启用 Agent 模式

   • 在 VSCode Insiders 中打开 Copilot 聊天
   • 点击“Copilot Edits”
   • 选择“Agent mode”
   • 点击聊天输入框中的刷新按钮，加载可用工具

完成这些步骤后，即可通过 GitHub Copilot 的聊天界面使用所有数据库上下文工具。

选项 1：使用 Docker（推荐）

在 VSCode Insiders 中，打开用户或工作区的 settings.json 文件并添加以下内容：

"mcp": {
    "inputs": [
     {
       "id": "db-password",
       "type": "promptString",
       "description": "Oracle DB Password",
       "password": true,
     }
   ],
    "servers": {
        "oracle": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "ORACLE_CONNECTION_STRING",
                "-e",
                "TARGET_SCHEMA",
                "-e",
                "CACHE_DIR",
                "-e",
                "THICK_MODE",
                "dmeppiel/oracle-mcp-server"
            ],
            "env": {
               "ORACLE_CONNECTION_STRING":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
               "TARGET_SCHEMA":"",
               "CACHE_DIR":".cache",
               "THICK_MODE":"",  // Optional: set to "1" to enable thick mode
               "ORACLE_CLIENT_LIB_DIR":"", // Optional: in case you use thick mode and you want to set a non-default directory for client libraries
               "READ_ONLY_MODE":"1"  // Optional: set to "0" to allow write operations (default: "1" for read-only)
            }
        }
    }
}

使用 Docker（推荐方式）时：

• 所有依赖项都已包含在容器中
• 如需启用 Thick 模式，请在环境变量中设置 THICK_MODE=1
• 如果使用 THICK_MODE，且 Oracle Client 库的安装路径与默认位置不同，可以选择通过 ORACLE_CLIENT_LIB_DIR 设置该路径。

选项 2：使用 UV（本地安装）

此选项需要在本地安装并设置项目：

1. 前提条件

   • Python 3.12 或更高版本
   • Oracle 数据库访问权限
   • Oracle instant client（oracledb Python 包所必需）

2. 安装 UV

   # 使用 curl 安装 uv（macOS/Linux）
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # 或使用 PowerShell（Windows）
   irm https://astral.sh/uv/install.ps1 | iex
   

   安装 uv 后，请务必重启终端。

3. 项目设置

   # 克隆仓库
   git clone https://github.com/yourusername/oracle-mcp-server.git
   cd oracle-mcp-server
   
   # 创建并激活虚拟环境
   uv venv
   
   # 激活（Unix/macOS）
   source .venv/bin/activate
   
   # 激活（Windows）
   .venv\Scripts\activate
   
   # 安装依赖项
   uv pip install -e .
   

4. 配置 VSCode 设置

   "mcp": {
      "inputs": [
         {
            "id": "db-password",
            "type": "promptString",
            "description": "Oracle 数据库密码",
            "password": true,
         }
      ],
      "servers": {
         "oracle": {
               "command": "/path/to/your/.local/bin/uv",
               "args": [
                  "--directory",
                  "/path/to/your/oracle-mcp-server",
                  "run",
                  "main.py"
               ],
               "env": {
                  "ORACLE_CONNECTION_STRING":"<db-username>/${input:db-password}@<host>:1521/<service-name>",
                  "TARGET_SCHEMA":"",
                  "CACHE_DIR":".cache",
                  "THICK_MODE":"",  // 可选：设置为 "1" 以启用 Thick 模式
                  "ORACLE_CLIENT_LIB_DIR":"", // 可选：如果使用 Thick 模式，并且想为客户端库指定非默认目录
                  "READ_ONLY_MODE":"1"  // 可选：设置为 "0" 以允许写入操作（默认值："1"，只读）
               }
         }
      }
   }
   

• 将路径替换为实际的 uv 二进制文件路径和 oracle-mcp-server 目录路径

对于这两个选项：

• 将 ORACLE_CONNECTION_STRING 替换为实际的数据库连接字符串
• TARGET_SCHEMA 为可选项，默认使用用户的架构
• CACHE_DIR 为可选项，默认使用 MCP 服务根目录下的 .cache
• READ_ONLY_MODE 默认为 "1"（只读），以确保安全。仅在需要写入操作时才设置为 "0"

在本地启动服务

直接运行 MCP 服务：

uv run main.py

用于开发和测试：

# Install the MCP Inspector
uv pip install mcp-cli

# Test with MCP Inspector
mcp dev main.py

# Or install in Claude Desktop
mcp install main.py

可用工具

连接到 GitHub Copilot（VSCode Insiders 中）或 Claude 等 AI 助手后，可使用以下工具：

get_table_schema

获取指定表的详细架构信息，包括列、数据类型、是否可为空以及关系。 示例：

Can you show me the schema for the EMPLOYEES table?

get_tables_schema

一次性获取多个表的架构信息。比多次调用 get_table_schema 更高效。 示例：

Please provide the schemas for both EMPLOYEES and DEPARTMENTS tables.

search_tables_schema

按名称模式搜索表并获取其架构。 示例：

Find all tables that might be related to customers and show their schemas.

rebuild_schema_cache

强制重建架构缓存。请谨慎使用，因为此操作会消耗大量资源。 示例：

The database structure has changed. Could you rebuild the schema cache?

get_database_vendor_info

获取有关已连接 Oracle 数据库版本和架构的信息。 示例：

What Oracle database version are we running?

search_columns

搜索包含与指定词条匹配的列的表。当你知道需要什么数据，但不确定哪些表包含这些数据时，此工具很有用。 示例：

Which tables have columns related to customer_id?

get_pl_sql_objects

获取有关 PL/SQL 对象的信息，例如过程、函数、程序包、触发器等。 示例：

Show me all stored procedures that start with 'CUSTOMER_'

get_object_source

获取 PL/SQL 对象的源代码。适用于调试和理解数据库逻辑。 示例：

Can you show me the source code for the CUSTOMER_UPDATE_PROC procedure?

get_table_constraints

获取表的所有约束（主键、外键、唯一约束、检查约束）。 示例：

What constraints are defined on the ORDERS table?

get_table_indexes

获取表上定义的所有索引，有助于优化查询。 示例：

Show me all indexes on the CUSTOMERS table.

get_dependent_objects

查找依赖于指定数据库对象的所有对象。 示例：

What objects depend on the CUSTOMER_VIEW view?

get_user_defined_types

获取数据库中用户定义类型的信息。 示例：

Show me all custom types defined in the schema.

get_related_tables

获取通过外键与指定表相关的所有表，并显示传入和传出的关系。 示例：

What tables are related to the ORDERS table?

run_sql_query

执行 SQL 查询，并以格式化表格形式返回结果。 示例：

Can you run this query for me? SELECT * FROM EMPLOYEES WHERE DEPARTMENT_ID = 10

注意：在只读模式（默认）下，仅允许执行 SELECT 语句。出于安全考虑，写入操作（INSERT、UPDATE、DELETE）会被阻止。停用只读模式（READ_ONLY_MODE="0"）后，此工具可以执行读取和写入操作。

架构

此 MCP 服务采用针对大型 Oracle 数据库优化的三层架构：

1. DatabaseConnector 层

   • 管理 Oracle 数据库连接和查询执行
   • 实现连接池和重试逻辑
   • 处理原始 SQL 操作

2. SchemaManager 层

   • 实现智能架构缓存
   • 提供优化的架构查找和搜索
   • 管理磁盘上的持久缓存

3. DatabaseContext 层

   • 提供高层 MCP 工具和接口
   • 处理授权和访问控制
   • 为 AI 使用优化架构

连接模式

数据库连接器支持两种连接模式：

Thin 模式（默认）

默认情况下，连接器使用 Oracle 的 Thin 模式，这是一种纯 Python 实现。此模式：

• 更易于设置和部署
• 足以满足大多数基本数据库操作的需求
• 在不同环境之间具有更好的可移植性

Thick 模式

对于需要高级 Oracle 功能或更高性能的场景，可以启用 Thick 模式：

• 使用 Docker 时（推荐）：在 Docker 环境变量中设置 THICK_MODE=1
• 使用本地安装时：导出 THICK_MODE=1 环境变量，并确保已安装与系统架构和数据库版本兼容的 Oracle Client 库

可以使用 ORACLE_CLIENT_LIB_DIR 环境变量指定 Oracle Client 库的自定义位置。以下情况尤其适用：

• Oracle Client 库安装在非标准位置
• 需要在同一系统上使用多个 Oracle Client 版本
• 没有管理权限，无法将 Oracle Client 安装到标准位置
• 需要特定版本的 Oracle Client，以兼容某些数据库功能

注意：使用 Docker 时，无需担心安装 Oracle Client 库，因为它们已包含在容器中（Oracle Instant Client v23.7）。该容器支持 19c 至 23ai 版本的 Oracle 数据库，并支持 linux/arm64 和 linux/amd64 架构。

只读模式

此 MCP 服务默认以只读模式运行，以提高安全性。这样可以在允许对数据库进行完整读取访问的同时，阻止所有写入操作（INSERT、UPDATE、DELETE、DDL）。这有助于防止 AI 生成的查询造成意外更改。

配置

• 默认：READ_ONLY_MODE="1"（只读，安全）
• 写入访问：READ_ONLY_MODE="0"（允许写入操作）

系统要求

• Python：版本 3.12 或更高（实现最佳性能所必需）
• 内存：对于大型数据库（10,000 多张表），需有 4GB 以上可用 RAM
• 磁盘：至少有 500MB 可用空间用于架构缓存
• Oracle：兼容 Oracle Database 11g 及更高版本
• 网络：与 Oracle 数据库服务器保持稳定连接

性能注意事项

• 对于超大型数据库，初始缓存构建可能需要 5-10 分钟
• 后续启动通常不到 30 秒
• 缓存完成后，架构查询通常在不到一秒内完成
• 内存用量随活动架构的大小而变化

贡献

欢迎贡献！详情请参阅我们的贡献指南。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

支持

如有问题或疑问：

• 在此 GitHub 仓库中创建议题