npm package: @studious-xiaoyu/oracle-link
Description: Oracle MCP Query Server (Node.js) - Read-only SELECT via MCP
Latest version: 0.2.3

# Oracle MCP Query Tool

一个基于 MCP（Model Context Protocol）的 Oracle 数据库“只读查询”服务器（Node.js/TypeScript），允许 MCP 客户端安全地执行 SELECT 查询。

## 功能特点

- 通过 MCP 协议与 AI 助手集成
- 仅执行 SELECT 查询获取数据（强制行数上限）
- 拒绝一切写操作（INSERT/UPDATE/DELETE 等）
- 安全的查询执行环境

## 安装与运行

依赖安装：

```
npm install
```

## 配置

在 `src/config.ts` 中直接填写数据库连接与默认行数：

```
export const oracleConfig = {
  username: 'your_username',
  password: 'your_password',
  connectString: 'localhost:1521/your_service_name',
  defaultMaxRows: 100
}
```

## 使用方法

### 开发模式（stdio）

```
npx -y tsx src/index.ts
```

### 作为 MCP 服务器运行（Node.js）

默认以 `stdio` 传输运行，便于在 Claude/Inspector 中作为命令接入；也可扩展为 `HTTP` 传输。

## 可用工具

### oracle_query
执行 SELECT 查询并返回结果

参数:
- `sql`: 要执行的 SELECT 查询语句（允许 `SELECT` 或 `WITH` 开头）
- `max_rows`: 返回的最大行数（可选，默认 100；未限制时自动追加 `FETCH FIRST {max_rows} ROWS ONLY`）

### oracle_list_tables
列出当前用户或指定 `owner` 的所有表名，并返回数量

参数:
- `owner`: 可选，指定 schema/owner 名（建议使用大写）

返回:
- `success`: 是否成功
- `count`: 表数量
- `tables`: 表名数组
- `message`: 文本信息

### oracle_describe_table
查询指定表的详细元数据

参数:
- `table_name`: 表名（建议使用大写）
- `owner`: 可选，schema/owner 名（建议使用大写）

返回:
- `success`: 是否成功
- `table`: 表名
- `comment`: 表注释
- `columns`: 列定义（名称/类型/长度/精度/可空/默认/列注释）
- `primaryKey`: 主键列
- `uniqueConstraints`: 唯一约束及其列
- `foreignKeys`: 外键（约束名、列、引用的表和列）
- `indexes`: 索引（名称、唯一性、列）

## 开发

### 依赖

- Node.js 18+
- @modelcontextprotocol/sdk、zod、oracledb、dotenv

### 项目结构

```
oracle-link/
├── src/index.ts         # MCP 服务器入口（stdio）
├── src/oracle.ts        # Oracle 只读查询封装
├── package.json         # Node 项目配置与脚本
├── tsconfig.json        # TypeScript 配置
└── README.md            # 说明文档
```

## 注意事项

1. 确保已安装/可用 Oracle 客户端库
2. 确保网络连接和防火墙设置允许访问 Oracle 数据库
3. 强烈建议在生产环境使用只读账号，仅授予查询权限

## 集成到 MCP 客户端
 
### 通用（npx 启动 stdio）
- 在你的 MCP 客户端里声明一个 stdio 服务器：
```
command: "npx"
args: ["-y", "@studious-xiaoyu/oracle-link"]
env:
  ORACLE_USERNAME: "scott"
  ORACLE_PASSWORD: "tiger"
  ORACLE_CONNECT_STRING: "localhost:1521/xe"
  DEFAULT_MAX_ROWS: "100"
```

### Claude Desktop 配置示例（Windows/macOS）
- 在 `claude_desktop_config.json` 的 `mcpServers` 中添加：
```
{
  "mcpServers": {
    "oracle-link": {
      "command": "npx",
      "args": ["-y", "@studious-xiaoyu/oracle-link"],
      "env": {
        "ORACLE_USERNAME": "scott",
        "ORACLE_PASSWORD": "tiger",
        "ORACLE_CONNECT_STRING": "localhost:1521/xe",
        "DEFAULT_MAX_ROWS": "100"
      }
    }
  }
}
```

### Cursor 设置示例
- 在 Cursor 的 MCP 设置中添加：
```
name: "oracle-link"
type: "stdio"
command: "npx"
args: ["-y", "@studious-xiaoyu/oracle-link"]
env:
  ORACLE_USERNAME: "scott"
  ORACLE_PASSWORD: "tiger"
  ORACLE_CONNECT_STRING: "localhost:1521/xe"
```

### 凭据传递方式
- 环境变量：通过 `ORACLE_USERNAME`、`ORACLE_PASSWORD`、`ORACLE_CONNECT_STRING`、`ORACLE_PRIVILEGE`（可选）提供连接信息。
- 工具级 URL：在调用工具时传入 `url` 覆盖连接，例如：
  - `oracle://scott:tiger@localhost:1521/xe?maxRows=100`
  - `oracle://sys:sys_password@localhost:1521/xe?privilege=SYSDBA&maxRows=100`

### 可用工具与输入
- `oracle_query`：`sql`、`max_rows`（默认 `DEFAULT_MAX_ROWS`）、`url`（可选）。
- `oracle_list_tables`：`owner`（可选）、`url`（可选）。
- `oracle_describe_table`：`table_name`、`owner`（可选）、`url`（可选）。

### 运行与排错
- 本地手动启动：`npx -y @studious-xiaoyu/oracle-link` 或 `node dist/index.js`。
- 如果客户端无法识别工具，检查：
  - 客户端是否支持 MCP stdio。
  - 环境变量是否设置正确。
  - 是否能连通 Oracle（端口、防火墙、权限）。