使用说明

项目简介

本项目 'Oracle数据库MCP服务器' 是一个基于 Model Context Protocol (MCP) 构建的后端服务，旨在为LLM（大型语言模型）应用提供与 Oracle 数据库交互的能力。它通过标准化的 MCP 协议，向客户端暴露了一系列工具，使得 LLM 能够安全、可控地执行 SQL 查询、获取表结构信息以及浏览数据库中的表。

主要功能点

SQL查询执行: 提供 'execute_oracle' 工具，允许 LLM 客户端执行安全的 SELECT 查询语句，并返回格式化的查询结果。支持绑定变量，防止 SQL 注入，并限制查询长度和返回行数，保障数据库安全和性能。
表结构描述: 提供 'describe_table' 工具，允许 LLM 客户端获取指定表的详细结构信息，包括列名、数据类型、是否允许为空以及列注释，帮助 LLM 理解数据库 schema。
表列表检索: 提供 'list_tables' 工具，允许 LLM 客户端列出数据库中的所有或部分表，支持通过表名模式进行过滤，并可选择是否包含系统表，方便 LLM 探索数据库内容。
安全保障: 实施多重安全措施，包括 SQL 查询语句的白名单关键词过滤、输入参数的安全清理、以及对查询长度和复杂度的限制，防止恶意 SQL 注入和资源滥用。
Prompt 引导: 提供 'oracle_query_assistant' Prompt，为 LLM 客户端提供 'execute_oracle' 工具的使用指南和最佳实践，包括 SQL 模板、参数示例、常见错误排查以及数据类型指导，降低 LLM 使用工具的门槛。

安装步骤

克隆仓库

git clone https://github.com/kutsushitaneko/mcp-server-for-oracle-database.git
cd mcp-server-for-oracle-database

安装 Python 依赖 确保你的 Python 环境中已安装必要的库。如果未安装，请运行以下命令安装：
```
pip install oracledb python-dotenv sqlparse fastmcp-server
```
- 确保已安装 Oracle 客户端库 (如 Oracle Instant Client)，并且 'oracledb' 库能够正确连接到 Oracle 数据库。

配置数据库连接信息 在项目根目录下创建 '.env' 文件，并根据你的 Oracle 数据库配置填写以下环境变量：

DB_USER=your_db_username
DB_PASSWORD=your_db_password
DB_DSN=your_db_dsn  # 例如：localhost:1521/YOUR_SERVICE_NAME

请替换 'your_db_username', 'your_db_password', 和 'your_db_dsn' 为你的实际数据库连接信息。

服务器配置

MCP 客户端需要配置以下 JSON 信息以连接到此 MCP 服务器。无需修改任何代码，只需将以下 JSON 配置提供给你的 MCP 客户端即可。

{
  "serverName": "oracle-mcp-server",
  "command": "python",
  "args": ["oracledb_mcp_server.py"]
}

配置参数说明:

'serverName': 服务器的名称，可以自定义，例如 "oracle-mcp-server"。
'command': 启动服务器的命令，这里使用 'python' 解释器。
'args': 启动命令的参数，指定服务器主程序文件为 'oracledb_mcp_server.py'。

MCP客户端配置示例

假设你的 MCP 客户端是一个名为 'mcp-client-app' 的应用程序，你需要在该应用的配置文件中添加上述 JSON 配置。具体的配置方式取决于 'mcp-client-app' 的实现，但通常会有一个配置文件（例如 JSON 或 YAML 格式）允许你指定要连接的 MCP 服务器。

例如，如果 'mcp-client-app' 的配置文件是 'config.json'，你可能会在其中添加类似如下的配置：

{
  "mcpServers": [
    {
      "serverName": "oracle-mcp-server",
      "command": "python",
      "args": ["oracledb_mcp_server.py"]
    },
    // ... 其他 MCP 服务器配置 ...
  ],
  // ... 其他客户端配置 ...
}

请参考你的 MCP 客户端应用程序的文档，了解如何正确配置和连接 MCP 服务器。

基本使用方法

启动 MCP 服务器 在项目根目录下，运行以下命令启动 MCP 服务器：
```
python oracledb_mcp_server.py
```
服务器将通过 stdio 监听 MCP 客户端的请求。
配置并启动 MCP 客户端 根据 MCP 客户端的文档，配置上述服务器连接信息，并启动 MCP 客户端。客户端将通过 MCP 协议与服务器通信。
通过 MCP 客户端调用工具 在 MCP 客户端中，你可以调用以下工具与 Oracle 数据库进行交互：
- 'execute_oracle': 执行 SQL 查询。你需要提供 'query' 参数（SQL 查询语句），以及可选的 'params'（绑定变量参数）、'max_length'（最大返回字符数）、'max_rows'（最大返回行数）参数。
- 'describe_table': 获取表结构信息。你需要提供 'table_name' 参数（表名）。
- 'list_tables': 列出数据库表。你可以使用 'max_rows', 'name_pattern', 'order_by', 'include_system_tables' 等可选参数进行过滤和排序。
参考 Prompt 获取工具使用指导 你可以调用 'oracle_query_assistant' Prompt 获取 'execute_oracle' 工具的详细使用指南，包括 SQL 模板、参数示例、以及使用技巧。

示例：使用 execute_oracle 工具

假设你想查询 'employees' 表中 'department_id' 为 50 的员工信息。你可以通过 MCP 客户端调用 'execute_oracle' 工具，并提供如下参数：

{
  "tool_call": {
    "name": "execute_oracle",
    "arguments": {
      "query": "SELECT employee_id, first_name, last_name FROM employees WHERE department_id = :dept_id",
      "params": {"dept_id": 50},
      "max_rows": 20
    }
  }
}

服务器将执行该 SQL 查询，并将格式化的结果返回给 MCP 客户端。

请根据你的 MCP 客户端的具体使用方式，参考以上说明进行操作。

关键词