mcp-oracle-claude desktop

로컬 MCP(Model Context Protocol) 서버로, 고객 데이터를 쿼리 가능한 도구로 노출합니다. Claude는 이 서버를 직접 호출하여 고객에 대한 자연어 질문에 답할 수 있습니다.

현재 데이터는 로컬에서 목(mock) 처리되어 있습니다(data/customers.json, 주문 내역이 포함된 가짜 고객 레코드 28개). 나중에 목 데이터 계층은 MCP 도구 코드를 건드리지 않고 Oracle AI Agent Studio와의 실제 연결로 교체할 수 있습니다. 아래의 Oracle AI Agent Studio로 교체하기를 참조하세요.

이 프로젝트가 하는 일

stdio 기반 MCP 서버로서 다섯 가지 도구를 제공합니다:

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 메뉴 → 설정 → 개발자 → 구성 편집)에 항목을 추가하고 컴파일된 서버를 가리키게 하세요:

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

절대 경로를 사용하세요. Claude Desktop은 이 프로젝트 폴더가 아니라 자신의 작업 디렉터리에서 프로세스를 시작합니다. 설정을 저장한 후 Claude Desktop을 다시 시작하면 새 채팅에서 "customer-data"가 연결된 도구 소스로 표시될 것입니다(🔌 / 도구 아이콘을 찾아보세요).

연결 후 시도할 만한 예시 질문

• "모든 활성 고객을 보여 줘."

• "[고객 이름] 고객이 무엇을 주문했나요?"

• "이탈한 고객은 누구인가요?"

• "고객 CUST-0012가 우리에게 지출한 금액과 평균 주문 금액은 얼마인가요?"

• "Acme Co.의 고객을 찾아 줘."

Oracle AI Agent Studio로 교체하기

src/data_source.ts는 원시 고객 데이터를 다루는 유일한 파일입니다. 모든 MCP 도구는 JSON 파일을 직접 읽지 않고 이 파일이 내보내는 함수(getCustomerById, searchCustomers, getCustomerOrders, getCustomersByStatus, getCustomerStats)를 호출합니다. 따라서 이후 실제 백엔드에 연결할 때는 도구 정의나 서버가 아니라 이 파일 하나만 수정하면 됩니다.

data_source.ts 안에서 바뀌어야 할 것들:

1. 인증 처리 — Oracle AI Agent Studio API에 대한 토큰 흐름(예: OAuth 클라이언트 자격 증명 또는 API 키)을 추가합니다. 하드코딩하는 대신 환경 변수에서 자격 증명을 읽도록 하고, 호출마다 재인증하지 않도록 수명이 짧은 토큰 캐시를 사용합니다.

2. 로컬 JSON 읽기 대체 — loadCustomers()의 로컬 JSON 읽기를 Oracle 엔드포인트에 대한 인증된 REST 호출(예: GET /customers/{id}, GET /customers/search?q=..., GET /customers?status=...)로 대체하고, Oracle의 응답 형태를 이미 그 파일에 정의된 Customer / Order TypeScript 인터페이스에 매핑합니다(또는 Oracle 스키마가 다르면 인터페이스를 조정합니다).

3. 오류 처리 — 실제 API는 로컬 파일 읽기에서는 발생하지 않는 타임아웃, 속도 제한, 오류가 발생할 수 있습니다. 따라서 try/catch와 도구가 Claude에게 표시할 수 있는 명확한 오류 메시지를 추가하세요.

4. 캐싱 — 현재 인메모리 캐시는 정적 데이터를 전제로 합니다. 실제 백엔드를 대상으로 할 때는 캐시를 제거하거나 짧은 TLS을 부여해야 h요합니다.

이 각 항목에 대한 자세한 내용은 src/data_source.ts 맨 아래 주석에도 정리되어 있습니다.

테스트

npm test를 실행하는 test/test_data_source.ts는 다음과 같은 작업을 합니다:

• data_source.ts의 모든 함수를 직접 호출하여 그 결과를 목 데이터의 알려진 속성과 확인합니다 (예: 알려진 고객 ID는 정상으로 null을 반환하고, 알 수 없는 ID는 null을 반환하며, 검색은 대소문자를 구분하지 않습니다).

• 모든 도구 핸들러 함수를 MCP 전송을 거치지 않고 직접 호출하여, 반환된 JSON이 올바른 형식이고 기본 데이터와 일치하는지 확인합니다.

이 코드는 테스트 프레임워크가 없는 일반 스크립트이므로 화면 공유 demo에서 한 줄씩 읽고 설명하기 쉽습니다.