mcp-oracle 桌面版

一个本地 MCP（Model Context Protocol）服务器，将客户数据以可查询工具的形式暴露出来，让 Claude 可以通过直接调用此服务器来回答关于客户的自然语言问题。

目前数据在本机模拟（data/customers.json，28 条含订单历史的伪客户记录）。之后，可以把模拟数据层换成对 Oracle AI Agent Studio 的真实访问，而完全不用动 MCP 工具代码——见下文 替换接入 Oracle AI Agent Studio。

Project purpose

这是一个基于 stdio 的 MCP server，提供五个工具：

一旦在 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

安装与本地运行

Requires Node.js 18 或更高版本。

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

For 没有 build 步骤的本地开发：

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

在接入 Claude Desktop 之前，运行验证流程，其中综合测试数据访问层和每个“工具”的处理器，同时应为每项检查打印 PASS/FAIL：

npm test

A stdio MCP 服务器本身不会向 stdout 打印任何内容（stdout 是为协议 stream 保留的）——启动后你会看到 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，你应该在“已连接”的 tool source 列表中看到 “customer-data”（新聊天中的 🔌 / “tools” 图标）。

连接后可尝试的问题

• “显示所有 active 客户。”

• “[customer name] 订购了什么？”

• “哪些客户已流失？”

• “客户 CUST-0012 在我们这里总共消费了多少，平均订单金额是多少？”

• “找到 Acme Co. 的所有客户。”

Swapping in Oracle AI Agent Studio

src/data_source.ts 是唯一与原始客户数据接触的文件。每个 MCP 工具都调用其导出的（ getCustomerById, searchCustomers, getCustomerOrders, getCustomersByStatus, getCustomerStats）函数，而不是直接读取该 JSON 文件——因此以后切换到实际“后端时，只需修改这一个文件，而不需要改工具定义或服务器本身。

在 data_source.ts 中需要做哪些改动：

1. 认证处理 — 给 Oracle AI Agent Studio 的 API 增加 token 流程（例如 OAuth 客户端凭据或 API key）。最好从环境变量读取凭据，不要硬编码，再配一个短期的 token 缓存，免得每次调用都要重新认证。

2. 替换本地的 JSON read （loadCustomers()） 为对 Oracle 端点的已认证里 REST 调用——如 GET /customers/{id}、GET /customers/search?q=...、 GET /customers?status=...——并把 Oracle 的返回结构映射到文件内已经定义的类型Customer / Order TS 接口上（如果 Oracle schema 不同也可以调整）。

3. 错误处理 —— 真实 API 会 timeout、rate-limit 或以本地文件读取不会出现的方式失败，因此增加 try/catch 和清晰的错误消息，让工具可以反馈给后端给 Claude。

4. 缓存 —— 当前的内存缓存假设数据是静态的；连上真实后端后，要么移除这个缓存，要么设置短 TTL 。

上面每点的详细说明也直接注释在 src/data_source.ts 的文件底部。

测试

npm test 运行 test/test_data_source.ts，它会：

• 直接调用 data_source.ts 中每个函数，并对照 已知的 mock 数据特征来检查返回值（例如已知 customer IDing can resolve，未知 ID 返回 null，搜索不区分大小写）。

• 直接调用 每个工具的 handler 函数（绕过 MCP transport层），并检查返回的 JSON 是否是格式正确 且 与底层数据一致。

这是一个纯脚本（不依赖测试框架），因此在屏实际演示中很容易逐行阅读、讲解。