Oracle Lens MCP

Oracle Lens-MTG MCP服务器

Magic的模型上下文协议（MCP）服务器：收集预言卡搜索和收集管理。

特性

• Oracle卡搜索：使用类似Scryfall的语法搜索所有MTG卡
• 馆藏管理：搜索和管理您的个人MTG收藏
• 双数据集支持：加载Oracle卡（基于规则）和默认卡

（基于打印）来自Scryfall批量数据API

• 收款导入：从MTGGoldfish格式导入收藏（即将推出）

设置

1. 安装依赖项：

npm install

1. 设置PostgreSQL数据库：

创建一个PostgreSQL数据库（如果你没有）：

   createdb mtg

或使用 psql:

   CREATE DATABASE mtg;

1. 配置环境变量：

创建一个 .env 项目根目录中的文件：

   # PostgreSQL Database Connection
   DATABASE_URL=postgresql://localhost:5432/mtg

   # Optional: MCP Server Port (if not set, server runs in stdio mode)
   # MCP_PORT=3000

如果你的PostgreSQL需要身份验证：

   DATABASE_URL=postgresql://username:password@localhost:5432/mtg

1. 构建项目：

npm run build

1. 加载卡数据：

npm run load-data

这将从Scryfall下载并加载Oracle卡和默认卡（第一次运行需要几分钟）。

1. 运行服务器：

服务器支持两种传输模式：

标准模式（默认） -适用于Claude Desktop等MCP客户端：

npm start

HTTP模式 -要在网络端口上公开服务器：

MCP_PORT=3000 npm start

或者以开发模式运行：

npm run dev
# or for HTTP mode:
MCP_PORT=3000 npm run dev

用法

标准模式（默认）

Stdio模式设计用于通过标准通信的MCP客户端 输入/输出。这是默认模式，当 MCP_PORT 未设置。

使用案例：

• 克劳德桌面
• 生成进程的其他MCP客户端
• 本地开发和测试

正在运行：

npm start
# or
npm run dev

服务器将通过stdin/stdout进行通信。未暴露任何网络端口。

HTTP模式

HTTP模式使用MCP Streamable HTTP将服务器暴露为HTTP端点 协议。这允许远程客户端通过网络连接。

使用案例：

• 远程MCP客户端
• Web应用程序
• 微服务架构
• Docker容器
• 云部署

正在运行：

# Default port 3000
MCP_PORT=3000 npm start

# Custom port
MCP_PORT=8080 npm start

# Development mode
MCP_PORT=3000 npm run dev

端点： 服务器将在以下时间可用 http://localhost:PORT/mcp （例如。， http://localhost:3000/mcp)

正在连接到HTTP服务器：

HTTP服务器实现MCP流式HTTP协议：

1. 初始化会话 -向发送POST请求 /mcp 带着一个 initialize JSON-RPC消息：

   curl -X POST http://localhost:3000/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "initialize",
       "params": {
         "protocolVersion": "2024-11-05",
         "capabilities": {},
         "clientInfo": {
           "name": "example-client",
           "version": "1.0.0"
         }
       }
     }'

1. 会话ID -服务器将以 Mcp-Session-Id 头球在所有后续请求中包含此标头：

   curl -X POST http://localhost:3000/mcp \
     -H "Content-Type: application/json" \
     -H "Mcp-Session-Id: YOUR_SESSION_ID" \
     -d '{
       "jsonrpc": "2.0",
       "id": 2,
       "method": "tools/list"
     }'

1. SSE流 -对于流式响应，请连接到SSE端点：

   curl -N http://localhost:3000/mcp \
     -H "Mcp-Session-Id: YOUR_SESSION_ID"

1. 终止会话 -发送DELETE请求以关闭会话：

   curl -X DELETE http://localhost:3000/mcp \
     -H "Mcp-Session-Id: YOUR_SESSION_ID"

会话管理：

• 每个客户端连接都会获得一个唯一的会话ID
• 会话关闭时会自动清理
• 支持多个并发会话

数据库设置

服务器使用PostgreSQL和Drizzle ORM。你需要一个PostgreSQL数据库 正在运行（建议使用版本12或更高版本）。

数据库连接

数据库连接是通过配置的 DATABASE_URL 环境变量。 您可以在 .env 文件或作为环境变量：

DATABASE_URL=postgresql://[user[:password]@][host][:port][/database]

示例：

• 本地数据库： postgresql://localhost:5432/mtg
• 通过身份验证： postgresql://myuser:mypassword@localhost:5432/mtg
• 远程数据库： postgresql://user:pass@db.example.com:5432/mtg

数据库模式

数据库包含三个主要表：

• oracle_cards：每张Oracle卡一条记录（唯一规则对象）-用于

基于文本/规则的查询。包含约36k张卡。

• 默认卡片：每张卡片打印一条记录-用于设置特定和打印级别查询。

包含约110k张卡片打印。

• 库存：用户集合（oracle_id、数量、标签、位置）

表在第一次运行时通过Drizzle迁移自动创建。

荷载数据

要从Scryfall加载Oracle卡和默认卡，请执行以下操作：

npm run load-data

此脚本将：

1. 从Scryfall获取最新的Oracle卡批量数据元数据
2. 下载并加载Oracle卡（约160MB，约36k卡）
3. 从Scryfall获取最新的默认卡批量数据元数据
4. 下载并加载默认卡（~495MB，所有卡打印）
5. 如果再次运行，请删除并重新加载现有数据

注： 第一次运行需要几分钟的时间来下载和处理这两个文件 数据集。首先加载Oracle卡，因为默认卡通过引用它们 oracle_id.

生成迁移

如果在中修改架构 src/db/schema.ts，生成新的迁移：

# Generate migration files
npx drizzle-kit generate

# Apply migrations to database
npx drizzle-kit migrate

注： 服务器启动或运行时会自动应用迁移 npm run load-data.

MCP工具

oracle_search

使用类似Scryfall的语法搜索所有Oracle卡。

查询语法：

基本字段

• 名字: n: 或 name: -搜索卡片名称

- 例子： n:Lightning, name:Bolt

• 类型: t: 或 type: -按卡片类型搜索

- 例子： t:creature, t:enchantment, t:legendary

• Oracle文本: o: 或 oracle: -搜索oracle文本

- 例子： o:"draw a card", o:destroy （短语用引号括起来）

• 关键词: k:, kw:，或 keyword: -按关键字搜索能力

- 例子： k:haste, kw:flying, keyword:lifelink

颜色和颜色标识

• 颜色: c:, color:，或 colors: -按卡片颜色搜索

- 支持： c:red, c:R, c:WUBRG - 操作员： =, = （超集）， != （不相等） - 例子： c:red, c>=W, c=, `, != - 特殊值： cmc:even, cmc:odd - 例子： cmc:3, cmc=5, cmc:even`

• 魔法力费用: m: 或 mana: -按实际法力消耗字符串搜索

- 例子： m:{R}{R}, mana:2WW, m:{G}{U}

力量和韧性

• 力量: pow: 或 power: -按生物力量搜索

- 操作员： =, =, `, != - 例子： pow:4, pow>=3, powertou 或 pow>toughness -寻找力量>韧性的生物 - 注意：仅比较数值（卡片 *, ?`等除外）

• 韧性: tou: 或 toughness: -按生物韧性搜索

- 操作员： =, =, `, != - 例子： tou:5, toughness>=4, tou=4", "limit": 10 }

{ "query": "id:esper t:instant cmc:even", "limit": 20 }

{ "query": "m:{R}{R} cmc=4", "limit": 10 }

{ "query": "ci:wbg pow>tou", "limit": 10 }

### `collection_search`

语法与 `oracle_search`，但只退还您收藏的卡片。

### `import_collection`

从MTGGoldfish格式导入收藏（即将推出）。

## 资源

- `mcp://mtg/schema/oracle_cards` -oracle_cards表的模式文档
- `mcp://mtg/collection/summary` -收款汇总

## 配置

### 环境变量

|变量|描述|默认值|
| -------------- | ----------------------------------------------------------------- | --------------------------------- |
| `MCP_PORT` |HTTP模式的端口号。如果未设置，服务器将以stdio模式运行。|（无-stdio）|
| `DATABASE_URL` |PostgreSQL连接字符串| `postgresql://localhost:5432/mtg` |

### 运输方式选择

服务器根据以下内容自动选择传输 `MCP_PORT`
环境变量：

- **标准模式** （默认）：在以下情况下使用 `MCP_PORT` 未设置。通过以下方式进行沟通
  stdin/stdout，适用于Claude Desktop等MCP客户端。
- **HTTP模式**：在以下情况下使用 `MCP_PORT` 已设置。显示指定服务器上的服务器
  使用MCP Streamable HTTP协议的端口。

**示例：**

Stdio mode (default)

npm start

HTTP mode on port 3000

MCP_PORT=3000 npm start

HTTP mode on custom port

MCP_PORT=8080 npm start

Custom database URL

DATABASE_URL=postgresql://user:password@localhost:5432/mtg npm start

Combine options

MCP_PORT=3000 DATABASE_URL=postgresql://user:password@localhost:5432/mtg npm start

## 连接MCP客户端

### 克劳德桌面

Claude Desktop使用stdio模式。添加到您的 `claude_desktop_config.json`:

**macOS：**

{ "mcpServers": { "oracle-lens": { "command": "node", "args": ["/absolute/path/to/oracle-lens/build/index.js"] } } }

**窗户：**

{ "mcpServers": { "oracle-lens": { "command": "node", "args": ["C:\\absolute\\path\\to\\oracle-lens\\build\\index.js"] } } }

**Linux：**

{ "mcpServers": { "oracle-lens": { "command": "node", "args": ["/absolute/path/to/oracle-lens/build/index.js"] } } }

### 其他MCP客户端（HTTP模式）

对于支持HTTP传输的客户端，请将其配置为连接到您的HTTP服务器：

{ "mcpServers": { "oracle-lens": { "url": "http://localhost:3000/mcp" } } }

确保服务器在HTTP模式下运行：

MCP_PORT=3000 npm start

## 项目状态

- \[x\] 实施Scryfall Oracle批量数据导入器
- \[x\] 实现Scryfall默认批量数据导入器
- \[x\] 使用类似Scryfall的语法进行基本搜索
- \[x\] 支持类型、颜色、颜色标识、CMC、关键字和oracle文本过滤器
- \[x\] 颜色名称映射（红色→R、 蓝色→U、 等等）
- \[x\] 支持法力消耗查询(`m:`, `mana:`)
- \[x\] 支持格式合法性查询(`f:`, `format:`, `banned:`, `restricted:`)
- \[x\] 支持公会/分片/楔形颜色名称（azorius、esper等）
- \[x\] 支持复杂的查询逻辑（AND、OR、NOT、括号）
- \[x\] 支持CMC偶数/奇数和其他运算符(`!=`)
- \[x\] 支持功率/韧性查询（数字比较和 `pow>tou`)
- \[x\] 具有会话管理的HTTP传输模式
- \[x\] 本地MCP客户端的标准传输模式
- \[\]实施MTG金鱼采集进口商
- \[\]添加 `suggest_additions` 工具
- \[\]添加集合摘要资源实现
- \[\]添加工具，按集合、收集器编号等搜索默认卡（打印）。
- \[\]添加对稀有性查询的支持（需要默认卡数据）

## 故障排除

### 搜索返回空结果

- 确保您已加载数据： `npm run load-data`
- 检查滤色器是否使用正确的格式： `c:red` 或 `c:R` （不是 `c:Red`)
- 关键字不区分大小写： `k:haste` 工作原理与 `k:Haste`

### 数据库连接错误

- **“连接被拒绝”**：确保PostgreSQL正在运行：

# macOS (Homebrew) brew services start postgresql

# Linux (systemd) sudo systemctl start postgresql

# Or check if it's running pg_isready

- **“数据库不存在”**：创建数据库：

createdb mtg

- **“身份验证失败”**：检查您的 `DATABASE_URL` 包含正确的用户名和密码：

DATABASE_URL=postgresql://username:password@localhost:5432/mtg

- **迁移错误**：如果您看到迁移语法错误，则可能是旧的SQLite迁移。删除
  `db/migrations/` 并再生：

rm -rf db/migrations/* npx drizzle-kit generate

### 空搜索结果

- 确保您已加载数据： `npm run load-data`
- 检查滤色器是否使用正确的格式： `c:red` 或 `c:R` （不是 `c:Red`)
- 关键字不区分大小写： `k:haste` 工作原理与 `k:Haste`
- 验证您的数据库是否有数据： `psql mtg -c "SELECT COUNT(*) FROM oracle_cards;"`
- 功率/韧性查询仅匹配数值（带有 `*`, `?`等除外）

### HTTP 400错误请求错误

- 确保服务器正在运行： `MCP_PORT=3000 npm start`
- 检查您是否将请求发送到正确的端点： `http://localhost:3000/mcp`
- 对于HTTP模式，请确保发送 `initialize` 首先请求创建会话
- 服务器将自动为不存在会话ID的工具调用创建会话（在服务器重新启动后有用）