使用说明

MCP Oracle服务器（HTTP传输）

用于Oracle数据库的生产级Node.js模型上下文协议（MCP）服务器 HTTP传输 用于Telnyx AI代理兼容性。此服务器通过HTTP/JSON-RPC公开MCP工具，实现与Telnyx和其他基于HTTP的MCP客户端的集成。

特性

✅ 基于HTTP的MCP协议：完整的HTTP/JSON-RPC实现（不是STDIO）
✅ Telnyx兼容：专为Telnyx AI代理MCP集成而设计
✅ Oracle数据库集成：连接池与 oracledb 驾驶员
✅ API密钥验证：安全 /mcp 具有API密钥验证的端点
✅ MCP工具:
- runQuery：使用绑定参数执行SQL查询
- listTables：列出数据库中的所有表
- getSchema：获取详细的表架构信息
- nl2sql：使用外部服务将自然语言转换为SQL
✅ Web服务器：Express服务器 /health, /ready, /metrics, /webhook/telnyx
✅ 生产就绪：日志记录、错误处理、连接池、优雅关机
✅ Docker化：使用Docker Compose完全容器化

项目结构

mcp-oracle/
├── src/
│   ├── server.js          # Main entrypoint: HTTP server + MCP setup
│   ├── oracle.js          # Oracle connection pool management
│   ├── auth.js            # API key authentication middleware
│   ├── web.js             # Express app and routes
│   ├── mcpTransport.js    # HTTP transport wrapper for MCP
│   ├── logger.js          # Winston logger with file rotation
│   └── tools/
│       ├── runQuery.js     # Execute SQL queries
│       ├── listTables.js   # List database tables
│       ├── getSchema.js    # Get table schema
│       └── nl2sql.js       # Natural language to SQL
├── tests/
│   ├── integration.test.sh # Integration test script
│   └── lint-setup.md       # Linting setup guide
├── package.json
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

先决条件

Node.js 20+（用于本地开发）
Docker和Docker Compose（用于容器化部署）
Oracle数据库（可通过网络访问）
Oracle即时客户端（在Docker中自动处理）

快速开始

1.设置环境

# Copy environment file
cp .env.example .env

# Edit .env with your Oracle credentials
nano .env

所需的环境变量：

ORACLE_USER：Oracle数据库用户名
ORACLE_PASS：Oracle数据库密码
ORACLE_CONN：连接字符串（格式： host:port/service)
MCP_API_KEY：的API密钥 /mcp 端点身份验证（推荐）

2.使用Docker Compose运行

# Build and start all services
docker-compose up --build

# Run in detached mode
docker-compose up -d

# View logs
docker-compose logs -f mcp-oracle

3.本地运行（开发）

# Install dependencies
npm install

# Set environment variables (or use .env file)
export ORACLE_USER=your_user
export ORACLE_PASS=your_password
export ORACLE_CONN=host:1521/XEPDB1
export MCP_API_KEY=your_api_key

# Start the server
npm start

配置

环境变量

看 .env.example 对于所有可用的配置选项：

必修的：

ORACLE_USER：Oracle数据库用户名
ORACLE_PASS：Oracle数据库密码
ORACLE_CONN：Oracle连接字符串（格式： host:port/service)

推荐：

MCP_API_KEY：的API密钥 /mcp 端点（如果未设置，则允许在开发模式下进行未经身份验证的请求）

可选：

PORT：HTTP服务器端口（默认值： 3000)
NL2SQL_URL：NL2SQL服务的URL（默认值： http://nl2sql-service:8500/query)
LOG_LEVEL：日志记录级别（默认值： info)
CORS_ORIGIN：CORS原点（默认值： *)
MAX_REQUEST_SIZE：最大请求大小（默认值： 10mb)

Oracle连接池

通过环境变量配置池设置：

ORACLE_POOL_MIN：最小池大小（默认值： 2)
ORACLE_POOL_MAX：最大池大小（默认值： 10)
ORACLE_POOL_INCREMENT：池增量（默认值： 1)
ORACLE_POOL_TIMEOUT：池超时（秒）（默认值： 60)

API终点

MCP端点

发布 /mcp

主MCP协议端点。接受JSON-RPC 2.0请求。

身份验证：

头球 x-mcp-api-key: <your-api-key>
或者： Authorization: Bearer <your-api-key>

请求格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

响应格式：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...]
  }
}

健康与监测

获取 /health：基本健康检查
获取 /ready：准备状态检查（验证数据库池）
获取 /metrics：普罗米修斯格式的指标
发布 /webhook/telnyx：Telnyx webhook处理程序

MCP工具

1.runQuery

对Oracle数据库执行SQL查询。

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "runQuery",
    "arguments": {
      "sql": "SELECT * FROM employees WHERE department_id = :dept_id",
      "binds": { "dept_id": 10 },
      "maxRows": 100
    }
  }
}

答复：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"success\":true,\"data\":{\"rows\":[...],\"rowCount\":5}}"
    }]
  }
}

2.列表

列出数据库中的所有表。

请求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "listTables",
    "arguments": {
      "schema": "HR"
    }
  }
}

3. getSchema

获取表的详细架构信息。

请求：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "getSchema",
    "arguments": {
      "tableName": "employees",
      "schema": "HR"
    }
  }
}

4.nl2sql

将自然语言查询转换为SQL。

请求：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "nl2sql",
    "arguments": {
      "query": "Show me all customers from New York"
    }
  }
}

Telnyx配置

设置Telnyx AI代理

配置MCP URL：
- 在Telnyx AI代理设置中，将MCP URL设置为： https://<your-host>:<port>/mcp
- 例子： https://mcp.example.com:3000/mcp
配置API密钥：
- 在Telnyx AI代理MCP配置中，设置API密钥以匹配您的 MCP_API_KEY 环境变量
- 代理应发送带有标头的请求： x-mcp-api-key: <your-api-key>
Telnyx配置JSON示例：

{
  "mcp": {
    "url": "https://your-server.com:3000/mcp",
    "apiKey": "your-secure-api-key-here",
    "transport": "http"
  }
}

测试Telnyx集成

# Test MCP endpoint with API key
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "x-mcp-api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

curl命令示例

列出可用工具

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "x-mcp-api-key: changeme" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

执行查询

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "x-mcp-api-key: changeme" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "runQuery",
      "arguments": {
        "sql": "SELECT table_name FROM user_tables WHERE ROWNUM <= 5"
      }
    }
  }'

健康检查

curl http://localhost:3000/health

Telnyx Webhook

curl -X POST http://localhost:3000/webhook/telnyx \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "message.received",
    "data": {
      "from": "+1234567890",
      "to": "+0987654321",
      "text": "Hello"
    }
  }'

运行测试

集成测试

该项目包括一个bash集成测试脚本：

# Make script executable
chmod +x tests/integration.test.sh

# Run tests (defaults to http://localhost:3000)
./tests/integration.test.sh

# Run with custom URL and API key
BASE_URL=http://your-server:3000 MCP_API_KEY=your-key ./tests/integration.test.sh

测试脚本验证：

健康终点
准备就绪终点
指标端点
MCP身份验证
MCP工具/清单
MCP工具/调用（列表表）

Docker服务

mcp预言机

主MCP服务器容器：

在端口3000上运行HTTP服务器
在以下位置显示MCP端点 /mcp
装载日志目录
连接到Oracle数据库

nl2sql服务

用于自然语言到SQL转换的FastAPI服务：

包括占位符实现
在端口8500上显示API
替换为实际的NL2SQL服务 通过更新 image 在 docker-compose.yml

oracle数据库（可选）

用于测试的本地Oracle数据库：

用途 gvenzl/oracle-free 图像
暴露端口1521
数据保存在Docker卷中
默认情况下已注释掉 -取消注释 docker-compose.yml 如有需要

日志记录

日志将写入：

控制台：带时间戳的结构化JSON日志
文件：在中旋转日志文件 logs/ 目录
- 格式： mcp-oracle-YYYY-MM-DD.log
- 最大大小：每个文件20MB
- 保留期：14天

安全

API密钥验证

这 /mcp 端点需要API密钥身份验证：

集 MCP_API_KEY 环境变量
发送带有标头的请求： x-mcp-api-key: <key> 或 Authorization: Bearer <key>
如果 MCP_API_KEY 未设置，允许请求，但会记录警告（开发模式）

TLS/HTTPS

对于生产，启用TLS：

选项1：应用层TLS （不推荐）
- 集 TLS_CERT 和 TLS_KEY 环境变量
- 更新服务器代码以使用HTTPS
选项2：反向代理 （推荐）
- 使用nginx、traefik或类似工具
- 在代理端处理TLS终止
- 将请求转发到端口3000上的应用程序

请求限制

最大请求大小：10MB（可通过配置 MAX_REQUEST_SIZE)
请求超时：30秒（可通过配置 MCP_REQUEST_TIMEOUT)
CORS：可通过以下方式配置 CORS_ORIGIN

故障排除

Oracle连接问题

检查连接字符串格式: host:port/service
验证网络连接: telnet host 1521
检查Oracle即时客户端：确保它安装在Docker中
查看日志：检查 logs/ 详细错误消息目录

MCP端点问题

身份验证错误：验证 MCP_API_KEY 请求标头中的匹配项
超时错误：增加 MCP_REQUEST_TIMEOUT 如果查询速度慢
连接被拒绝：确保服务正在运行并且端口已暴露

NL2SQL服务问题

验证服务是否正在运行: curl http://nl2sql-service:8500/health
检查网络：确保服务在同一个Docker网络上
审核超时：默认值为30秒

设计说明/选择

本节记录了实施过程中做出的关键设计决策和权衡：

1.HTTP传输实现

决定：实现了自定义HTTP传输包装器，而不是使用SDK的STDIO传输。

依据:

MCP SDK(@modelcontextprotocol/sdk)主要支持STDIO传输
Telnyx和其他基于HTTP的客户端需要HTTP/JSON-RPC端点
创建了一个包装器，将JSON-RPC请求路由到MCP服务器的内部请求处理程序
这允许服务器与HTTP客户端一起工作，同时保持与MCP协议的兼容性

权衡:

需要手动将请求路由到处理程序
如果SDK将来添加本机HTTP传输，可能需要更新
优点：适用于Telnyx和任何HTTP客户端

2.API密钥认证模式

决定：通过标头进行简单的API密钥身份验证，具有开发模式回退。

依据:

Telnyx需要基于API密钥的身份验证
支持两者 x-mcp-api-key 标题和 Authorization: Bearer 为了灵活性
如果 MCP_API_KEY 未设置，允许请求但记录警告（对本地开发有用）
易于实施和理解

权衡:

不如JWT那样安全（过期），但足以进行API到API的通信
将来可以通过JWT支持进行增强（存根提供在 auth.js)

3.请求超时处理

决定：具有可配置值的30秒默认超时。

依据:

防止挂起请求消耗资源
SQL查询可能很慢，但在大多数情况下，30秒是合理的
可通过以下方式配置 MCP_REQUEST_TIMEOUT 适用于不同的用例
超时时返回正确的JSON-RPC错误响应

权衡:

可能会在非常大/复杂的查询中超时
用户可以增加超时时间或优化查询

4.流媒体支持

决定：实现了无流的请求-响应模式。

依据:

MCP SDK的流媒体是为STDIO设计的
HTTP请求响应更简单、更兼容
可以使用以下命令对大型结果集进行分页 maxRows 参数
如果需要，可以使用服务器发送事件（SSE）或WebSockets进行增强

权衡:

大型结果集必须分页
没有实时结果流
优点：实施更简单，兼容性更好

5.错误处理和响应格式

决定：所有错误都会返回符合JSON-RPC 2.0的响应，并带有正确的错误代码。

依据:

保持JSON-RPC 2.0协议合规性
提供结构化错误信息
工具错误被包装在MCP内容格式中
数据库错误被捕获并以JSON格式返回

权衡:

错误信息嵌套（JSON-RPC错误→ MCP内容→ 工具错误）
优点：协议合规性、结构化错误、更容易调试

许可证

麻省理工学院

贡献

欢迎投稿！请确保：

代码遵循现有样式
所有工具都返回一致的JSON响应
错误处理全面
日志记录是适当的
测试已更新

支持

对于问题和疑问：

检查登录 logs/ 目录
查看Docker撰写日志： docker-compose logs
验证环境变量
独立测试Oracle连接
运行集成测试： ./tests/integration.test.sh

使用说明

MCP Oracle服务器（HTTP传输）

特性

项目结构

先决条件

快速开始

1.设置环境

2.使用Docker Compose运行

3.本地运行（开发）

配置

环境变量

Oracle连接池

API终点

MCP端点

健康与监测

MCP工具

1.runQuery

2.列表

3. getSchema

4.nl2sql

Telnyx配置

设置Telnyx AI代理

测试Telnyx集成

curl命令示例

列出可用工具

执行查询

健康检查

Telnyx Webhook

运行测试

集成测试

Docker服务

mcp预言机

nl2sql服务

oracle数据库（可选）

日志记录

安全

API密钥验证

TLS/HTTPS

请求限制

故障排除

Oracle连接问题

MCP端点问题

NL2SQL服务问题

设计说明/选择

1.HTTP传输实现

2.API密钥认证模式

3.请求超时处理

4.流媒体支持

5.错误处理和响应格式

许可证

贡献

支持

相关 MCP

Oracle数据库MCP服务器

JSON-RPC服务

CLI工具MCP服务器

以太坊RPC MPC服务器

WinDbg调试服务器

PHP MCP服务器SDK