AI导哈

MTG卡片数据CLI工具

一个强大的命令行工具，提供Magic: The Gathering卡片数据的访问和AI集成功能，适用于卡片搜索、套牌分析和游戏辅助。

  • by guzmonne
  • Rust
  • 本地部署
  • 更新于
在 GitHub 查看 guzmonne/mtg

使用说明

MTG-CLI

Magic的强大命令行界面：具有AI集成功能的采集卡数据。

概述

MTG CLI是一个全面的命令行工具，通过多个API提供对Magic:The Gathering卡数据的访问。它采用Rust构建，以提高性能和可靠性，通过模型上下文协议（MCP）提供传统的CLI功能和现代AI集成。

特性

核心功能

  • 多个搜索引擎：支持MTG API、Wizards的Gatherer和Scryfall API
  • 高级卡片搜索：使用过滤器搜索名称、颜色、类型、稀有度、设置、法力消耗等
  • 设置浏览：探索魔术集并生成虚拟增强包
  • 类型信息：访问综合卡类型、子类型、超类型和游戏格式
  • 壳牌完井：对Bash、Zsh、Fish、PowerShell和Elvish的自动补全支持
  • 高性能：具有内置缓存和超时控制的异步操作
  • MTG竞技场伴侣 （仅限macOS/Windows）：实时日志监控和游戏状态跟踪

人工智能集成（MCP）

  • MCP服务器：用于无缝集成AI助手的模型上下文协议服务器
  • 丰富的数据访问：20000多张包含完整细节和元数据的魔术卡
  • 交互式工具：8个用于卡片查找、搜索和卡片组分析的综合工具
  • 预构建提示：常见Magic相关AI任务的模板
  • 多个传输：STDIO和SSE支持不同的集成需求

输出和可用性

  • 格式化表格：输出清晰易读，对齐得当
  • 分页：高效处理大型结果集
  • 环境变量：常见选项的可配置默认值
  • 详细模式：详细的日志记录和调试信息

安装

预构建二进制文件

从以下网址下载适用于您的操作系统的预构建二进制文件 GitHub发布。二进制文件可用于：

  • Linux（x86_64，ARM64）
  • macOS（英特尔、苹果硅）
  • Windows（x86_64）

从源代码构建

先决条件：

步骤：

  1. 克隆和构建：

    git clone https://github.com/cloudbridgeuy/mtg.git
cd mtg
cargo build --bin mtg --release

  2. 全局安装（可选）：

    cargo install --bin mtg --path crates/mtg

  3. 验证安装：

    ./target/release/mtg --version
# or if installed globally:
mtg --version

快速开始

命令概述

CLI提供对三个主要API的访问：

  • api -用于基本卡、集合和类型查询的MTG API
  • scryfall -Scryfall API，用于灵活语法的高级搜索
  • gatherer -Wizards官方卡数据收集器数据库

基本用法

# MTG API - Basic card search
mtg api cards search "Lightning Bolt"
mtg api sets list --page-size 10
mtg api types list

# Scryfall API - Advanced search
mtg scryfall search "c:blue t:instant mv<=3" --pretty
mtg scryfall named "Lightning Bolt" --pretty
mtg scryfall collector ktk 96 --pretty

# Gatherer API - Official Wizards data
mtg gatherer search --name "Lightning Bolt" --rarity "Common"
mtg gatherer search --colors "Red" --type "Instant"

# Generate booster pack
mtg api sets booster "KTK"

设置壳牌完井

# Bash
mtg completions generate bash > ~/.local/share/bash-completion/completions/mtg

# Zsh
mtg completions generate zsh > ~/.zsh/completions/_mtg

# Fish
mtg completions generate fish > ~/.config/fish/completions/mtg.fish

# PowerShell
mtg completions generate powershell >> $PROFILE

用于AI集成的MCP服务器

# Start MCP server (STDIO transport)
mtg mcp

# Start with SSE transport for web applications
mtg mcp sse --host 127.0.0.1 --port 3000

# With custom configuration
mtg --api-base-url https://api.magicthegathering.io/v1 --timeout 60 mcp

使用指南

全局选项

所有命令都支持这些全局选项：

  • --api-base-url <URL> -覆盖默认MTG API URL
  • --timeout <SECONDS> -设置请求超时（默认值：30）
  • --verbose -启用详细输出
  • --help -显示帮助信息
  • --version -显示版本信息

环境变量

使用环境变量配置默认值：

export MTG_API_BASE_URL="https://api.magicthegathering.io/v1"
export MTG_TIMEOUT=60
export MTG_VERBOSE=1

卡命令

# Basic search
mtg api cards search "Lightning"

# Exact name matching
mtg api cards search "Lightning Bolt" --exact

# Advanced filtering
mtg api cards list --colors "Red,Blue" --type "Creature" --cmc 4

# Get specific card by ID
mtg api cards get 409574

# Search with pagination
mtg api cards search "Dragon" --page 2 --page-size 20

设置命令

# List all sets
mtg api sets list

# Search sets by name
mtg api sets search "Zendikar"

# Get specific set information
mtg api sets get "KTK"

# Generate booster pack
mtg api sets booster "ISD"

键入命令

# List all card types
mtg api types list

# Get subtypes
mtg api types subtypes

# Get supertypes
mtg api types supertypes

# Get game formats
mtg api types formats

完成命令

# Generate completions for your shell
mtg completions generate bash
mtg completions generate zsh
mtg completions generate fish
mtg completions generate powershell
mtg completions generate elvish

用于AI集成的MCP服务器

MTG CLI包括一个强大的模型上下文协议（MCP）服务器，使AI助手能够无缝访问Magic:The Gathering数据。

主要特点

  • 丰富的数据访问：20000多张包含完整细节和元数据的魔术卡
  • 交互式工具：8个用于卡片查找、搜索和卡片组分析的综合工具
  • 多个API：通过统一接口访问MTG API、Scryfall和Gatherer
  • 高级搜索：具有15个以上排序选项和筛选的复杂查询
  • 甲板分析：综合统计，包括法力曲线和格式合法性
  • 多个传输：STDIO（默认）和SSE支持不同的集成需求

Claude桌面集成

添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "mtg": {
      "command": "/path/to/mtg",
      "args": ["mcp"],
      "env": {
        "MTG_TIMEOUT": "60"
      }
    }
  }
}

可用的MCP组件

  • 资源：访问完整的卡片、集合和类型数据库
  • 工具：用于搜索、分析和助推器生成的交互式功能
  • 提示：用于卡片分析、卡片组构建和比较的预构建模板

例子

高级卡片搜索

# Find expensive red creatures
mtg api cards list --colors "Red" --type "Creature" --cmc 6 --rarity "Mythic Rare"

# Search for artifacts from specific set
mtg api cards list --type "Artifact" --set "KTK" --page-size 50

# Find cards legal in Modern format
mtg api cards list --format "Modern" --rarity "Rare"

集合分析

# Research Khans of Tarkir
mtg api sets get "KTK"

# Generate multiple booster packs
for i in {1..3}; do
  echo "=== Booster Pack $i ==="
  mtg api sets booster "KTK"
  echo
done

甲板建筑研究

# Find all Dragons
mtg api cards list --subtype "Dragon" --page-size 100

# Research tribal strategies
mtg api types subtypes | grep -i "warrior\|wizard\|goblin"

# Check format legality
mtg api types formats

发展

建筑

# Development build
cargo build

# Release build with optimizations
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- api cards search "Lightning Bolt"

项目结构

mtg/
├── crates/
│   └── mtg/           # Main CLI application
├── docs/              # Comprehensive documentation
├── xtask/             # Build automation
├── Cargo.toml         # Workspace configuration
└── README.md          # This file

依赖项

关键依赖关系包括：

  • clap -命令行参数解析
  • clap_complete -壳体完井生成
  • tokio -异步运行时
  • reqwest -API调用的HTTP客户端
  • serde -JSON序列化/反序列化
  • prettytable -格式化表格输出
  • rmcp -模型上下文协议服务器
  • color-eyre -增强的错误报告

文档

综合文档可在 docs/ 目录：

CLI使用情况

MCP集成

故障排除

常见问题

网络超时：

# Increase timeout
mtg --timeout 120 api cards search "Complex Query"

API速率限制：

  • 使用较小的页面大小
  • 增加请求之间的延迟
  • CLI包括内置的速率限制

连接问题：

# Test API connectivity
curl -s "https://api.magicthegathering.io/v1/cards?pageSize=1"

# Check with verbose output
mtg --verbose api cards search "test"

壳牌完井不起作用：

# Verify completion file exists
ls -la ~/.local/share/bash-completion/completions/mtg

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

调试模式

启用详细调试：

export RUST_LOG=debug
export RUST_BACKTRACE=1
mtg --verbose api cards search "Lightning Bolt"

贡献

欢迎投稿！无论您是在修复错误、添加功能、改进文档还是增强AI集成功能。

入门指南

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feature/amazing-feature
  3. 进行更改
  4. 如果适用，添加测试
  5. 运行测试套件： cargo test
  6. 提交您的更改： git commit -m 'Add amazing feature'
  7. 推到分支： git push origin feature/amazing-feature
  8. 打开拉取请求

开发指南

  • 遵循Rust的最佳实践和习惯用法
  • 添加新功能的测试
  • 更新面向用户的更改文档
  • 确保shell完成与新命令一起工作
  • 如果修改服务器功能，则测试MCP集成

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

链接

  • 文档: docs/
  • 安装件API: https://magicthegathering.io/
  • MCP规范: https://spec.modelcontextprotocol.io/
  • 问题: https://github.com/cloudbridgeuy/mtg/issues

内置于❤️ Rust for the Magic:the Gathering社区

相关 MCP