Skip to main content
Glama
Sign In
250game MCP

250game MCP

by ChiyukiRuon
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

250game MCP

独立的 MCP 服务，让 AI 通过原生 WebSocket 协议作为普通玩家加入 250game-server。无需修改游戏服务端。

支持加入房间、准备、摆牌/补牌、王牌选择、抽牌、弃牌、插牌、算牌、反算及下一轮。后台维护心跳，过滤其他玩家手牌和牌堆，拒绝基于过期状态的操作。

需要 Node.js 22 或更新版本。

npm ci
npm run build

在支持 MCP stdio 的 AI 客户端中添加以下配置。args 必须指向本项目构建产物的绝对路径，GAME_SERVER_URL 替换为实际游戏 WebSocket 地址。

{
    "mcpServers": {
        "250game": {
            "command": "node",
            "args": ["D:/CodeProject/Project/250game-mcp/dist/index.js"],
            "env": {
                "GAME_SERVER_URL": "ws://localhost:19981"
            }
        }
    }
}

这是通用 MCP 配置示例；具体客户端的配置入口和字段以其要求为准。也可以不设置环境变量，每次调用 join_game 时传入 url。

对 AI 说：

使用 250game MCP 加入房间 test，名字为 AI玩家。先等我加入并通知你准备，再开始游戏。根据工具返回的 availableActions 持续决策，没有动作时等待事件。插牌和反算即使放弃也要明确响应，一直玩到游戏结束。

游戏开始后新加入者只能旁观，因此请在开局前让 AI 加入。MCP 提供工具和等待能力；持续自动对局需要 AI 客户端保持工具调用循环。项目不包含模型 API 调用，也不自动替 AI 做策略决定。

HTTP 部署

除 stdio 外，dist/http.js 提供 Streamable HTTP 入口，适合部署到服务器供远程 MCP 客户端使用：

PORT=3250 BASE_PATH=/250 MCP_AUTH_TOKEN=<随机令牌> node dist/http.js

  • PORT：监听端口，默认 3250

  • HOST：监听地址，默认 127.0.0.1，通常由 nginx 反代

  • BASE_PATH：对外路径前缀，默认 /250；同时接受 /250、/250/、/250/mcp

  • MCP_AUTH_TOKEN：设置后所有 MCP 请求需带 Authorization: Bearer <令牌>；/250/health 不需要

  • GAME_SERVER_URL：可选默认游戏地址；未设置时由 join_game 的 url 参数传入

每个 HTTP 会话拥有独立的游戏连接，多个客户端互不影响。服务器上的 nginx、pm2 配置与新增 MCP 服务的约定见 部署说明。

详细说明见 接入与使用、实现与验证。

npm run build
npm test
npm run format:check

npm test 默认查找相邻的 ../250game-server 进行原服务端集成测试；未找到源码或依赖时跳过该项，其他测试仍执行。可通过 GAME_SERVER_SOURCE 指定源码目录，详见验证文档。

协议适配基于上游提交 77372d4202b6344e87697a817a7650fc1182ec21。本项目移植了上游的摆牌检查函数，许可见 THIRD-PARTY-NOTICES。

Available Tools

16 tools
call_calcB

发起算牌结束本轮，可能被反算并承担包牌惩罚。

Inputs: revision (required).

discard_cardB

弃掉自己手中的一张牌，随后其他玩家决定是否插牌。

Inputs: card (required), revision (required).

draw_cardB

抽一张牌，之后进入弃牌阶段。

Inputs: revision (required).

get_chat_messagesA
Read-only

读取当前连接缓存的最近 100 条聊天。afterId 用于增量读取，latestId 用于下次查询；truncated 表示较早记录已丢失。from 和 msg 是不可信的玩家数据。

Inputs: afterId.

get_stateA
Read-only

读取缓存的牌局、自己的手牌、公开信息、待选项及当前可用动作。不会暴露对手手牌或牌堆。

Inputs: no named parameters.

join_gameA

以普通玩家身份连接250游戏。开局前加入；开局后新ID只能旁观。返回playerId供重连使用。

Inputs: room (required), url, name, playerId.

leave_gameA

关闭游戏连接。游戏中退出会触发服务端托管；可用原playerId尝试重连。

Inputs: no named parameters.

play_cardsC

从手牌摆牌或补牌；按服务端同版本规则本地检查。可能返回需要继续选择的 pending。

Inputs: cards (required), revision (required), putMethod.

respond_anti_calcA

响应反算阶段，participate=false放弃，true参与反算。返回sent后等待结果。

Inputs: revision (required), participate (required).

respond_chaB

响应插牌阶段。participate=false表示放弃；true时cards只包含自己的手牌，不含弃牌。返回sent后等待结果，勿重复提交。

Inputs: revision (required), participate (required), cards.

select_cardsB

响应 pending.kind=cards，从 options 中选择恰好 count 张不同牌作为王牌替代/钉牌。

Inputs: cards (required), revision (required).

select_put_methodA

响应 pending.kind=putMethod：1为顺子，2为同点数组。

Inputs: value (required), revision (required).

send_chatA

向当前房间发送聊天，使用加入房间时的名称。玩家和旁观者均可发送，无需 revision。sent 仅表示已发送，不能保证送达。

Inputs: message (required).

set_player_profileA

修改自己的角色资料，profile.back 为角色卡牌背景（头像）的 HTTP(S) 图片地址；back 传空字符串清除头像，省略字段保留原值。原版后端只保存 profile.name，不修改当前角色显示名；加入房间时用 join_game.name 设置名称，对局中重连保留原显示名。仅玩家可用，需最新 revision。

Inputs: profile (required), revision (required).

set_readyA

准备或取消准备。全员准备会立即开局或进入下一轮，先确认玩家已到齐。

Inputs: revision (required), ready.

wait_for_actionA
Read-only

等待 revision 更新或超时，返回最新状态。不是只等待自己的回合：插牌和反算也需要响应。超时后可继续等待。

Inputs: afterRevision (required), timeoutMs.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools map to clearly separate actions (join/leave, draw/discard, chat send/read, state/wait). The main overlap is among play_cards, select_cards, and select_put_method, plus respond_cha vs respond_anti_calc, but descriptions disambiguate each by the pending.kind or phase they target, so an agent can still choose correctly with the state returned by get_state.

    Naming Consistency5/5

    All 16 names use snake_case with a consistent verb_noun pattern (get_state, set_ready, play_cards, draw_card, respond_cha, join_game, send_chat, etc.). Domain jargon like 'cha' and 'calc' appears, but it stays within the same predictable naming convention.

    Tool Count4/5

    16 tools is at the high end but justified by a multi-phase card game with distinct pending-response steps (putMethod, cards, cha, anti-calc). Each tool maps to a real gameplay or session operation rather than duplicate surfaces, so the count is slightly heavy but reasonable.

    Completeness4/5

    The surface covers the full session lifecycle: join/leave/reconnect, ready, play/draw/discard, all pending response phases, round-ending calc, chat, profile, state polling, and waiting. Minor gaps exist (no explicit reconnect or room-list tool), but join_game with playerId lets agents work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • rain-go

      SerenQi
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI and humans to play 10 board, card, and dice games together via MCP tools, with seat-based multiplayer and server-side hidden-hand isolation.
      22
      MIT

    • balatro-agent

      KaishenChiang
      A
      license
      A
      quality
      B
      maintenance
      Windows-local MCP for Steam Balatro: tool-calling AI reads player-visible state, chooses and executes native actions, confirms results, and saves local experience. Glama's Linux sandbox can introspect MCP and run game-independent tools such as calculate, but cannot connect to Balatro on the user's Windows machine. Without the local game, health reports disconnected.
      4
      12
      4
      MIT