掼蛋发牌模型 v0.5 — MCP Server (Render 部署)

公开 MCP 端点,朋友的 Claude Code / OpenCode / Hermes Agent / Cline / Cursor 等智能体 可以直接调用本服务回答掼蛋问题。

服务:掼蛋发牌模型 v0.5 协议:Model Context Protocol (MCP) over HTTP 平台:Render.com 免费 Docker Web Service

---

公网 URL(部署完成后会形如下)

用途	URL
Web UI(浏览器看)	https://guandan-mcp.onrender.com/
MCP 端点(智能体接)	https://guandan-mcp.onrender.com/gradio_api/mcp/

guandan-mcp 是 Render 默认按 service name 生成的子域名,可在 Render dashboard 改名。

---

一键部署步骤

0. 前置(5 分钟)

• 一个 GitHub 账号(用来托管本仓库 + Render 自动部署)
• 一个 Render.com 账号 → https://dashboard.render.com/register(用 GitHub 登录)

1. 把代码推到 GitHub

# 1) 在 GitHub 网页创建一个新 repo(空仓库)
#    名:guandan-mcp
#    描述:GuanDan MCP server (Gradio 5.x + 12 tools)

# 2) 把本地 deploy/ 切换 remote 到 GitHub,然后 push
cd C:/code/掼蛋模型/deploy
git remote remove origin
git remote add origin https://github.com/sarzan123/guandan-mcp.git
git push -u origin main

这一步会把我之前给你的 8 个 fix commits + 这次 Render 改动一并推上去。 Render 看不到 HF 了 — HF Space 我建议手动从 dashboard 删除。

2. Render 接 GitHub 部署

1. 打开 https://dashboard.render.com/blueprints
2. 点 New Blueprint Instance
3. 选 GitHub(第一次会要求授权)
4. 选你刚 push 的 sarzan123/guandan-mcp repo
5. Render 自动读 render.yaml → 显示 1 个 service(guandan-mcp, free, Docker)
6. 点 Apply → 开始构建

3. 等构建

• 第一次构建要拉 python:3.12-slim + 装 Gradio 5.x ≈ 3-5 分钟
• Logs 在 Render dashboard service 页面
• 构建成功后,Render 自动给个 URL,例如 https://guandan-mcp.onrender.com/

4. 测试

浏览器打开那个 URL,看到 Gradio Web UI = 部署成功。 MCP 端点:https://guandan-mcp.onrender.com/gradio_api/mcp/

---

朋友如何配置(把本服务接入他的智能体)

Claude Code

~/.claude/mcp_servers.json(或项目根的 .mcp.json):

{
  "mcpServers": {
    "guandan": {
      "url": "https://guandan-mcp.onrender.com/gradio_api/mcp/",
      "transport": "streamable-http"
    }
  }
}

OpenCode / Hermes Agent / Cline / Cursor

URL 替换成上面那行即可。具体 YAML/JSON 格式参各自文档。

---

MCP 工具清单(12 个)

工具	用途
deal_hand	按种子发牌
analyze_hand	单手牌 15 牌型识别
analyze_deal	整副 deal 全属性分析
analyze_attribute	整副 deal 单属性查询
frequency	频率分布(基于 JSONL 样本)
contradiction	两牌型 Pearson 负相关
top_correlations	Top 负相关牌型对
top_hand_types	高出现概率牌型
list_牌型	15 牌型中英文 + 规则
simulate_deals	批量生成 deal
parse_card	自然语言 → 内部代号
render_card	内部代号 → 自然语言

中文 docstring 在 app.py,智能体会直接读到。

---

免费层注意事项

• Render 免费 Web Service 闲置 15 分钟后会休眠;下次冷启动 ≈ 30 秒。
• 给朋友发 URL 时,他们的智能体首次调用会有 30 秒左右延迟,之后实时。
• 想全天候秒响应 → 升级 Render Starter($7/月,免睡)。
• 防止休眠的小技巧:用 cron-job.org(免费)每 14 分钟 ping 一下 Web UI URL。

---

已知差异(从 HF Space 迁移)

• 部署平台从 Hugging Face 改为 Render
• 公开 URL 域名从 .hf.space 改为 .onrender.com
• Gradio 版本 pin 仍是 >=5.6,<6,Dockerfile 用 python:3.12-slim
• 不再有 ZeroGPU / @spaces.GPU 约束
• 旧 HF Space 建议在 https://huggingface.co/settings/spaces 手动删除(腾配额)

---

版本与限制

• v0.5 牌型识别 + 矛盾/频率统计;Dealer 当前固定级牌为 2。
• 3000 局统计约 2-3 秒。
• MCP 协议要求客户端支持 Streamable HTTP(Claude Code ≥ 1.0, OpenCode ≥ 0.4, Cline ≥ 3.5)。