Name: 游戏AI桥接服务器
Author: BotWithUs

使用说明

BotWithUs MCP服务器

MCP（模型上下文协议）服务器，通过管道服务器将Claude Code等AI助手连接到游戏。将游戏状态查询、操作和缓存查找作为MCP工具公开。

先决条件

Python 3.10+
游戏运行 agentcpp 注入（创建 \\.\pipe\BotWithUs_{PID})

安装

cd mcp_server
pip install -r requirements.txt

依赖关系： mcp[cli]>=1.0.0, msgpack>=1.0.0, pywin32>=306

Claude代码配置

添加到您的Claude Code MCP配置中(.claude.json, claude_desktop_config.json，或通过 claude mcp add):

{
  "mcpServers": {
    "botwithus": {
      "command": "python",
      "args": ["C:/path/to/BotWithUs2/mcp_server/server.py"]
    }
  }
}

要在多个游戏实例运行时瞄准特定的游戏实例，请执行以下操作：

{
  "args": ["C:/path/to/BotWithUs2/mcp_server/server.py", "--pid", "12345"]
}

独立运行

# Auto-discover (fails if multiple instances running)
python server.py

# Target specific PID
python server.py --pid 12345

连接行为

服务器发现匹配的管道 \\.\pipe\BotWithUs_* 在启动时。只需一个游戏实例，它就会自动连接。对于多个实例， --pid 是必需的。管道连接在第一次工具调用时延迟建立，如果断开，则会自动重新连接。

可用工具

实体查询

工具	说明
`query_npcs`	按类型、名称、半径、战斗状态、移动方式查找NPC
`query_players`	查找具有相同筛选条件的玩家
`query_locations`	查找游戏对象/位置
`query_ground_items`	查找基础项目堆栈（将项目内联返回）
`query_entities`	任何实体类型的通用查询
`query_obj_stacks`	查找地面烟囱（仅手柄）
`query_projectiles`	查找活动射弹
`query_spot_anims`	查找活动点动画
`query_hint_arrows`	查找活动提示箭头

实体详细信息

工具	说明
`get_entity_info`	按手柄显示完整的NPC/玩家详细信息
`get_entity_name`	按句柄命名
`get_entity_health`	当前和最大健康状况
`get_entity_position`	瓷砖位置
`get_entity_animation`	当前动画ID
`get_animation_length`	动画序列的长度（以刻度为单位）
`get_entity_hitmarks`	主动伤害飞溅
`get_entity_overhead_text`	头顶聊天文本
`get_entity_screen_positions`	多个实体的屏幕位置
`is_entity_valid`	检查手柄是否仍然有效

UI组件和界面

工具	说明
`query_components`	按界面、项目、角色、文本、选项搜索
`get_component_text`	文本内容
`get_component_item`	按组件持有的项目
`get_component_position`	屏幕位置和大小
`get_component_options`	右键单击菜单选项
`get_component_sprite_id`	雪碧ID
`get_component_type`	组件类型
`get_component_children`	图层的子组件
`is_component_valid`	检查组件是否存在
`get_open_interfaces`	所有开放接口
`is_interface_open`	检查接口是否打开

库存和物品

工具	说明
`query_inventories`	列出所有活动库存
`query_inventory_items`	在库存中搜索项目
`get_inventory_item`	特定插槽中的项目
`get_item_vars`	插槽的项目变量
`get_item_var_value`	特定项目变量值
`get_obj_stack_items`	按手柄放置在地面堆中的物品

游戏状态

工具	说明
`get_local_player`	本地玩家信息（位置、健康、动画）
`get_account_info`	帐户详细信息（显示名称、成员状态、运行能量）
`get_game_cycle`	当前游戏滴答计数器
`get_login_state`	登录状态、进度、状态
`get_mini_menu`	当前右键菜单项
`get_grand_exchange_offers`	所有GE提供的插槽
`get_current_world`	当前世界ID
`query_worlds`	所有可用世界
`get_player_stats`	所有技能级别和XP
`get_player_stat`	单技能状态
`query_chat_history`	最近的聊天消息

游戏变量

工具	说明
`get_varp`	玩家变量值
`get_varbit`	Varbit值
`get_varc_int`	客户端变量（int）
`get_varc_string`	客户端变量（字符串）
`query_varbits`	批量读取多个变量

缓存和配置查找

工具	说明
`get_item_type`	项目定义（名称、选项、价格、插槽）
`get_npc_type`	NPC定义（名称、战斗级别、选项）
`get_location_type`	对象定义（名称、大小、选项）
`get_enum_type`	枚举键值映射
`get_struct_type`	结构参数包
`get_sequence_type`	动画序列数据
`get_quest_type`	任务定义
`get_cache_file`	原始缓存文件数据
`get_cache_file_count`	缓存索引中的文件计数

渲染和坐标

工具	说明
`get_world_to_screen`	投影瓷砖到屏幕位置
`batch_world_to_screen`	批量拼接到屏幕投影
`get_entity_screen_positions`	多个实体的屏幕位置
`get_viewport_info`	投影/视图矩阵和视口
`get_game_window_rect`	窗口位置和大小
`take_screenshot`	将游戏帧缓冲区捕获为PNG格式

行动（不安全）

这些工具可以修改游戏状态。它们是前缀 [UNSAFE] 在他们的描述中。

工具	说明
`queue_action`	排队单个游戏动作
`queue_actions`	以原子方式排队多个操作
`clear_action_queue`	清除所有待处理的操作
`set_actions_blocked`	阻止/取消阻止操作处理
`get_action_queue_size`	未决诉讼计数
`get_action_history`	最近的行动历史
`get_last_action_time`	上次操作的时间戳
`are_actions_blocked`	检查操作是否被阻止

登录和会话控制（不安全）

工具	说明
`set_world`	设置登录/跳转的目标世界
`change_login_state`	更改登录状态机
`login_to_lobby`	从登录屏幕登录大厅
`get_auto_login`	检查是否启用了自动登录
`set_auto_login`	启用/禁用自动登录
`get_humanization_enabled`	检查输入人性化是否启用
`set_humanization_enabled`	启用/禁用输入人性化
`schedule_break`	计划注销中断时间（毫秒）
`interrupt_break`	取消预定休息

脚本执行（不安全）

工具	说明
`get_script_handle`	获取客户端脚本的句柄
`execute_script`	使用int/string参数执行脚本
`destroy_script_handle`	释放脚本句柄
`fire_key_trigger`	在UI组件上按下按键输入

效用

工具	说明
`ping`	检查连接
`list_methods`	列出所有已注册的RPC方法
`compute_name_hash`	计算实体过滤的名称哈希

线路协议

MCP服务器通过Windows命名管道使用msgpack与管道服务器通信。每条消息的框架如下：

[4 bytes: little-endian uint32 body length] [N bytes: msgpack-encoded JSON body]

看 ../claudedocs/pipe_server_api.md 以获取完整的RPC方法参考。