# oradb-explorer-mcp

An MCP server and skills package for read-only Oracle exploration using
`node-oracledb` 7 in Thin mode.

## Download the repository

Windows PowerShell:

```powershell
git clone https://github.com/YOUR_USER/oradb-explorer-mcp.git
Set-Location oradb-explorer-mcp
```

macOS/Linux:

```bash
git clone https://github.com/YOUR_USER/oradb-explorer-mcp.git
cd oradb-explorer-mcp
```

## Setup

Windows PowerShell:

```powershell
npm install
Copy-Item .env.example .env
```

macOS/Linux:

```bash
npm install
cp .env.example .env
```

Windows `.env`:

```dotenv
ORACLE_USER=your_user
ORACLE_PASSWORD=your_password
ORACLE_DSN=your_connect_string
# Optional: used only if the normal Thin-mode connection fails
ORACLE_WALLET_LOCATION=C:\secure\adb-wallet
```

macOS/Linux `.env`:

```dotenv
ORACLE_USER=your_user
ORACLE_PASSWORD=your_password
ORACLE_DSN=your_connect_string
# Optional: used only if the normal Thin-mode connection fails
ORACLE_WALLET_LOCATION=/home/your-user/adb-wallet
```

Never commit the real `.env` file.

## Start locally

Windows and macOS/Linux:

```bash
npx tsx mcp/server.ts
```

The server uses MCP stdio and normally produces no terminal output.

## Codex MCP configuration

Windows:

```toml
[mcp_servers.oradb]
command = 'C:\path\to\oradb-explorer-mcp\node_modules\.bin\tsx.cmd'
args = ['C:\path\to\oradb-explorer-mcp\mcp\server.ts']
env = { ORACLE_ENV_FILE = '.env' }
startup_timeout_sec = 30
tool_timeout_sec = 120
```

macOS/Linux:

```toml
[mcp_servers.oradb]
command = '/path/to/oradb-explorer-mcp/node_modules/.bin/tsx'
args = ['/path/to/oradb-explorer-mcp/mcp/server.ts']
env = { ORACLE_ENV_FILE = '.env' }
startup_timeout_sec = 30
tool_timeout_sec = 120
```

## Available tools

```text
oradb_connect
oradb_status
oradb_disconnect
oradb_tables
oradb_describe
oradb_indexes
oradb_sql_preview
oradb_run_readonly_sql
oradb_dataframe_preview
oradb_dataframe_export
```

## Natural-language workflow

The MCP server does not use Select AI or generate SQL inside the database.
The host agent interprets the user’s natural-language request and generates a
candidate SQL statement. The MCP server validates and executes it safely.

Recommended workflow:

```text
1. User describes the desired analysis.
2. The agent generates one read-only SELECT or WITH statement.
3. The agent calls oradb_sql_preview.
4. The SQL and bind values are reviewed.
5. The agent calls oradb_run_readonly_sql with a row limit.
```

Example request:

```text
Find the five most recent active customers and return their ID, name,
status, and registration date.
```

The agent may generate:

```sql
SELECT customer_id, name, status, registration_date
FROM customers
WHERE status = :status
ORDER BY registration_date DESC
FETCH FIRST 5 ROWS ONLY
```

with binds:

```json
{
  "status": "ACTIVE"
}
```

## Schema exploration examples

```text
List tables whose names start with CUSTOM.
```

```text
Describe the CUSTOMERS table.
```

```text
List indexes on APP_SCHEMA.CUSTOMERS.
```

## Dataframe examples

Preview selected columns:

```text
Preview CUSTOMER_ID, NAME, and STATUS from CUSTOMERS, limited to 20 rows.
```

Export a bounded result to a user-selected file:

```text
Export CUSTOMER_ID, NAME, and STATUS from CUSTOMERS to
/tmp/customers.csv using oradb_dataframe_export.
```

Windows example:

```text
Export CUSTOMER_ID, NAME, and STATUS from CUSTOMERS to
C:\\temp\\customers.csv using oradb_dataframe_export.
```

Supported formats are CSV and JSON. The result can then be consumed by pandas,
Polars, or marimo without overwhelming the agent context.

## Safety boundary

The server allows one bounded `SELECT` or `WITH` statement. It rejects
semicolon-separated statements and does not provide DDL, DML, PL/SQL, commit,
privilege, or credential-management tools.

Credentials, wallet files, database dumps, and generated artifacts must remain
outside Git.