使用说明

Oracle Lens-MTG MCP服务器

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

特性

Oracle卡搜索：使用类似Scryfall的语法搜索所有MTG卡
馆藏管理：搜索和管理您的个人MTG收藏
双数据集支持：加载Oracle卡（基于规则）和默认卡（基于打印）来自Scryfall批量数据API
收款导入：从MTGGoldfish格式导入收藏（即将推出）

设置

安装依赖项：

npm install

设置PostgreSQL数据库：

创建一个PostgreSQL数据库（如果你没有）：
```
createdb mtg
```
或使用 psql:
```
CREATE DATABASE mtg;
```

配置环境变量：

创建一个 .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

构建项目：

npm run build

加载卡数据：

npm run load-data

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

运行服务器：

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

标准模式（默认） -适用于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协议：

初始化会话 -向发送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"
      }
    }
  }'

会话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"
  }'

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

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

终止会话 -发送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

此脚本将：

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

注：第一次运行需要几分钟的时间来下载和处理这两个文件数据集。首先加载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<=WUG
颜色标识: ci:, id:, identity:，或 color_identity: -按颜色标识搜索
- 语法与颜色相同
- 例子： ci:WUG, id:esper, identity<=azorius
命名颜色组合 （公会、碎片、楔形物等）：
- 行业协会： azorius, dimir, rakdos, gruul, selesnya, orzhov, izzet, golgari, boros, simic
- 碎片： bant, esper, grixis, jund, naya
- 楔子： abzan, jeskai, sultai, mardu, temur
- 四色： chaos, aggression, altruism, growth, artifice
- 学院： quandrix, silverquill, witherbloom, prismari, lorehold
- 例子： c:esper, ci<=azorius, id:bant
特殊价值观: c:colorless 或 c:c 对于无色， c:multicolor 或 c:m 用于多色

马纳成本

总法术力费用: cmc:, mv:，或 manavalue: -按法力值搜索
- 操作员： =, <=, >=, <, >, !=
- 特殊值： cmc:even, cmc:odd
- 例子： cmc:3, cmc<=2, mv>=5, cmc:even
魔法力费用: m: 或 mana: -按实际法力消耗字符串搜索
- 例子： m:{R}{R}, mana:2WW, m:{G}{U}

力量和韧性

力量: pow: 或 power: -按生物力量搜索
- 操作员： =, <=, >=, <, >, !=
- 例子： pow:4, pow>=3, power<=2
- 特别： pow>tou 或 pow>toughness -寻找力量>韧性的生物
- 注意：仅比较数值（卡片 *, ?等除外）
韧性: tou: 或 toughness: -按生物韧性搜索
- 操作员： =, <=, >=, <, >, !=
- 例子： tou:5, toughness>=4, tou<=3
- 注意：仅比较数值（卡片 *, ?等除外）

格式合法性

格式: f: 或 format: -查找格式合法的卡片
- 例子： f:modern, f:commander, f:standard
禁止: banned: -查找以某种格式禁止的卡片
- 例子： banned:legacy, banned:modern
受限的: restricted: -查找格式受限的卡片
- 例子： restricted:vintage

逻辑运算符

与（隐式）：空格分隔的项加在一起
- 例子： t:creature c:red k:haste
或（显式）：使用 OR 关键词
- 例子： t:creature OR t:enchantment
非（前缀）：使用 - 前缀
- 例子： -t:land, t:creature -c:blue
括号：组条件
- 例子： (t:creature OR t:enchantment) c:red
纯文本：如果未指定字段，则搜索名称和oracle文本
- 例子： Lightning 匹配名称或文本中带有“闪电”的卡片

复杂查询示例：

{
  "query": "t:enchantment ci:WUG",
  "limit": 10
}

{
  "query": "t:creature c:red k:haste cmc<=3",
  "limit": 20
}

{
  "query": "(t:instant OR t:sorcery) c:blue o:counter",
  "limit": 15
}

{
  "query": "f:modern -banned:modern cmc>=4",
  "limit": 10
}

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

{
  "query": "m:{R}{R} cmc<=4 t:creature",
  "limit": 15
}

{
  "query": "ci:wbg pow>=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的工具调用创建会话（在服务器重新启动后有用）