mcp-oracle-server/README_NPM.md

MCP (Model Context Protocol) client for Oracle Database with tool discovery - Executable via NPX

# mcp-oracle-server

MCP (Model Context Protocol) client for Oracle Database - Execute via NPX

[![npm version](https://badge.fury.io/js/mcp-oracle-server.svg)](https://www.npmjs.com/package/mcp-oracle-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ⚡ Quick Start

No installation required! Just configure and use:

### 1. Configure Cursor IDE

Create or edit: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "oracle": {
      "command": "npx",
      "args": ["-y", "mcp-oracle-server"],
      "env": {
        "MCP_ORACLE_URL": "http://your-server:8080"
      }
    }
  }
}
```

### 2. Restart Cursor

Close and reopen Cursor IDE.

### 3. Test

Ask Cursor: "List available schemas in Oracle"

## 🎯 What is this?

This package is a **MCP client** that connects to an Oracle Database HTTP server. It implements the Model Context Protocol, allowing AI assistants like Cursor, Claude Code, and VS Code to interact with Oracle databases.

## 🏗️ Architecture

```
┌─────────────┐         ┌────────────────┐         ┌──────────────┐
│  Cursor IDE │ stdio   │  mcp-oracle    │  HTTP   │  HTTP Server │
│   (AI)      │ ◄──────►│  (this pkg)    │ ◄──────►│   (Python)   │
└─────────────┘         └────────────────┘         └──────┬───────┘
                                                           │
                                                   ┌───────▼────────┐
                                                   │ Oracle DB      │
                                                   └────────────────┘
```

## 📋 Requirements

- **Node.js 18+** (for running this client via npx)
- **HTTP Server** running with access to Oracle Database
- **Cursor IDE** or compatible MCP client

## 🔧 Configuration

### Environment Variable

| Variable | Description | Example |
|----------|-------------|---------|
| `MCP_ORACLE_URL` | HTTP server URL | `http://10.10.11.5:8080` |

### IDE Configuration

#### Cursor IDE
```json
{
  "mcpServers": {
    "oracle": {
      "command": "npx",
      "args": ["-y", "mcp-oracle-server"],
      "env": {
        "MCP_ORACLE_URL": "http://10.10.11.5:8080"
      }
    }
  }
}
```

#### VS Code (with MCP extension)
Same configuration as Cursor.

## 🛠️ Available Tools

The client automatically discovers tools from the server. To see all available endpoints:

```bash
curl http://your-server:8080/mcp/tools
```

### Main Tools

- **execute_sql** - Execute SQL SELECT queries
- **get_schemas** - List available schemas
- **get_tables** - List tables in a schema
- **describe_table** - Show table structure
- **get_source** - Get PL/SQL source code
- **health_check** - Check server status
- **get_metrics** - Get performance metrics

## 📖 Usage Examples

### Ask Cursor

```
"List the first 10 products from CONSINCO.MAP_PRODUTO"
"Count how many records are in CONSINCO.MAP_PRODUTO"
"Show me the structure of table CONSINCO.MAP_PRODUTO"
"List all tables in schema CONSINCO"
```

The AI will automatically:
1. Discover available endpoints
2. Execute appropriate SQL queries
3. Present results in a readable format

## 🤖 For AI Agents

If you're an AI reading this:

### ⚠️ CRITICAL: Never Use /execute

The server does NOT have an `/execute` endpoint. Always use `/sql`:

```bash
# ✅ CORRECT
curl -X POST ${MCP_ORACLE_URL}/sql \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM CONSINCO.MAP_PRODUTO WHERE ROWNUM <= 10"}'

# ❌ WRONG - This endpoint does not exist!
curl -X POST ${MCP_ORACLE_URL}/execute ...
```

### 📋 SQL Query Rules

1. **ALWAYS** include schema: `CONSINCO.TABLE_NAME`
2. **ALWAYS** limit results: `WHERE ROWNUM <= 100`
3. **ONLY** SELECT is allowed (no INSERT/UPDATE/DELETE)

### 🔍 Discovery Flow

1. First, call: `GET ${MCP_ORACLE_URL}/mcp/tools`
2. Read the returned instructions
3. Use the endpoints listed in the response

## 🔒 Security

- ✅ Only SELECT queries allowed
- ✅ Schema validation
- ✅ Rate limiting (60 req/min)
- ✅ Maximum 1000 rows per query
- ✅ Connection pooling

## 📝 Changelog

### v1.2.0
- ✨ Added `/mcp/tools` endpoint for tool discovery
- 📚 Added `.cursorrules` for AI instructions
- 🔧 Examples using `${MCP_ORACLE_URL}` variable
- 📖 Complete AI agent documentation

### v1.1.1
- 🐛 Fixed npm publish script
- 📦 Removed failing test requirement

### v1.1.0
- 🎉 First public release
- ✨ NPX support
- 🔧 MCP client implementation

## 🆘 Troubleshooting

### "No tools available" error

1. **Check server is running:**
   ```bash
   curl http://your-server:8080/health
   ```

2. **Verify MCP_ORACLE_URL is correct** in your configuration

3. **Restart Cursor** after changing configuration

4. **Check server logs** on the HTTP server machine

### "Connection refused" error

- Ensure HTTP server is running
- Check firewall allows port 8080
- Verify server is listening on `0.0.0.0` not just `127.0.0.1`

### Server Setup

This package requires a separate HTTP server with Oracle access. See the [full documentation](https://github.com/edapinheiro/mcp-oracle) for server setup instructions.

## 🔗 Links

- **GitHub Repository:** https://github.com/edapinheiro/mcp-oracle
- **npm Package:** https://www.npmjs.com/package/mcp-oracle-server
- **MCP Protocol:** https://modelcontextprotocol.io

## 📄 License

MIT

## 👤 Author

**Ed Pinheiro**
- Email: ed1404@gmail.com
- GitHub: [@edapinheiro](https://github.com/edapinheiro)

## 🙏 Credits

- Built with [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic
- Compatible with Cursor IDE, VS Code, and other MCP clients

---

**Made with ❤️ for the Oracle community**