pokewallet-mcp

<div align="center">  # 宝可梦钱包 MCP ### 将您的视觉模型对准一张卡片。获取准确的印刷信息——而不是自信的猜测。 [](https://www.python.org/) [](https://modelcontextprotocol.io/) [](LICENSE) [](#run-it) **基于视觉的宝可梦 TCG 鉴定，精确变体价格匹配，套装研究和本地收藏工具，适用于符合标准的 MCP 客户端。** </div> PokéWallet MCP 填补了“看起来像喷火龙”和“这是第一版无阴影全息印刷品”之间的危险差距。它结合了具有视觉能力的 OpenAI 兼容模型与 PokéWallet 目录数据，对候选印刷品进行排名，验证可见的版本和箔面证据，并返回只有照片支持的市场变体。 ## 为什么收藏家需要精确匹配变体 具有相同名称和收藏编号的卡片可以具有截然不同的价值。版本戳、全息图案、箔面覆盖、区域印刷、发行戳和已知的错误标记都至关重要。普通的名称搜索无法安全地解决这些差异。 PokéWallet MCP 使用分阶段的管道： ```text 本地照片 → 安全解码 + 方向接触表 → 结构化视觉证据 → PokéWallet 目录候选者 → 元数据排名 + 参考图像验证 → 严格的市场变体选择 → 置信度、不确定性和数据质量警告 ``` 它**不**验证卡片，不分配状况或等级，也不承诺销售价值。它识别可见的印刷证据，并保持不确定性可见。 ## 为影响价格的细节而构建 | 证据类别 | 识别示例 | |---|---| | 版本和印刷批次 | 第一版，无限， 无阴影，无版本标记，`1999–2000`版权线 | | 核心饰面 | 普通，全息箔，反向全息箔 | | 箔面覆盖 | 仅艺术品，卡片主体，全卡，选择性 | | 反面图案 | 宝可球，大师球，传奇收藏烟花，能量符号，类型符号，套装徽标，金色边框 | | 全息图案 | 标准/普通，宇宙，星系之星，星系，裂冰，线，彩带，蚀刻，纹理，彩虹 | | 发行变体 | 黑星促销，预发布，STAFF，宝可梦中心，零售商独家，联盟，获胜者，世界锦标赛，主题套装，束装，购买赠品，盖章促销 | | 谨慎的错误标记 | 灰色/幽灵印章，无符号，黑点，无损伤，进化/文本错误 | 特定证据非常严格。如果图像显示大师球反面图案，则不会默默替换为通用反向全息价格。如果它显示裂冰，则不会将通用全息箔行视为等效。可能的错误卡标记会改善候选排名，但仍然明确表示为尝试，直到独立验证。 ### 动态照片，而非扫描完美输入 图像管道接受本地路径或 base64 数据，并生成多个证据视图： - EXIF 感知方向校正 - 多尺度，基于卡片的区域建议，放大嵌入截图或广角场景的卡片 - 0°，90°，180°和270°视图 - 高分辨率全卡视图和聚焦细节裁剪 - 倾斜/视角报告和强大的接触表 - 有界像素数，字节大小和图像边缘长度 - 可选的本地图像路径允许根目录强制执行 验收测试包括直立、侧卧、倒置和倾斜的卡片照片。不需要 OpenCV 或 GPU 重型探测器进行预处理；Pillow 准备视图，而您配置的视觉模型执行视觉分析。 ## 真实的 Hermes 结果 此缩略的截图是从 Hermes 验收测试中渲染的，使用拍摄的基地套装喷火龙。 Hermes 加载了便携式技能，检测并调用了 `mcp__pokewallet__analyze_pokemon_card`，检测到 100% 置信度的圆形第一版印章，选择了**第一版全息箔**，拒绝了无限行，并显示了不一致的市场字段，而不是呈现误导性的数字。  ### 自然语言估值 用简单的语言提问一张卡片图像，代理可以解决印刷问题，查询 PokéWallet 市场数据，保持美元和欧元来源的独立，并用收藏家友好的语言解释结果。  市场数据是时间点源数据，而不是评估。状况、真伪和等级仍需要独立评估。 结构化响应包括证据——而不只是答案： ```json { "status": "likely", "identified_card": { "name": "喷火龙", "collector_number": "004/102", "set": {"name": "基地套装（无阴影）"} }, "detected": { "edition_guess": "first_edition", "finish_guess": "holofoil", "foil_pattern_guess": "standard_holofoil", "visible_stamps": ["EDITION 1"], "field_confidence": {"edition_guess": 1.0} }, "edition_evidence": { "edition_guess": "first_edition", "visible_stamp_text": ["EDITION 1"], "confidence": 1.0 }, "matched_price_variants": [{ "source": "tcgplayer", "currency": "USD", "variant": {"name": "第一版全息箔"}, "data_quality_warnings": [ "市场字段内部不一致；请验证最近的售出清单。" ] }] } ``` ## 功能集 - **40 个 MCP 工具**用于卡片、套装、价格、分析、本地收藏、观察列表、状态和图像识别 - **8 个资源**用于卡片、本地化卡片图像、套装、套装徽标、收藏和观察列表数据 - **4 个提示**用于图像识别、卡片研究、印刷比较和套装浏览 - 一个基于标准的**代理技能**，具有丰富的触发自然语言路由指令 - MCP 初始化指令和一个独立于客户端特定工具前缀的单一高级别 `analyze_pokemon_card` 入口点 - 精确的收藏编号解析，支持标准、字母数字、分数、促销和前导零格式 - 候选者从标题、收藏编号、套装代码、HP、阶段、可见印章、变体标记和可能的错误中评分 - 当元数据不足以分离附近的印刷品时，进行参考图像验证 - 每个来源的价格变体，分别保留 TCGPlayer 美元和 Cardmarket 欧元 - 一个机器可读的 `answer_policy`，禁止使用外部拍卖、评级、已售清单或基于内存的价格 - 明确的模糊状态：`confirmed`，`likely`，`ambiguous`和`not_found` - 批量图像识别，有界并发，缓存，重试/回退和结构化错误 - 本地 SQLite 收藏/观察列表存储，支持 JSON 和 CSV 导出 - stdio 和 Streamable HTTP 传输 - 非根 Docker 镜像和仅限环回的 Compose 端口绑定 ## 快速入门 要求： - Python 3.11 或更新版本 - [uv](https://docs.astral.sh/uv/) - 一个 PokéWallet API 密钥 - 用于图像识别的 OpenAI 兼容**视觉**端点和视觉能力模型 ```bash git clone <您的仓库网址> cd poke-mcp uv sync --extra dev cp .env.example .env ``` 在 PowerShell 上，使用 `Copy-Item .env.example .env` 作为最后一个命令。然后编辑 `.env`： ```dotenv POKEWALLET_API_KEY=您的密钥 VISION_API_BASE=http://127.0.0.1:1234/v1 VISION_API_KEY=如果需要，您的本地提供商密钥 VISION_MODEL=您的视觉模型别名 VISION_TIMEOUT_SECONDS=600 VISION_MAX_TOKENS=3000 VISION_DISABLE_THINKING=true ``` 使用本地提供者公开的模型别名，而不是原始模型文件名。一些运行时环境仅通过该别名附加视觉投影仪；选择 GGUF 可以让 GPU 空闲，并使图像请求表现得像文本调用一样。 ### API 密钥和机密 1. 复制 `.env.example` 到 `.env`；请勿使用真实凭证重命名或编辑 `.env.example`。 2. 设置 `POKEWALLET_API_KEY`。这是文本/目录操作的唯一必需 API 凭证。 3. 为图像识别设置 `VISION_MODEL`，以及当提供者不在默认本地 URL 时设置 `VISION_API_BASE`。 4. 仅当视觉提供者需要身份验证时设置 `VISION_API_KEY`。本地服务器通常接受空值；托管提供者通常不接受。 5. 在 `${POKEWALLET_API_KEY}` 和 `${VISION_API_KEY}` 占位符上保留客户端配置示例。不要将真实密钥粘贴到已提交的 JSON、YAML、截图或 shell 脚本中。 验证连接客户端之前： ```bash uv run pokewallet-mcp --check-config uv run pokewallet-mcp --health-check ``` ## 通用自然语言路由 PokéWallet 的便携式路由层位于 MCP 服务器中，而不位于 Pi、Hermes、Discord 或其他前端适配器中： 1. 在标准 MCP 初始化握手期间，服务器发送一个路由合约，告诉客户端为卡片照片识别或价值问题调用 `analyze_pokemon_card`。 2. `analyze_pokemon_card` 是一个明确命名的、只读的、幂等的顶级工具。其描述包含完整的选择规则，甚至在客户端为工具名称添加前缀时也有效。 3. [`skills/pokewallet-card-analysis/SKILL.md`](skills/pokewallet-card-analysis/SKILL.md) 以开放的 Agent Skills 格式打包相同的流程。任何兼容 Agent Skills 的框架都可以加载该技能而不做任何更改；只有框架的发现/安装位置有所不同。 不需要客户端特定的路由适配器即可使用此便携式路径。连接 MCP 服务器，如果框架支持 Agent Skills，请复制或链接 `skills/pokewallet-card-analysis` 到该框架的标准技能目录中。根据需要配置框架以预加载或自动激活该技能，以便在需要时进行卡片图像对话。 ## 在 Hermes 上安装 包含的安装程序是幂等的且生产安全的：它找到项目虚拟环境，添加或更新唯一的 `pokewallet` MCP 条目，将不变的便携式 Agent 技能安装到 Hermes 的标准 `skills` 目录中，镜像非机密项目设置，备份 Hermes 配置和任何以前的技能副本，将机密复制到 Hermes 的私有 `.env` 中，并在 YAML 中留下 `${...}` 占位符。它从不打印 API 密钥。 ### Windows PowerShell ```powershell Copy-Item .env.example .env # 配置 .env 后： uv run python scripts/install_hermes.py ` --project . ` --hermes-home "$env:LOCALAPPDATA\hermes" hermes gateway restart ``` ### macOS 或 Linux ```bash cp .env.example .env # 配置 .env 后： uv run python scripts/install_hermes.py --project . --hermes-home "$HOME/.hermes" hermes gateway restart ``` Hermes 向模型公开已安装的技能元数据，但一些本地模型可能会在读取技能正文之前并行启动通用视觉。在首次调用工具选择之前，请预加载标准技能，以便其指令保持活动状态： ```bash hermes chat --skills pokewallet-card-analysis ``` 您也可以在一次 `hermes chat` 调用中使用 `-s pokewallet-card-analysis`。对于 Discord 或 Slack 网关通道，请使用 Hermes 内置的 `channel_skill_bindings` 和该通道的 ID： ```yaml discord: channel_skill_bindings: - id: "您的频道 ID" skills: ["pokewallet-card-analysis"] ``` 一旦通过 Hermes 的标准 Agent 技能激活机制预加载，自然语言请求（例如“这张宝可梦卡值多少钱？”）会在必要时发现延迟的 MCP 工具并调用高级分析器，而无需通用视觉或网络估值。 从 Hermes 环境验证： ```bash python scripts/verify_hermes.py ``` Hermes 应该报告已注册的 `pokewallet` 条目，并且 `hermes skills list` 应该显示已启用的 `pokewallet-card-analysis`。然后启动 **Hermes 本身**，预加载技能，提供本地卡片图像，并要求它识别确切的印刷品和匹配的市场变体。Discord 仅是一个前端，如果您的 Discord 机器人路由到该 Hermes 实例；当您希望在那里使用相同的预加载时，请使用标准的通道技能绑定。 ## 在其他 MCP 客户端中安装 任何支持 stdio MCP 服务器的客户端都可以直接启动该软件包。使用绝对路径，因为桌面客户端通常在存储库外部启动。 ### 通用 `mcpServers` 配置 ```json { "mcpServers": { "pokewallet": { "command": "/绝对/路径/到/poke-mcp/.venv/bin/python", "args": ["-m", "pokewallet_mcp", "--transport", "stdio"], "env": { "POKEWALLET_API_KEY": "${POKEWALLET_API_KEY}", "VISION_API_BASE": "http://127.0.0.1:1234/v1", "VISION_API_KEY": "${VISION_API_KEY}", "VISION_MODEL": "您的视觉模型别名", "VISION_TIMEOUT_SECONDS": "600", "VISION_MAX_TOKENS": "3000", "VISION_DISABLE_THINKING": "true" } } } } ``` 在 Windows 上，`command` 通常以 `.venv\\Scripts\\python.exe` 结尾。与 Claude Desktop、Cursor、Windsurf 和 VS Code MCP 集成等客户端相同；使用客户端要求的配置位置和环境变量语法。避免在提交的 JSON 文件中粘贴真实密钥。 对于实现 Agent Skills 的任何框架，还请复制或链接此存储库的 `skills/pokewallet-card-analysis` 目录到其记录的技能搜索路径，并使用该框架的正常自动激活或预加载设置。自动扩展匹配技能的框架不需要额外规则；仅显示元数据的框架应该预加载它以防止首次调用的通用视觉竞争。 不实现 Agent Skills 的框架仍然可以使用 MCP 初始化指令和高级工具。没有 Pi 适配器、Discord 适配器或客户端特定 Python 路由器是该项目的组成部分。 ### 流式 HTTP ```bash uv run pokewallet-mcp --transport streamable-http ``` 默认端点绑定到 `127.0.0.1:8765`。对于容器化的本地部署： ```bash docker compose up --build -d ``` ## 配置 所有设置都是环境变量。`.env.example` 可以安全提交；`.env` 和 `.env.*` 被忽略，但有一个明确的例外，即 `.env.example`。 | 变量 | 默认值 | 目的 | |---|---:|---| | `POKEWALLET_API_KEY` | 空 | 必需的 PokéWallet 凭证 | | `POKEWALLET_BASE_URL` | `https://api.pokewallet.io` | API 来源 | | `POKEWALLET_TIMEOUT_SECONDS` | `30` | API 超时，最大 300 秒 | | `POKEWALLET_ENABLE_PRO` | `false` | 启用 Pro 端点 | | `VISION_API_BASE` | `http://127.0.0.1:1234/v1` | OpenAI 兼容视觉 API | | `VISION_API_KEY` | 空 | 视觉提供者凭证（如果需要） | | `VISION_MODEL` | 空 | 提供者的视觉能力模型别名 | | `VISION_TIMEOUT_SECONDS` | 示例中为 `600` | 视觉请求超时，最大 600 秒 | | `VISION_MAX_TOKENS` | 示例中为 `3000` | 结构化提取响应预算 | | `VISION_TEMPERATURE` | `0.0` | 确定性提取温度 | | `VISION_DISABLE_THINKING` | 示例中为 `true` | 请求兼容的本地模型的直接 JSON | | `CARD_IMAGE_MAX_MB` | `15` | 输入字节限制 | | `CARD_IMAGE_MAX_PIXELS` | `40000000` | 解压缩炸弹防护 | | `CARD_IMAGE_MAX_EDGE` | `1600` | 准备图像边缘限制 | | `ALLOWED_IMAGE_ROOTS` | 空 | 以逗号分隔的本地路径允许列表 | | `MCP_TRANSPORT` | `stdio` | `stdio` 或 `streamable-http` | | `MCP_HOST` / `MCP_PORT` | `127.0.0.1` / `8765` | HTTP 绑定地址 | | `CACHE_ENABLED` | `true` | 内存和图像缓存 | | `COLLECTION_ENABLED` | `true` | 本地收藏/观察列表工具 | | `COLLECTION_DATABASE_PATH` | 平台数据目录 | SQLite 数据库位置 | | `COLLECTION_EXPORT_DIRECTORY` | 平台数据目录 | JSON/CSV 导出目的地 | ## 工具映射 | 区域 | 工具 | |---|---| | 鉴定 | `analyze_pokemon_card`，`identify_card_from_image`，`identify_cards_from_images`，`resolve_card` | | 卡片发现 | `search_cards`，`search_card_by_name`，`find_card_by_number`，`batch_search_cards`，`get_card` | | 价格和比较 | `get_card_prices`，`summarize_card_value`，`compare_card_prices`，`compare_printings`，`compare_cards` | | 图像 | `get_card_image` 加图像资源 | | 套装 | `list_sets`，`search_sets`，`get_set`，`get_set_cards`，`get_complete_set_cards`，`get_set_image` | | 分析 | 套装统计，趋势套装，完成价值，套装价格，价格历史，热门卡 | | 收藏 | 添加/更新/删除/列表/价值/导出/摘要 | | 观察列表 | 添加/删除/列表/检查 | | 操作 | `pokewallet_health`，`pokewallet_api_info` | ## 精确识别的工作原理 1. 服务器拒绝远程网址，并安全地解码本地路径或 base64 图像。 2. 它提出在多个尺度上丰富、详细的类似卡片区域，允许从截图或广角场景中恢复卡片，而无需依赖复杂的计算机视觉。 3. 它规范化 EXIF 方向，生成旋转的全卡视图，并为细小文字、印章、套装符号和箔证据创建定向裁剪。 4. 视觉模型返回具有每个字段的置信度、可见标记和不确定性的严格模式。 5. PokéWallet 候选项根据稳定的元数据和可见的变体证据进行排名。 6. 可以将接近的候选项与参考卡片图像进行比较。 7. 有针对性的变体检查检查版本、完成度、箔图案/覆盖率、发行印章和可能的错误标记。 8. 早期的 Wizards 卡片会收到一个孤立的直立版本近景，以便可见的圆形 `EDITION 1` 印章可以覆盖不正确的 Unlimited 猜测，而不会混淆稀有度或能量符号。 9. 与观察到的证据冲突的市场变体被删除。响应仅携带支持的行、保留的货币、模糊标志和源数据警告。 ## 安全状况 - 在应用程序代码、示例、截图、Docker 文件或 Hermes YAML 中没有硬编码 API 密钥。 - `.env`、`.env.*`、数据库、缓存、日志、导出、测试环境、IDE 元数据和操作系统垃圾被忽略。 - Hermes 安装程序从项目 `.env` 读取机密，仅写入私有 Hermes `.env`，安装便携式技能，并创建带有时间戳的备份。 - 配置/状态输出仅报告诸如 `api_key_configured` 的布尔值；它从不返回机密值。 - 图像工具拒绝远程网址，强制执行解码图像限制，并可以限制对显式文件系统根目录的访问。 - HTTP 传输默认绑定到环回；Docker Compose 端口也是仅限环回。 - 集合导出被限制在配置的导出目录内。 在发布分叉之前，请运行适合您组织的机密扫描。一个有用的本地基线是： ```bash git grep -nEi '(api[_-]?key|token|secret|password).{0,30}[=:].{0,5}[A-Za-z0-9_-]{16,}' -- ':!README.md' ':!.env.example' ``` ## 测试 ```bash uv run ruff check . uv run ruff format --check . uv run pytest -q ``` 实时测试是可选的，因为它们调用外部服务： ```bash POKEWALLET_RUN_LIVE_TESTS=1 uv run pytest -m integration -q ``` `scripts/` 下的实用脚本涵盖了传输烟雾测试、实时识别、聚焦版本检测、准备好的表格检查、方向装置、视觉诊断、Hermes 安装和 Hermes MCP 注册。 ## 研究和设计参考 实现使用了原始代码，但照片策略和变体分类法已针对现有的开源扫描仪和收藏家参考进行了检查： - [MCP 生命周期规范](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle) 在初始化响应中定义了可移植的服务器 `instructions`。 - [Agent Skills 规范](https://agentskills.io/specification) 定义了此存储库中包含的可移植 `SKILL.md` 包。 - [1vcian/Pokemon-TCGP-Card-Scanner](https://github.com/1vcian/Pokemon-TCGP-Card-Scanner) 演示了轮廓/长宽比扫描、感知匹配、定向边界框和合成旋转/视角增强。PokéWallet MCP 采用了恢复力目标，而无需添加其 YOLO/OpenCV 运行时。 - [hugopeixoto/ptcg-detection](https://github.com/hugopeixoto/ptcg-detection) 探索了感知哈希和套装符号模板；此服务器结合结构化视觉和目录候选项，因此它不限于单个相机分辨率或模板库。 - [OpenCV 卡片扫描器示例](https://gist.github.com/D31T4/af49aaa110523015f80862d1d25482fd) 告知了视角/倾斜威胁模型。 - [TCGplayer 的稀有度指南](https://help.tcgplayer.com/hc/en-us/articles/360025636074-What-are-the-rarities-of-Pok%C3%A9mon-TCG-cards) 记录了收藏家编号、促销星级和全息与反全息区别。 - [CGC 的 Pokémon 变体指南](https://www.cgccards.com/news/article/8591/pokemon-variants/) 记录了灰色/幽灵印章、Cosmos Machamp、无损伤 Ninetales、Black Dot Charizard、进化错误和 `1999–2000` 印刷批次。 - [CGC 的 Jungle No Symbol 指南](https://www.cgccards.com/news/article/14903/cards-registry-jungle-no-symbol/) 涵盖了缺失的套装符号变体。 - [Bulbapedia 的全息箔指南](https://bulbapedia.bulbagarden.net/wiki/Holofoil) 目录了 Cosmos、Cracked Ice、套装徽标、符号、金色边框和其他历史图案。 - [Pokémon Card 151](https://bulbapedia.bulbagarden.net/wiki/Pok%C3%A9mon_Card_151_%28TCG%29) 记录了在支持的亚洲语言版本中，独特的精灵球和更稀有的大师球镜像全息图案。 - [Prerelease 卡片](https://bulbapedia.bulbagarden.net/wiki/Prerelease_Cards_%28TCG%29) 涵盖了 `PRERELEASE`、扩展徽标和 `STAFF` 印章。 这些是视觉识别参考，而不是价格来源。价格响应来自配置的 PokéWallet API，并保留其市场/来源元数据。 ## 限制 - 单张照片通常无法证明真伪、卡片材质、表面状况或确切等级。 - 保护膜眩光、压缩、阴影和缺少背面照片会隐藏箔或伪造指示器。 - 箔图案分类仅限于图像和配置的视觉模型。 - 错误卡标记为可能的变体，从不认证错误。 - 市场数据可能已过时或内部不一致；必须保留警告，并且最近的售出清单应独立验证以做出重要决定。 - 自然语言自动路由依赖于 MCP 客户端遵循服务器指令并为工具参数提供附件；MCP 无法拦截客户端的原始聊天输入。 ## 许可证和商标 [MIT](LICENSE)。生成的项目艺术品是原创的，旨在避免官方角色艺术、卡片背面、徽标和受商标保护的球符号。 宝可梦及相关名称是其各自所有者的商标。PokéWallet MCP 是一个独立的集成，不隶属于、未得到、或由任天堂、Creatures、GAME FREAK、The Pokémon Company、TCGplayer、Cardmarket 或 PokéWallet 赞助或认可。