内容
# Scryfall MCP Server
[](https://opensource.org/licenses/Apache-2.0)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://www.npmjs.com/package/@kaminaduck/scryfall-mcp-server)
[](https://github.com/kaminaduck/scryfall-mcp)
一个模型上下文协议（Model Context Protocol，MCP）服务器，提供对Scryfall API的访问，以获取《万智牌》（Magic: The Gathering）卡片数据。该服务器使AI助手和其他MCP客户端能够搜索卡片、检索卡片信息、下载高分辨率图像，并通过标准化接口访问全面的MTG数据。
## Claude Desktop 快速设置
### 选项 1：NPM 包（推荐 - 适用于所有平台）
1. **全局安装**：
```bash
# Linux/macOS/Windows
npm install -g @kaminaduck/scryfall-mcp-server
```
2. **添加到 Claude Desktop 设置** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"scryfall-server": {
"command": "scryfall-mcp-server",
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
3. **重启 Claude Desktop** - 现在服务器应该可以使用了！
### 选项 2：从源代码
1. **克隆并构建**：
```bash
git clone https://github.com/kaminaduck/scryfall-mcp.git
cd scryfall-mcp
npm install && npm run build
```
2. **添加到 Claude Desktop 设置** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"scryfall-server": {
"command": "node",
"args": ["/full/path/to/scryfall-mcp/dist/index.js"],
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
3. **重启 Claude Desktop** - 服务器现在应该可用！
## 功能
- **卡片搜索**：使用 Scryfall 强大的搜索语法搜索 Magic: The Gathering 卡片
- **卡片详情**：获取特定卡片的详细信息，包括价格、合法性和元数据
- **图像下载**：下载高分辨率的卡片图像和艺术剪裁
- **数据库操作**：管理本地卡片数据库并进行完整性验证
- **套牌信息**：访问有关 MTG 套牌和扩展的信息
- **艺术作品访问**：获取高质量的卡片艺术作品和多种格式的图像
- **高级过滤**：使用 Scryfall 的高级搜索运算符进行精确查询
## 安装
### 选项 1：NPM 包（推荐）
从 npm 安装该包：
```bash
npm install -g @kaminaduck/scryfall-mcp-server
```
或者直接使用 npx 运行：
```bash
npx @kaminaduck/scryfall-mcp-server
```
### 选项 2：从源代码安装
```bash
git clone https://github.com/kaminaduck/scryfall-mcp.git
cd scryfall-mcp
npm install
npm run build
```
**重要**：构建过程会在 `dist/index.js` 创建一个可执行的二进制文件，并自动设置执行权限。
## 快速开始
### 运行服务器
如果全局安装：
```bash
scryfall-mcp-server
```
使用 npx（无需安装）：
```bash
npx @kaminaduck/scryfall-mcp-server
```
从源代码运行（构建后）：
```bash
./dist/index.js
```
# 或者
node dist/index.js
```
用于开发：
```bash
npm run dev
```
### 基本用法
服务器提供了多个工具，供MCP客户端使用：
#### 搜索卡牌
```javascript
// 搜索闪电箭卡牌
const result = await mcpSearchCards("lightning bolt");
// 搜索法力值转换为3的红色生物
const result = await mcpSearchCards("t:creature c:red cmc:3");
// 搜索特定扩展包中的卡牌
const result = await mcpSearchCards("set:znr");
```
#### 下载卡片图像
```javascript
// 下载特定的卡片图像
const result = await mcpDownloadCard("Lightning Bolt");
// 从特定的系列下载
const result = await mcpDownloadCard("Lightning Bolt", "m10", "146");
// 强制重新下载
const result = await mcpDownloadCard("Lightning Bolt", undefined, undefined, true);
```
#### 下载艺术裁剪
```javascript
// 下载卡片的艺术裁剪
const result = await mcpDownloadArtCrop("Lightning Bolt");
// 从特定印刷中下载艺术裁剪
const result = await mcpDownloadArtCrop("Lightning Bolt", "m10", "146");
```
## 可用工具
### 搜索工具
- **`mcp_search_cards(query)`**: 使用 Scryfall 语法搜索卡片
- **`mcp_get_card_artwork(card_id)`**: 获取特定卡片的艺术作品 URL
### 下载工具
- **`mcp_download_card(card_name, set_code?, collector_number?, force_download?)`**: 下载高分辨率卡片图像
- 返回: `filepath`，用于访问下载图像的 `resource_uri`
- **`mcp_download_art_crop(card_name, set_code?, collector_number?, force_download?)`**: 下载艺术裁剪图像
- 返回: `filepath`，图像的 `resource_uri`，JSON 数据的 `metadata_uri`
### 数据库工具
- **`mcp_verify_database()`**: 验证数据库完整性
- **`mcp_scan_directory(directory, update_db?)`**: 扫描目录中的图像文件
- **`mcp_clean_database(execute?)`**: 清理数据库中缺失的文件引用
- **`mcp_database_report()`**: 生成全面的数据库报告
## 可用资源
### 卡片资源
- **`resource://card/{card_id}`**: 通过 Scryfall ID 获取详细的卡片信息
- **`resource://card/name/{card_name}`**: 通过名称获取详细的卡片信息
- **`resource://random_card`**: 获取一张随机的《万智牌》卡片
### 下载资源 (新)
- **`resource://download/card/{file_id}`**: 访问下载的卡片图像
- **`resource://download/art/{file_id}`**: 访问下载的艺术裁剪图像
- **`resource://download/metadata/{file_id}`**: 访问下载卡片的JSON元数据
### 数据库资源
- **`resource://database/stats`**: 获取数据库统计信息和相关信息
## 搜索语法
服务器支持 Scryfall 强大的搜索语法。以下是一些示例：
| 查询 | 描述 |
|-------|-------------|
| `lightning bolt` | 名称中包含 "lightning bolt" 的卡牌 |
| `t:creature` | 所有生物卡牌 |
| `c:red` | 所有红色卡牌 |
| `cmc:3` | 转换法力费用为 3 的卡牌 |
| `set:znr` | 来自 Zendikar Rising 的卡牌 |
| `r:mythic` | 神话稀有卡牌 |
| `pow>=4` | 力量为 4 或更大的生物 |
| `o:"draw a card"` | 规则文本中包含 "draw a card" 的卡牌 |
| `is:commander` | 可以作为指挥官的卡牌 |
| `year:2023` | 2023 年印刷的卡牌 |
<details>
<summary>高级搜索示例</summary>
```javascript
// 查找来自最近系列的所有力量为 4 或更大的红色生物
await mcpSearchCards("t:creature c:red pow>=4 year>=2020");
// 查找所有费用为 3 法力的计划者
await mcpSearchCards("t:planeswalker cmc:3");
// 查找所有同时具有 "飞行" 和 "警觉" 的卡牌
await mcpSearchCards("o:flying o:vigilance");
// 查找所有可以作为指挥官的传奇生物
await mcpSearchCards("t:legendary t:creature is:commander");
// 查找所有由特定艺术家插画的卡牌
await mcpSearchCards("a:\"Rebecca Guay\"");
```
</details>
## 配置
### 文件存储
服务器根据执行环境调整其存储位置：
**MCP模式**（作为MCP服务器运行时）：
- 使用系统临时目录或XDG缓存目录
- 默认：`/tmp/scryfall_downloads/` 或 `$XDG_CACHE_HOME/scryfall_mcp/`
- 可通过 `SCRYFALL_DATA_DIR` 环境变量进行配置
**独立模式**（直接运行脚本时）：
- 使用传统的主目录存储
- 卡片图像：`.local/scryfall_card_images/`
- 艺术裁剪：`.local/scryfall_images/`
- 数据库：`.local/scryfall_database.db`
### 环境变量
- **`SCRYFALL_DATA_DIR`**: 覆盖默认存储目录
- **`MCP_ENABLE_FILE_DOWNLOADS`**: 在MCP模式下启用文件下载功能
### Claude Desktop 配置
要将此 MCP Server 与 Claude Desktop 一起使用，请将以下内容添加到您的 Claude Desktop 设置文件中。
#### 选项 1：全局 NPM 安装（推荐）
如果您使用 `npm install -g @kaminaduck/scryfall-mcp-server` 全局安装了该包：
```json
{
"mcpServers": {
"scryfall-server": {
"command": "scryfall-mcp-server",
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
#### 选项 2：使用 NPX（无需安装）
**⚠️ Windows 用户：** NPX 可能在 Claude Desktop 中存在环境变量扩展问题。如果遇到错误，请改用选项 1（全局安装）或选项 2b（Windows 包装器）。
```json
{
"mcpServers": {
"scryfall-server": {
"command": "npx",
"args": ["@kaminaduck/scryfall-mcp-server"],
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
#### 选项 2b：使用 Windows Wrapper（推荐用于 Windows）
对于在 NPX 中遇到环境变量问题的 Windows 用户：
```json
{
"mcpServers": {
"scryfall-server": {
"command": "scryfall-mcp-server-windows",
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
首先全局安装该包以获取 wrapper：
```cmd
npm install -g @kaminaduck/scryfall-mcp-server
```
#### 选项 3：从源代码构建 (Node.js)
如果您是从源代码构建的，请使用构建项目的绝对路径：
```json
{
"mcpServers": {
"scryfall-server": {
"command": "node",
"args": ["/full/path/to/scryfall-mcp/dist/index.js"],
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
#### 选项 4：来自源（直接二进制）
```json
{
"mcpServers": {
"scryfall-server": {
"command": "/full/path/to/scryfall-mcp/dist/index.js",
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
**重要**：对于源选项，请将 `/full/path/to/scryfall-mcp` 替换为您克隆的仓库的实际路径。
#### Claude桌面设置文件位置
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`
## 错误处理
所有工具返回带有状态指示的结构化响应：
```typescript
interface ToolResponse {
status: "success" | "error";
message?: string;
// 额外的响应数据因工具而异
[key: string]: any;
}
```
## 故障排除
### 常见的 Claude 桌面问题
#### "服务器传输意外关闭"
此错误通常发生在以下情况：
1. **二进制文件不可执行**：确保二进制文件具有执行权限：
```bash
chmod +x dist/index.js
```
2. **配置中的路径不正确**：验证您的Claude Desktop设置中的路径指向正确的位置：
```bash
# 检查文件是否存在且可执行
ls -la /full/path/to/scryfall-mcp/dist/index.js
```
3. **缺少Node.js**：如果使用直接二进制选项，请确保shebang行能够找到Node.js：
```bash
which node
# 应返回类似 /usr/bin/node 或 /usr/local/bin/node 的路径
```
#### Windows特定问题
**使用NPX时的环境变量扩展错误**
如果您看到类似以下的错误：
```
npm error path C:\Users\Username\AppData\Local\AnthropicClaude\app-0.11.6\${APPDATA}
npm error enoent ENOENT: no such file or directory, lstat '...\${APPDATA}'
```
这是因为Claude Desktop在Windows上使用npx时扩展环境变量存在问题。**解决方案按优先级排序：**
**解决方案1：使用全局安装（推荐用于Windows）**
```json
{
"mcpServers": {
"scryfall-server": {
"command": "scryfall-mcp-server",
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
首先全局安装：
```cmd
npm install -g @kaminaduck/scryfall-mcp-server
```
**解决方案2：使用带全局包路径的Node.js**
```json
{
"mcpServers": {
"scryfall-server": {
"command": "node",
"args": ["%APPDATA%\\npm\\node_modules\\@kaminaduck\\scryfall-mcp-server\\dist\\index.js"],
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
注意：如果环境变量扩展不起作用，请将`%APPDATA%`替换为您的实际AppData路径（通常是`C:\\Users\\Username\\AppData\\Roaming`）。
**解决方案3：使用完整路径的NPX**
```json
{
"mcpServers": {
"scryfall-server": {
"command": "C:\\Program Files\\nodejs\\npx.cmd",
"args": ["@kaminaduck/scryfall-mcp-server"],
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
**解决方案4：使用PowerShell包装器**
```json
{
"mcpServers": {
"scryfall-server": {
"command": "powershell",
"args": ["-Command", "npx @kaminaduck/scryfall-mcp-server"],
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
#### "命令未找到"或"权限被拒绝"
1. **对于 NPM 安装**：确保包已正确安装：
```bash
npm install -g @kaminaduck/scryfall-mcp-server
which scryfall-mcp-server
```
2. **对于 NPX 使用**：尝试使用完整的包名：
```json
{
"command": "npx",
"args": ["@kaminaduck/scryfall-mcp-server"]
}
```
3. **对于源代码构建**：使用完整的绝对路径并验证二进制文件是否存在：
```bash
ls -la /full/path/to/scryfall-mcp/dist/index.js
```
4. **尝试使用 Node.js 选项**，而不是直接执行二进制文件：
```json
{
"command": "node",
"args": ["/full/path/to/scryfall-mcp/dist/index.js"]
}
```
#### "模块未找到" 错误
1. **确保所有依赖项已安装**：
```bash
cd /path/to/scryfall-mcp
npm install
```
2. **如果您拉取了新的更改，请重建项目**：
```bash
npm run build
chmod +x dist/index.js
```
#### 循环依赖问题
如果您遇到与循环依赖相关的 npm 解析错误：
1. **检查 package.json 中的自引用**：
- 包不应依赖于自身
- 从依赖项中移除类似 `"@kaminaduck/scryfall-mcp-server": "^1.0.x"` 的条目
2. **清除 npm 缓存并重新安装**：
```bash
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```
3. **使用全新的 npm 安装**：
```bash
npm uninstall -g @kaminaduck/scryfall-mcp-server
npm install -g @kaminaduck/scryfall-mcp-server
```
#### 增强的 ENOENT 错误故障排除
如果您看到详细的 ENOENT 错误，且环境变量未解析：
**错误模式：**
```
npm error path C:\Users\Username\AppData\Local\AnthropicClaude\app-0.11.6\${APPDATA}
npm error errno -4058
npm error enoent ENOENT: no such file or directory, lstat '...\${APPDATA}'
```
**根本原因：** 在 Windows 上，Claude Desktop 在使用 npx 时未正确扩展环境变量。
**解决方案：**
1. **使用全局安装而不是 npx**（最可靠）：
```cmd
npm install -g @kaminaduck/scryfall-mcp-server
```
然后使用以下 Claude Desktop 配置：
```json
{
"mcpServers": {
"scryfall-server": {
"command": "scryfall-mcp-server",
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
2. **在 Claude Desktop 配置中设置显式环境变量：**
```json
{
"mcpServers": {
"scryfall-server": {
"command": "scryfall-mcp-server",
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true",
"SCRYFALL_DATA_DIR": "C:\\Users\\%USERNAME%\\Documents\\scryfall_data"
}
}
}
}
```
将 `%USERNAME%` 替换为您的实际 Windows 用户名。
3. **使用 PowerShell 包装器** 来处理环境变量扩展：
```json
{
"mcpServers": {
"scryfall-server": {
"command": "powershell",
"args": ["-Command", "npx @kaminaduck/scryfall-mcp-server"],
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
}
}
```
#### Windows目录权限和APPDATA问题
**在Windows上设置正确的目录权限：**
1. **检查常见路径的目录权限：**
```cmd
icacls "%APPDATA%" /T /C
icacls "%LOCALAPPDATA%" /T /C
icacls "%USERPROFILE%\Documents" /T /C
```
2. **如有需要，授予用户帐户完全权限：**
```cmd
icacls "%APPDATA%\scryfall_mcp" /grant "%USERNAME%:F" /T
```
3. **如果自动创建失败，手动创建目录：**
```cmd
mkdir "%APPDATA%\scryfall_mcp"
mkdir "%USERPROFILE%\Documents\scryfall_data"
```
**处理APPDATA路径问题：**
1. **验证APPDATA环境变量：**
```cmd
echo %APPDATA%
echo %LOCALAPPDATA%
echo %USERPROFILE%
```
这些命令应返回实际路径，而不是`${APPDATA}`字面量。
2. **如果环境变量失败，手动配置路径：**
```json
{
"mcpServers": {
"scryfall-server": {
"command": "scryfall-mcp-server",
"env": {
"MCP_SERVER_NAME": "scryfall-server",
"MCP_ENABLE_FILE_DOWNLOADS": "true",
"SCRYFALL_DATA_DIR": "C:\\Users\\[YourUsername]\\AppData\\Roaming\\scryfall_mcp"
}
}
}
}
```
将`[YourUsername]`替换为您的实际Windows用户名。
3. **Windows的替代存储位置：**
```json
{
"env": {
"SCRYFALL_DATA_DIR": "C:\\ProgramData\\scryfall_mcp"
}
}
```
或使用文档文件夹：
```json
{
"env": {
"SCRYFALL_DATA_DIR": "C:\\Users\\[YourUsername]\\Documents\\scryfall_data"
}
}
```
**Windows特定的防病毒考虑：**
- 一些防病毒软件可能会阻止npm包的执行
- 添加以下路径的排除项：
- `%APPDATA%\npm\`
- `%LOCALAPPDATA%\npm\`
- 您的Node.js安装目录
- Claude桌面应用程序目录
#### "存储目录" 错误
1. **在你的 Claude Desktop 配置中设置自定义存储目录**：
```json
{
"env": {
"SCRYFALL_DATA_DIR": "/tmp/scryfall_downloads",
"MCP_ENABLE_FILE_DOWNLOADS": "true"
}
}
```
2. **确保目录可写**：
```bash
mkdir -p /tmp/scryfall_downloads
chmod 755 /tmp/scryfall_downloads
```
## Windows 快速设置脚本
Windows 用户可以使用提供的设置脚本进行自动配置：
```powershell
```
# 下载并运行设置
npm install -g @kaminaduck/scryfall-mcp-server
scryfall-mcp-server-windows --setup
# 或在克隆后手动运行设置
```bash
git clone https://github.com/kaminaduck/scryfall-mcp.git
cd scryfall-mcp
npm install
npm run setup:windows
```
设置脚本将会：
- 创建必要的目录
- 设置环境变量
- 测试权限
- 生成Claude Desktop配置
- 提供故障排除信息
有关详细的Windows特定配置和故障排除，请参见[Windows设置指南](docs/WINDOWS_SETUP.md)。
**快速Windows修复：**
如果您遇到`${APPDATA}`扩展错误：
1. 全局安装：`npm install -g @kaminaduck/scryfall-mcp-server`
2. 在Claude Desktop配置中使用全局命令：`"command": "scryfall-mcp-server"`
### 测试您的配置
在将服务器添加到 Claude Desktop 之前，请手动测试它：
#### NPM 安装说明：
**Linux/macOS:**
1. **测试全局安装**：
```bash
which scryfall-mcp-server
# 应该返回二进制文件的路径
```
2. **测试服务器启动**：
```bash
timeout 3s scryfall-mcp-server
# 服务器应该静默启动（正常的 MCP 行为）
```
3. **测试环境变量**：
```bash
MCP_SERVER_NAME="scryfall-server" timeout 3s scryfall-mcp-server
# 应该检测到 MCP 模式并验证存储
```
**Windows:**
1. **测试全局安装**：
```cmd
where scryfall-mcp-server
REM 应该返回二进制文件的路径
```
2. **测试服务器启动**：
```cmd
timeout /t 3 /nobreak && taskkill /f /im scryfall-mcp-server.exe 2>nul || scryfall-mcp-server
REM 服务器应该静默启动（正常的 MCP 行为）
```
3. **测试环境变量**：
```cmd
set MCP_SERVER_NAME=scryfall-server && timeout /t 3 /nobreak && taskkill /f /im scryfall-mcp-server.exe 2>nul || scryfall-mcp-server
REM 应该检测到 MCP 模式并验证存储
```
#### NPX 使用说明：
**Linux/macOS:**
1. **测试 npx 执行**：
```bash
timeout 3s npx @kaminaduck/scryfall-mcp-server
# 应该下载并运行该包
```
**Windows:**
1. **测试 npx 执行**（可能因环境问题而失败）：
```cmd
timeout /t 3 /nobreak && taskkill /f /im node.exe 2>nul || npx @kaminaduck/scryfall-mcp-server
REM 可能会显示环境变量扩展错误 - 这是预期的
```
#### 对于源代码构建：
1. **直接测试二进制文件**：
```bash
cd /path/to/scryfall-mcp
timeout 3s ./dist/index.js
# 应该启动并显示 "Scryfall MCP server is running"
```
2. **使用环境变量进行测试**：
```bash
MCP_SERVER_NAME="scryfall-server" timeout 3s ./dist/index.js
# 应该检测到 MCP 模式并验证存储
```
#### 通用 MCP 协议测试：
3. **测试一个简单的 MCP 请求**（适用于任何方法）：
```bash
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | scryfall-mcp-server
# 应该返回一个包含可用工具的 JSON 响应
```
### 调试提示
1. **检查 Claude Desktop 日志** 以获取具体的错误信息
2. **对所有文件引用使用绝对路径**
3. **在将服务器与 Claude Desktop 配置之前，先单独测试服务器**
4. **验证 Node.js 版本** 是否为 18.0 或更高： `node --version`
5. **检查项目目录和二进制文件的权限**
### 获取帮助
如果您仍然遇到问题：
1. **验证您的配置** 是否与示例完全匹配
2. **检查日志** 以获取具体的错误信息
3. **手动测试服务器** 使用上述命令
4. **提交问题** 并附上您的配置和错误信息
## 需求
- Node.js 18.0+
- TypeScript 5.3+（用于开发）
- @modelcontextprotocol/sdk >= 0.4.0
> **注意**：此包作为 ES 模块分发。它需要支持 ES 模块的 Node.js 18 及以上版本。
## 开发
### 设置开发环境
```bash
git clone https://github.com/kaminaduck/scryfall-mcp.git
cd scryfall-mcp
npm install
```
### 构建项目
```bash
npm run build
```
### 运行测试
```bash
npm test
```
对于观察模式：
```bash
npm run test:watch
```
### 代码质量
```bash
```
# 检查代码
npm run lint
# 修复代码检查问题
npm run lint:fix
# 格式化代码
npm run format
```
### 代码风格
本项目遵循 TypeScript 和 ESLint 的最佳实践，并使用 Prettier 进行一致的格式化。所有代码都包含全面的 JSDoc 文档。
### 项目配置
该项目使用 ES 模块（在 package.json 中设置为 `"type": "module"`）。必须使用 CommonJS 的配置文件以 `.cjs` 扩展名命名：
- `.eslintrc.cjs` - ESLint 配置
- `jest.config.cjs` - Jest 测试配置
TypeScript 配置使用 `NodeNext` 模块解析，以实现最佳的 ES 模块兼容性。
## API 参考
### 作为库使用
如果您想从构建的源代码中以 ES 模块的方式程序化地使用此包：
```javascript
import { scryfallClient } from './dist/scryfallClient.js';
import { downloadManager } from './dist/downloadManager.js';
// 搜索卡牌
const cards = await scryfallClient.searchCards('lightning bolt');
// 下载卡牌图像
const results = await downloadManager.downloadCardImages(['Lightning Bolt']);
```
### 工具签名
```typescript
async function mcpSearchCards(query: string): Promise<SearchResult>
async function mcpDownloadCard(
cardName: string,
setCode?: string,
collectorNumber?: string,
forceDownload?: boolean
): Promise<DownloadResult>
async function mcpDownloadArtCrop(
cardName: string,
setCode?: string,
collectorNumber?: string,
forceDownload?: boolean
): Promise<DownloadResult>
async function mcpGetCardArtwork(cardId: string): Promise<ArtworkResult>
async function mcpVerifyDatabase(): Promise<DatabaseResult>
async function mcpScanDirectory(directory: string, updateDb?: boolean): Promise<DatabaseResult>
async function mcpCleanDatabase(execute?: boolean): Promise<DatabaseResult>
async function mcpDatabaseReport(): Promise<DatabaseResult>
```
## 贡献
欢迎贡献！请随时提交 Pull Request。对于重大更改，请先打开一个 issue 以讨论您希望更改的内容。
1. Fork 该仓库
2. 创建您的功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request
## 许可证
本项目采用 Apache License 2.0 许可 - 详细信息请参见 [LICENSE](LICENSE) 文件。
## 致谢
- [Scryfall](https://scryfall.com/) 提供了全面的 Magic: The Gathering API
- [Model Context Protocol](https://modelcontextprotocol.io/) 提供了标准化接口
- Magic: The Gathering 社区对我们持续的支持
## 支持
如果您遇到任何问题或有疑问：
1. 检查 [Issues](https://github.com/kaminaduck/scryfall-mcp/issues) 页面
2. 创建一个新问题，并详细描述您的问题
3. 包含相关的错误信息和系统信息
---
**注意**：这是一个非官方工具，与Wizards of the Coast或Scryfall没有关联。Magic: The Gathering是Wizards of the Coast LLC的商标。
连接信息
猜你喜欢
暂无推荐服务器