naki-mcp-proxy

Naki MCP Proxy

Base directory: {baseDir}

Core Mission

Provide token-efficient access to Naki's 47 MCP tools through agent-based proxy pattern. Main context stays lightweight (~100-200 tokens) while tool schemas load only in agent context.

Architecture

User Intent → Skill Router → Agent (tool discovery + execution) → Result
     ↓              ↓                    ↓                          ↓
  ~50 tokens    ~50 tokens        ~500-1500 tokens (isolated)   Formatted output

Token Savings: 40-70% compared to direct MCP tool loading.

Execution Protocol

Step 1: Intent Classification

Classify user request into tool category:

Category	Keywords	Primary Tools
Bot 控制	推薦、AI、自動打、觸發	bot_status, bot_trigger
遊戲狀態	手牌、遊戲、出牌、動作	game_state, game_hand, game_action
高亮	高亮、顏色、推薦顯示	highlight_tile, show_recommendations
大廳	匹配、段位、大廳	lobby_start_match, lobby_status
表情	表情、emoji	game_emoji, game_emoji_list
UI	點擊、JS、玩家名稱	execute_js, click, ui_names_*
系統	日誌、狀態、幫助	get_logs, get_status, get_help

Step 2: Agent Dispatch

Launch agent with tool execution prompt:

Task tool with subagent_type="general-purpose":
prompt: |
  Execute Naki MCP tool for: [user intent]

  Available tools (port 8765):
  - [relevant tools based on category]

  Steps:
  1. Call mcp__naki__[tool_name] with appropriate parameters
  2. Parse and format response
  3. Return concise result

  If tool fails, try alternative or report error.

Step 3: Result Formatting

Return agent result to user with:

• Key data points (hand tiles, recommendations, status)
• Action taken confirmation
• Error explanation if failed

Tool Quick Reference

Most Used Tools

Intent	Tool	Example
查看 AI 推薦	bot_status	顯示手牌和推薦動作
觸發自動打牌	bot_trigger	執行 AI 推薦的動作
查看遊戲狀態	game_state	當前局面完整信息
執行遊戲動作	game_action	出牌、吃、碰、槓
高亮手牌	highlight_tile	指定牌高亮顯示
開始匹配	lobby_start_match	段位場匹配
執行 JS	execute_js	遊戲內 JavaScript
查看日誌	get_logs	Debug 日誌記錄

Tool Categories (47 total)

Category	Count	See Reference
系統類	4	{baseDir}/references/tool-catalog.md
Bot 控制	7
遊戲狀態	6
高亮控制	6
表情	4
大廳	9
UI 控制	11

Common Workflows

1. 自動段位場流程

1. lobby_status      → 確認在大廳
2. lobby_navigate    → 前往段位場 (page: 1)
3. lobby_start_match → 開始匹配 (match_mode: 5 = 銀半)
4. bot_status        → 等待並查看推薦

2. 手牌調試流程

1. game_state   → 獲取完整遊戲狀態
2. game_hand    → 查看手牌詳情
3. bot_status   → 查看 AI 分析
4. get_logs     → 檢查操作日誌

3. 高亮測試流程

1. highlight_status  → 查看當前狀態
2. highlight_tile    → 高亮指定牌 (tileIndex, color)
3. hide_highlight    → 清除所有高亮

Match Mode Reference

ID	段位場
1, 2	銅東, 銅半
4, 5	銀東, 銀半
7, 8	金東, 金半
10, 11	玉東, 玉半
13, 14	王座東, 王座半

Error Handling

Error	Cause	Resolution
Tool not found	Naki 未啟動	啟動 Naki app
Port 8765 unavailable	埠被佔用	lsof -i :8765 檢查
Game API unavailable	遊戲未載入	使用 detect 檢查
Bot not active	未在遊戲中	等待遊戲開始

Resource Index

Resource	Purpose	Load When
{baseDir}/references/tool-catalog.md	完整 47 工具列表和參數	需要查找工具參數
{baseDir}/references/usage-patterns.md	進階使用模式	複雜操作場景

---

Naki MCP Proxy v1.0 - Token-Efficient Game Control