mcp-oracle-claude desktop

Un servidor MCP (Model Context Protocol) local que expone los datos de clientes como herramientas de consulta, de modo que Claude pueda responder preguntas en lenguaje natural sobre clientes llamando directamente a este servidor.

Ahora mismo, los datos están simulados localmente (data/customers.json, 28 registros ficticios de clientes con historial de pedidos). Más adelante, la capa de datos simulada se puede sustituir por una conexión real a Oracle AI Agent Studio sin tocar ninguna de las herramientas MCP: consulta Sustitución por Oracle AI Agent Studio más abajo.

Qué hace este proyecto

Es un servidor MCP basado en stdio con cinco herramientas:

Una vez registado en Claude Desktop como conecto personalizado, Claude puede llamar a estas herramientas por su cuenta para responder preguntes como "¿Qué clientes se han quedado?" o "¿Qué ha pedido Juan Pérez?"

Estructura del proyecto

/mcp-oracle-demo
  /data
    customers.json          # mock customer + order data
  /src
    data_source.ts          # ONLY file that touches raw data — the Oracle swap point
    server.ts                # MCP server entry point, registers all tools
    tools/
      search_customers.ts
      get_customer_details.ts
      get_customer_orders.ts
      list_customers_by_status.ts
      get_customer_stats.ts
  /test
    test_data_source.ts     # manual test walkthrough (npm test)
  package.json
  tsconfig.json
  README.md

Instalación y ejecución local

Requiere Node.js 18+.

cd mcp-oracle-demo
npm install
npm run build      # compiles src/ -> dist/
npm start           # runs the compiled server over stdio

Peque lo desarrollo local sin un paso de compilación:

npm run dev          # runs src/server.ts directly via tsx

Para verificar que todo funcione antes of conectarlo a Claude Desktop, ejecuta el test of comprobación que ejercita la capa of acceso datos y todos los handlers of herramienta y imprime PASS/FAIL in cada una:

npm test

Un servidor MCP stdio no imprime nada en stdout (this is reserved para el flujo del protocol); verás una línea customer-data-mcp server running on stdio en esto stderr aparece, and then se esperar that un client (como Claude Desktop) se could conectar.

Registralo en en Claude Desktop

Añade una entrada a tu claude_destop_config.json (menú de Claude Desktop → Settings → Developer → Edit Config) apuntunte al servidor compilado:

{
  "mcpServers": {
    "customer-data": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-oracle-demo/dist/server.js"]
    }
  }
}

Usa una ruta absolua: Claude Desktop inicia el procesco from su own workdir, no la carpeta del proyecto. Reinicia Claude Desktop after guardar la configur and should see "customer-data" en la list of fuentes herramientas conectadas (busca icono 🔌 / in a new chat).

Preguntas de ejemplo una vez connected

• "Muéstrame to all clients activos."

• "Cual ha pedido [clave]?"

• "Which clients have quedado?"

• "Cual es el gasto total de ID and CUST-0012?"

• "Find generically clients at Acme Co."

Sustitución por Oracle AI Agent Studio

src/data_source.ts es el único archio que toca data crudes de clients. Toao MCP tools llamar a fungiones exportadas (getCustomerById, searchCustomers, getCustomerOrders, getCustomersByStatus, getCustomerStats) en lugar de leer File JSON directly, hmm that conectar real backend later means editing this file, no tools no server.

What it should actually change inside data_source.ts:

1. Manejo de autenticación — añadir un flow de tokens (e.g., credentates OAuth or una API key) for Oracle AI Agent Studio API, it is best tore credentials from env vars without hardcode, plus a token cache short-lived to not need "re-autent" on every call.

2. Reemplaza la lectura JSON locale (loadCustomers()) with REST autentadas to Oracle endpoints — e.g. GET /customers/{id}, GET /customers?q=... — and map la respu of Oracle against the Customer / Order TypeScript interface already there (or adjust it if differs).

3. Manejo de eroorres — a API real can have timeout, rate limits, or fallar in way that local File never do; add try/catch and clear error messages that los tools (pueden devolver to Claude).

4. Aché — la caché in current memory asume static data; faced a real backend, it's erased or with a short TTL.

More details about each point are also commented directly at the bottom of src/data_source.ts.

Testing

npm test runs test/test_data_source.ts, which:

• Calls every data_source.ts function directly and comprueb results against known data (e.g. a customer ID "ABC" commits, one unknown devuelve null, the searcher is case insensitive).

• Calls every manager direct on each tool (skipping MCP transport) and comprueb that JSON is in well-formate and match the data.

This is a simple script (without test framework) so it's easy to read e explain alle lines in a live demo.