角色构建优化工具

流放之路2构建优化器MCP

社区项目免责声明

这是一个独立的、粉丝制作的社区项目，建立在对《流放之路2》的热爱之上。它是 与Grinding Gear Games没有附属关系、认可或正式联系 无论如何。《流放之路》是Grinding Gear Games的商标。所有游戏数据和资产仍然是其各自所有者的财产。

用于流亡之路2字符分析和优化的模型上下文协议（MCP）服务器。提供38个MCP工具，用于AI驱动的构建分析、被动树分析、项目模型验证、支持gem验证和构建路径集成（包括一个运行PoB实例的实时桥）。

这是什么？

这是一个 MCP服务器 -后端服务，使AI助手（如Claude、ChatGPT、Cursor等）能够分析您的流放之路2字符并提供优化建议。

它的作用：

• 从poe.ninja获取您的角色数据
• 分析防御数据、技能、装备和被动树
• 验证支持gem组合（防止无效建议）
• 检查拼写和支持宝石数据
• 建筑规范的进出口路径
• 将您的构建与顶级阶梯玩家进行比较
• 解释PoE2游戏机制

您需要什么：

• 支持MCP（克劳德桌面、ChatGPT桌面、光标、Windsurf等）的AI助手
• 已安装Python 3.9+
• 您在poe.ninja上的PoE2角色（公开资料）

快速开始

1.安装

选项A:PyPI（推荐）

pip install poe2-mcp

选项B：来源

git clone https://github.com/HivemindOverlord/poe2-mcp.git
cd poe2-mcp
pip install -e .

2.连接到您的AI助手

请在下面选择您的平台：

Claude桌面集成

选项A：手动配置（建议用于开发）

编辑您的Claude Desktop配置文件：

• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

正确的配置取决于您的安装方式。挑一个。

A1.如果你跑了 pip install poe2-mcp （推荐）

使用 poe2-mcp 控制台脚本。它在你的路径之后 pip install 适用于所有平台，无需绝对路径：

{
  "mcpServers": {
    "poe2-optimizer": {
      "command": "poe2-mcp",
      "env": {}
    }
  }
}

如果Claude Desktop报告找不到 poe2-mcp，你的 pip 安装目录不在Claude Desktop的PATH中。要么跑 which poe2-mcp (where poe2-mcp 在Windows上）并使用绝对路径，或回退到 python -m:

{
  "mcpServers": {
    "poe2-optimizer": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "env": {}
    }
  }
}

A2.如果你克隆了+ pip install -e . 来自源头

指向 launch.py 直接。它执行一些裸控制台脚本跳过的Windows特定UTF-8设置：

窗户：

{
  "mcpServers": {
    "poe2-optimizer": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\poe2-mcp\\launch.py"],
      "env": {}
    }
  }
}

macOS/Linux：

{
  "mcpServers": {
    "poe2-optimizer": {
      "command": "python3",
      "args": ["/Users/YourName/poe2-mcp/launch.py"],
      "env": {}
    }
  }
}

编辑配置后重新启动Claude Desktop。服务器将出现在您的MCP工具中。

选项B：下载.mcpb捆绑包（一键安装）

预构建的MCP捆绑包可在Claude Desktop中一键安装：

1. 下载 poe2-mcp-1.0.0.mcpb 从 GitHub 发布
2. 在克劳德桌面：设置>扩展>安装扩展
3. 选择已下载的 .mcpb 文件

注： 该捆绑包包含所有游戏数据文件，大小约为109MB。Python 3.9+必须安装在您的系统上。

建议： 对于开发或想要自动更新，请使用选项A（手动配置） pip install poe2-mcp.

其他AI平台

MCP是一个由多个AI平台支持的开放标准：

OpenAI ChatGPT桌面

ChatGPT桌面应用程序支持MCP服务器。配置因版本而异-请查看OpenAI的文档以获取当前的设置说明。

光标AI

Cursor通过SSE协议支持MCP。添加到光标设置中：

{
  "mcp": {
    "servers": {
      "poe2-optimizer": {
        "command": "python",
        "args": ["/path/to/poe2-mcp/launch.py"]
      }
    }
  }
}

帆板运动

Windsurf有一个内置的MCP插件商店。您可以：

• 在插件商店中搜索“poe2”（如果已发布）
• 在设置中手动添加服务器路径

克劳德代码（CLI）

# In your project directory
claude mcp add poe2-optimizer python /path/to/poe2-mcp/launch.py

其他兼容客户端

• Zed编辑
• 雷普利特
• 科迪姆
• 源代码图
• 微软语义内核
• Salesforce代理平台

检查每个平台的MCP服务器配置文档。

可用工具（已注册38个）

连接后，您可以让您的AI助手使用这些工具。这 权威列表是 _register_tools() 在 src/mcp_server.py --验证 实时计数：

python -c "import re; print(len(re.findall(r'types\.Tool\(\s*name=', open('src/mcp_server.py').read())))"

人物分析

验证和检查

被动树数据

基本项目数据

项目型号数据

知识与发现

建筑路径（基于文件）

贸易与商品

效用

桥梁施工现场路径： src/pob/client.py +the pob_addon/ Lua插件实现了一个到正在运行的PoB的TCP桥（127.0.0.1:49085） 例子网桥客户端存在，但 pob_* 操作是 不 当前注册为MCP工具 --它们在内部/通过 集成测试套件。他们不在上述38人之列。

未注册： DPS/EHP独立计算器、优化器和 生活 pob_* 桥操作系统有处理程序/客户端，但还没有工具注册。

示例用法

配置后，只需自然地与您的AI对话：

“从Tomawar的账户分析我的角色Tomawar TheFourth”

“导入此poe.ninja URL：https://poe.ninja/poe2/builds/char/..."

“我可以同时使用更快的弹丸和更慢的弹丸吗？”（使用 validate_support_combination)

“显示所有适用于投射物的支持宝石”（使用 list_all_supports)

“生命构建有哪些基石？”（使用 list_all_keystones)

“告诉我混沌接种”（使用 inspect_keystone)

“将我的版本与顶级Witchhunter玩家进行比较”

“解释装甲在PoE2中的工作原理”

“哪些前缀可以滚动到项目上？”（使用 get_available_mods)

“显示力量模组的所有层级”（使用 get_mod_tiers)

“Strength1和Strength2可以存在于同一个项目上吗？”（使用 validate_item_mods)

“搜索防火模组”（用途 search_mods_by_stat)

AI将自动使用适当的工具。

贸易API认证（可选）

为了 search_trade_items 要工作，您需要通过pathofexile.com进行身份验证：

pip install playwright
playwright install chromium
python scripts/setup_trade_auth.py

这将打开一个浏览器供您登录，然后保存您的会话cookie。

本地游戏数据库

服务器包括一个本地数据库，其中包含：

• 4975+个被动树节点
• 335+优势节点（99%覆盖率）
• 14269个项目修饰符（2252个前缀，2037个后缀，8930个隐含）
• 来自建筑之路的完整技能宝石数据
• 支持宝石效果和交互
• 基础项目和独特项目

数据从以下位置加载 data/ 启动时的目录。

集中式游戏数据分发（1.0.2中的新功能）

您不再需要提取 .datc64 您自己的PoE2安装中的文件。MCP在首次运行时和每个补丁后自动从该仓库的GitHub Release下载维护的游戏数据包（解析 #53).

它是如何工作的：

1. launch.py 电话 src/data/data_distributor.ensure_data_current() 启动期间
2. 它比较 data/version.json （本地）与标记的最新版本相对 data-v*
3. 如果有更新的数据可用，它会下载 poe2-data.zip 然后拉开拉链 data/
4. MCP从当前数据开始

选择退出 （改为运行您自己的本地提取）：

export POE2_MCP_NO_DATA_FETCH=1   # macOS/Linux
$env:POE2_MCP_NO_DATA_FETCH=1     # PowerShell

然后通过以下方式提取 scripts/extract_poe2_data.py 根据您自己的许可PoE2安装。

手动刷新：

python -m src.data.data_distributor

数据政策： 该捆绑包仅通过仓库内提取脚本从维护者的许可PoE2安装中提取。没有捆绑第三方wiki/抓取的数据。看 CLAUDE.md 有关详细信息，请参阅“数据源策略”。

数据流通和漂移保护： 提取装运的数据集 来自完整的补丁0.5表集（1019规范 .datc64 平衡表 通过 scripts/extract_balance_tables_v1.py)，版本在 data/game/version.json (data-v0.5.0-r12). data/game/schema_fingerprints.json 记录每个表的行数/行大小/哈希值；再提取与它的区别 因此，未来添加、移动或调整列大小的补丁会大声失败 默默地提供错误的数据。看 docs/GAME_DATA_RESEARCH.md 为了 逆向工程文件格式和提取方法。

建筑

poe2-mcp/
├── launch.py              # Entry point
├── src/
│   ├── mcp_server.py      # Main MCP server (38 tools registered)
│   ├── api/               # External API clients
│   │   ├── poe_ninja_api.py
│   │   ├── character_fetcher.py
│   │   └── rate_limiter.py
│   ├── analyzer/          # Analysis components
│   │   ├── character_analyzer.py
│   │   └── weakness_detector.py
│   ├── calculator/        # Numeric calculations
│   │   ├── ehp_calculator.py
│   │   ├── spirit_calculator.py
│   │   └── stun_calculator.py
│   ├── data/              # Data providers
│   │   ├── mod_data_provider.py
│   │   └── fresh_data_provider.py
│   ├── optimizer/         # Optimization engines
│   │   ├── gear_optimizer.py
│   │   └── gem_synergy_calculator.py
│   ├── parsers/           # Data parsers
│   │   ├── passive_tree_resolver.py
│   │   └── specifications/  # Datc64 format specifications
│   ├── knowledge/         # Game mechanics knowledge base
│   │   └── poe2_mechanics.py
│   └── database/          # SQLite database
│       ├── models.py
│       └── manager.py
├── data/                  # Game data files
│   ├── psg_passive_nodes.json
│   ├── poe2_support_gems_database.json
│   └── poe2_mods_extracted.json
└── tests/                 # Test suite

发展

运行测试

pytest tests/ -v

直接运行服务器

# If installed via pip
poe2-mcp

# From source
python launch.py

关键文件

• src/mcp_server.py -带有38个注册工具的MCP服务器
• src/data/mod_data_provider.py -项目模块数据访问层
• src/calculator/ehp_calculator.py -EHP计算
• src/optimizer/gem_synergy_calculator.py -支持gem逻辑
• data/psg_passive_nodes.json -被动树数据库
• data/poe2_mods_extracted.json -项目修改器数据库（14269 mods）

故障排除

在Claude Desktop中“找不到服务器”

• 检查配置中的路径是绝对的（不是相对的）
• 确保Python在你的PATH中
• 试着跑步 python launch.py 手动查看错误

“未找到字符”

• 你的角色必须在poe.ninja（公共阶梯）上
• 字符名称区分大小写
• 尝试使用完整的poe.ninja URL import_poe_ninja_url

工具返回空结果

• 数据库可能需要初始化： python launch.py 处理这个
• 检查 data/ 目录中存在JSON文件

积分

数据来源：

• poe.ninja -角色数据和构建
• 建筑路径（PoE2） -技能数据
• 磨削路径 -被动树数据

MCP协议：

• 模型上下文协议
• mcpb捆绑格式

许可证

MIT许可证-请参阅 许可证 了解详情。

这是一个社区项目。不隶属于Grinding Gear Games。

报告问题