mcp-oracle-claude desktop

Локальный MCP-сервер (Model Context Protocol), который предоставляет данные о клиентах в виде инструментов, доступных для запросов, чтобы Claude мог отвечать на естественные вопросы о клиентах, напрямую вызывая этот сервер.

Сейчас данные замоканы локально (data/customers.json, 28 вымышленных записей клиентов с историей заказов). Позже этот слой мок-данных можно заменить на реальное подключение к Oracle AI Agent Studio, не трогая код MCP-инструментов — см. Замена на Oracle AI Agent Studio ниже.

Что делает этот проект

Это MCP-сервер на базе stdio с пятью инструментами:

После регистрации в Claude Desktop в качестве пользовательского коннектора Claude сможет сам вызывать эти инструменты и отвечать на вопросы вроде «какие клиенты ушли?» или «что заказывал John Smith?».

Структура проекта

/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

Установка и локальный запуск

Требуется Node.js 18+.

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

Для локальной разработки без шага сборки:

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

Чтобы убедиться, что всё работает, прежде чем подключать сервер к Claude Desktop, запустите тестовый прогон: он проходит по слою доступа к данным и всем обработчикам инструментов и печатает PASS/FAIL для каждой проверки:

npm test

stdio MCP-сервер сам ничего не выводит в stdout (stdout зарезервирован под поток протокола) — при запуске в stderr вы увидите строку customer-data-mcp server running on stdio, после чего сервер будет ждать подключения клиента (например, Claude Desktop).

Регистрация в Claude Desktop

Добавьте запись в claude_desktop_config.json (меню Claude Desktop → Settings → Developer → Edit Config), указав на скомпилированный сервер:

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

Используйте абсолютный путь — Claude Desktop запускает процесс из собственной рабочей директории, а не из папки этого проекта. После сохранения конфига перезапустите Claude Desktop, и в списке подключённых источников инструментов должен появиться «customer-data» (ищите значок 🔌 / tools в новом чате).

Примеры вопросов после подключения

• «Покажи всех активных клиентов.»

• «Что заказывал [имя клиента]?»

• «Какие клиенты ушли?»

• «Сколько потратил клиент CUST-0012 и какова его средняя стоимость заказа?»

• «Найди клиентов в компании Acme Co.»

Замена на Oracle AI Agent Studio

src/data_source.ts — единственный файл, который имеет дело с исходными данными клиентов. Каждый MCP-инструмент вызывает его экспортируемые функции (getCustomerById, searchCustomers, getCustomerOrders, getCustomersByStatus, getCustomerStats), а не читает JSON-файл напрямую, — так что для подключения настоящего бэкенда достаточно изменить этот один файл, не а определения инструментов или сервер.

Что потребуется изменить внутри data_source.ts:

1. Обработка аутентификации — добавить потрибление токена (например, OAuth client credentials или API-ключ) для API Oracle AI Agent Studio; логично читать учётные данные из переменных окружения, а не задерживать жёстко, и держать кэш токена с коротким временем жизни, чтобы не проходить аутентификацию на каждый способ.

2. Замена локального чтения JSON (loadCustomers()) на аутентифицированные REST-запросы в эндпоинтам Oracle — например, GET /customers/{id}, GET /customers/search?q=..., GET /customers?status=..., — и приведение ответа Oracle к интерфейсам TypeScript Customer / Order, уже определённым в этом файле (или поправка интерфейсов, если схема Oracle отличается).

3. Обработка ошибок — реальный API может, не отвечая, не rate-limit или завершиться ошибкой так, как локальное чтение файла никогда не падает; поэтому добавьте try/catch и понятные сообщения, которые инструменты смогут передать обратно в Claude.

4. Кэш — текущий кэш в памяти предполагает статичные данные; при живом бэкенде его следует либо полностью исключить, либо задать короткий TTL.

Подробности каждого из пунктов также закомментированы в самом конце src/data_source.ts.

Тестирование

npm test запускает test/test_data_source.ts, который:

• Напрямую вызывает каждую функцию из data_source.ts и сверяет результат против известных свойств мок-данных (например-known, известный ID клиента находится, неизвестный возвращает null, поиск works insensitive to case);

• напрямую вызывает handle каждого инструмента (в обход MCP-транспорта) и проверяет, что возвращаемый JSON корректен и соответствует эти данным.

Это простой скрипт без тестового фреймворка, и его легко читать и объяснять построчно в демонстрации с трансляцией экрана.