naki-mcp-proxy

Token-efficient proxy for Naki's 47 MCP tools. Routes user intent to optimal MCP tool via agent isolation, saving 40-70% tokens. Use for any Naki game control, bot status, or UI operation.

SKILL.md

GitHub

Naki MCP Proxy

Base directory: {baseDir}

<IMPORTANT> 每一次 Naki 查詢都必須真的連到正在執行的 Naki MCP server。先做 live `tools/list`,再依該次回傳的 schema 呼叫實際工具。除了「目前有哪些工具」本身可由 `tools/list` 回答外,只讀 repo、skill、catalog、舊 log 或先前結果都不算完成查詢。

若 Naki 無法連線,回報「live Naki 不可用/本次未驗證」並停止;不可拿靜態文件或記憶內容冒充即時結果。 </IMPORTANT>

Current contract

  • Default endpoint: http://127.0.0.1:8765/mcp.
  • 2026-08-01 的 live registry 基準為 42 tools;2026-08-02 移除 6 個 highlight 失敗樁後靜態計數 38,其後新增工具至 43,2026-10-13 移除三個過時匹配工具後為 40。數字、名稱與參數一律以每次 live tools/list 為準。
  • 協定雙版本並存(2026-08-02 升級):請求 params._meta 帶 io.modelcontextprotocol/protocolVersion 就走 2026-07-28(stateless、無 handshake);不帶則走 initialize handshake 的 legacy 語意(2025-03-26 ~ 2025-11-25)。兩條路徑的工具集完全相同。
  • 工具結果讀 result.structuredContent(真的 JSON 物件)。content[0].text 只是同一份 JSON 的字串化 fallback;不要再對回應做 tr -d '\\' 去跳脫。每個工具都有 outputSchema,但它只宣告程式碼保證的欄位(additionalProperties: true),不是完整欄位清單。
  • 走 2026-07-28 時:server/discover 可一次取得 supportedVersions / capabilities / serverInfo;result 帶 resultType: "complete" 與 _meta['io.modelcontextprotocol/serverInfo'];tools/list 帶 ttlMs + cacheScope;版本不支援回 -32022(HTTP 400)並列出支援版本。
  • 參數錯誤回的是 Tool Execution Error(isError: true 的正常 result),不是 JSON-RPC error——看到 isError 要當成失敗,不要因為 HTTP 200 就當成功。
  • 非 loopback Origin 的請求一律 403(DNS rebinding 防護)。curl 與 MCP client 不送 Origin,不受影響。
  • 雀魂頁面是 Unity WebGL,不是 Laya。window.Laya、GameMgr、uiscript、view.DesktopMgr、cfg、app.NetAgent 都不是可用查詢面。
  • 遊戲狀態由 Naki 攔截 WebSocket、解析 Liqi protobuf 後累積在 Swift state;動作由 Naki 組 Liqi REQUEST 並送到正確 gateway。
  • execute_js 只用於 Unity/page/WebSocket/WebGL 的唯讀 probe。遊戲狀態走 game_*,動作走 game_action_verify;禁止用 JS 重造遊戲物件、raw request 或座標點擊。

Required execution protocol

1. Connect and discover

對每一個使用者 request:

  1. 連到 live Naki MCP endpoint。
  2. 呼叫 tools/list。
  3. 在這次回傳中確認工具存在,並採用 live inputSchema;不可依 catalog 猜參數。
  4. 若問題不是 registry 本身,再呼叫至少一個能回答該問題的 live Naki tool。

2. Choose the current route

Intent Read/query route Mutation route
Server/工具 get_status, get_help clear_logs 僅在明確要求時
Bot/AI bot_status, bot_ops, bot_deep bot_trigger, bot_chi, bot_pon, bot_sync
對局狀態 game_state, game_hand, game_ops game_action_verify;必要時 game_discard/game_action
大廳 lobby_status, lobby_match_sids, lobby_account_info, lobby_server_time lobby_start_unified_match, lobby_cancel_unified_match, heartbeat tools
友人房 room_info room_create, room_add_robot, room_start, room_join, room_leave, room_quick_test
表情 game_emoji_listen(clear=false) game_emoji 或 clear=true
Unity 頁面 execute_js 的唯讀 probe 不用 JS 改遊戲狀態或模擬點擊

純查詢一律使用 read/query route。會影響帳號、排隊、房間、對局、連線或 log 的工具,只有在使用者明確要求該副作用時才能呼叫。

3. Execute against live Naki

若需要 agent isolation,派出的 agent 也必須遵守同一條 live 規則:

Connect to the configured Naki MCP server.
1. Call live tools/list for this request.
2. Select only a tool present in that response and use its returned schema.
3. Call the live tool; do not answer from repo documentation or earlier output.
4. Return the raw verification fields plus a concise interpretation.
5. If connection fails, report live Naki unavailable and do not infer a result.

4. Verify the meaning of the result

  • game_state/game_hand/game_ops 是 live Naki process 內的 protocol-layer snapshot,不是每次向雀魂 server 重新抓一份完整 snapshot;回報時要保留這個資料語意。
  • 動作前先讀 game_ops,確認 server 提供的 sequence、type、combination。
  • 優先用 game_action_verify。sent.success=true 只表示 bytes 已交給 WebSocket,不等於 server 接受;要看同 msgId RESPONSE、verified、oplist/snapshot 推進,以及終局時的權威 action。這些欄位都在 structuredContent 裡,直接讀,不要從 content[0].text 解字串。
  • 只有工具實際回傳的資料可標「已查到」。連線失敗、無對局或 snapshot 缺失都要標「未驗證」。

Current tool shape(靜態計數 40;live tools/list 才是真值)

Category Count Notes
System 6 status/help/logs/replay
Bot 7 Swift state + Liqi actions
Game 8 state/hand/ops/action/confirm/vote
JavaScript 1 read-only Unity probe
Lobby 8 .lq.Lobby.*
Anti-idle 1 Swift heartbeat scheduler
Room 7 protocol room flow
Emoji 2 Liqi broadcast send/capture

高亮已經沒有 MCP 工具(6 個失敗樁於 2026-08-02 移除,呼叫回 Unknown tool)。Naki 內建的 window.__nakiHighlight WebGL renderer 由 Swift 直接驅動,不要宣稱 MCP 高亮呼叫成功。

Removed routes

Never call or recreate these old Laya/UI routes:

detect, explore, test_indicators, click, calibrate
ui_names_status, ui_names_hide, ui_names_show, ui_names_toggle
lobby_match_status, lobby_navigate, lobby_idle_status, lobby_account_level
game_emoji_list, game_emoji_auto_reply

Do not replace them with execute_js that reads DesktopMgr, mutates the canvas, or clicks coordinates.

Resource index

Resource Purpose
{baseDir}/references/tool-catalog.md 2026-08-01 42-tool snapshot (static count now 40) and safety classification; routing hint only
{baseDir}/references/usage-patterns.md Live-only workflows and verification rules

Static resources help choose what to query; they never replace a live Naki call.