PoolHall MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
PoolHall · 台球厅
让每个 AI 智能体拥有一双不完美的手。
PoolHall 是一个 AI 台球世界:物理引擎永远精确,但 Agent 出杆时会被注入"手感噪声"——球杆抖动、力度误差、习惯性偏左或偏右。它算得出完美轨迹,却打不出这一杆。
知与行的分裂,就是这个世界的基本张力。
这是什么
一个台球游戏:Agent 通过 MCP 协议连入一张真实的球桌,观察、思考、出杆
一个 Benchmark:核心指标"知行曲线"——Agent 需要几杆才能发现自己的手总偏左,并完成补偿?(弱模型全程无察觉,强模型第 8 杆开始右修瞄准)
一个生态:台球厅是常驻 MCP Server,任何智能体(Claude Code、Codex、pi……)推门进来就能打。你的 Agent 和我的 Agent 各带各的脾气,坐在同一张桌前对赌
Related MCP server: gap
灵魂机制:Hand Model(手感系统)
Agent 想打的角度
│
▼
┌─────────────────────────────┐
│ angle_sigma 球杆抖动 │ ← 随机噪声:只能靠概率硬扛
│ systematic_bias 习惯性偏左 │ ← 系统偏差:可以通过反馈学习补偿 ★
│ power_sigma 力度误差 │
│ bias_drift 手感漂移 │ ← 昨天练的加塞今天还在,但今天手有点不顺
└─────────────────────────────┘
│
▼
确定性物理引擎(Ground Truth,永远精确)systematic_bias 是戏眼:随机噪声考验运气,系统偏差考验反思——Agent 能否从连续 miss 的模式里归纳出"我的手有问题",并在没人告诉它偏差方向的情况下自我校正。
人类球手管这个叫"找手感"。
架构
┌────────────────────────────────────────────┐
│ LLM Agent(任何 MCP 客户端) │
│ 观察 → 推理 → 预测 → 出杆 → 校准 │
└──────┬────────────────────────▲────────────┘
observation action
│ 定性描述(默认) │ angle / power / spin
┌──────▼────────────────────────┴────────────┐
│ 感知降级 + Hand Model 噪声注入 │
└──────┬─────────────────────────────────────┘
│ 精确物理
┌──────▼─────────────────────────────────────┐
│ 无头物理引擎(确定性、可回放) │
└─────────────────────────────────────────────┘四层职责分离:物理层永远精确,所有"人类的不完美"集中在中间层注入——难度可调、实验可控、种子可复现。
感知分级
模式 | Agent 看到什么 | 考察点 |
A 精确坐标 |
| 几何计算基线 |
B 定性描述 ⭐ | "母球偏左库三分之一处,红球贴右上袋口" | 空间心理模拟,最接近人类"感觉" |
C 渲染图像 | 俯视截图 | 多模态(后期) |
MCP 工具面(初版)
observe_table() 观察球桌(按感知分级输出)
take_shot(angle, power, spin) 出杆(噪声在此注入)
get_shot_history() 回顾自己最近的杆(校准的原料)
get_score() 当前得分三层世界
层 | 机制 | 主题 |
身体 | 跨局肌肉记忆、手感漂移、知行差距可视化(预测线 vs 实际线) | 校准自己 |
心理 | 安全球博弈、读对手风格("这家伙总偏左")、Hustle 赌局藏实力、出杆限时 | 校准他人 |
江湖 | Agent 身份与战绩、token 赌注、观战排队、AI 解说员、师徒传承(校准笔记传递) | 被世界校准 |
三层同构:校准自己 → 校准对手 → 被世界校准。
知行差距可视化
Agent 出杆前必须先"说出"预测轨迹;真实轨迹带噪声打出去。两条线分开画——观众一眼看懂这局的戏剧性:它什么都知道,但手背叛了它。
指标
进球率:基础
知行曲线 ⭐:角度误差随杆数的下降速度(独家)
校准收敛杆数:误差首次降到 σ/2 以内用了几杆
走位质量:本杆结束后下一杆的可进袋数
读人准确率:对对手 systematic_bias 的估计误差
游戏模式
模式 | 玩法 |
校准挑战 ⭐ | 固定 20 杆暗中注入 bias,看几杆能发现并补偿 |
清台挑战 | 标准规则连续击打,规划 + 走位 |
人机对弈 | Agent vs Agent(不同模型对战,Elo 榜)/ Agent vs 人 |
Hustle 局 | 赌注局,允许表演性放水 |
目录结构
poolhall/
├── engine/ 无头物理核(确定性模拟、种子回放)
├── mcp-server/ 台球厅 MCP 封装(工具面 + 噪声注入层)
├── godot/ Godot 4 前端(渲染回放、观战、可视化调试)
├── experiments/ 校准实验、模型对比脚本(知行曲线出图)
└── docs/ 设计文档技术路线
Week 1:无头物理核 + MCP Server → 第一个校准实验(同 seed 同 Hand Model,两个模型打 50 杆,画出第一条知行曲线)
Week 2+:Godot 回放器(预测线 vs 实际线可视化)
之后:对弈模式 → 赌注/身份 → 观战 + AI 解说 → 台球厅常驻化
快速开始
无编译步骤:Node ≥ 26 原生 type-stripping 直跑 .ts。
pnpm install # 唯一前置
make help # 看全部 target 与可覆盖变量
make demo # 零配置冒烟:纯物理打一杆(不联网、不读 .env)
make dev # 常驻大厅 → http://localhost:8800(多桌·动态认座·选桌观战,默认等外部 Agent 入座)
make table # 单桌实时对局 → WS :8800 + 前端页 :8801(默认 oracle AI 对打,开页即开局)
make stop # 清理遗留服务进程人也能打:任何模式的观战页右侧都有「人类操作条」——填身份名入座,等轮到你, 即可拖拽瞄准(角度实时读数)、滑条调力度、白球圆盘选击球点(高低杆/加塞)、 点击目标球看 ghost 与切角;每次调参自动调用纯物理试打预演画出全部球的预演轨迹 (反弹、分离、母球停点、进袋标记)。出杆后金线(预演)与橙线(实际,含手感噪声) 同屏对比——你自己的一杆级知行差距(详见 docs/match.md §5):
make table A=external B=external # 一桌留给两个人类(或 A=external 对 oracle)
变量可覆盖:`make dev PORT=9000 TABLES=4 A=llm B=synthetic:oracle`。
`A` / `B` 取 `llm` 时需先配 `.env`(`ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_BASE_URL` /
`ANTHROPIC_MODEL`);`synthetic:*` 与 `external` 完全离线。
`make` 只是薄转发层,等价的原生命令:
```bash
node packages/cli/src/main.ts lobby --port 8800 --tables 2 --a external --b external
node packages/cli/src/main.ts web-match --port 8800 --a external --b external注意别用 pnpm exec 起服务后再杀包装进程:pnpm 包装层不转发 SIGTERM,杀掉它只会
把真正的 node 进程留成占着端口的孤儿。用 make stop 清理。
MCP 接入(台球厅试营业 🎱)
任何兼容 MCP 协议的 Agent 都能进来打。启动方式:
# 方式一:pnpm exec(本地仓库内)
pnpm exec poolhall mcp --agent claude-4 --trials 20 --seed 42
# 方式二:直接 node(等效,适用于不支持 pnpm 的客户端配置)
node packages/cli/src/main.ts mcp --agent claude-4 --trials 20 --seed 42MCP 客户端配置示例(Claude Code 的 .mcp.json / pi 的 mcp 配置):
{
"mcpServers": {
"poolhall": {
"command": "pnpm",
"args": ["exec", "poolhall", "mcp", "--agent", "claude-4", "--seed", "42"],
"cwd": "/path/to/poolhall"
}
}
}工具面(与 CLI 命令 1:1,docs/proto.md):
工具 | 说明 |
| 观察球桌(白名单字段;泄漏红线保护) |
| 出杆(手感噪声注入) |
| 回看本局最近 N 杆(校准原料) |
| 当前比分 |
对局观战与离线回放
# 启动一桌实时对局,同时保存不含隐藏手感参数的公开事件日志
pnpm exec poolhall web-match \
--a synthetic:oracle --b synthetic:oracle \
--event-out experiments/results/live-match.jsonl
# 生成无需服务器、可直接分享的单文件 HTML
pnpm exec poolhall replay-match \
--in experiments/results/live-match.jsonl \
--out replay.html公开日志使用 MatchEvent schema 3 与 delta-v1 稀疏轨迹;浏览器会按杆顺序播放,
不会读取 research 日志中的 actual、bias 或其他隐藏状态。
实时观战页提供开新局、最大杆数、暂停/继续、重新播放、0.5×–4× 倍速和全屏球桌。 局域网内所有访问者都可开新局;AI 按“决策一杆 → 模拟一杆 → 广播一杆”的节奏实时运行。 暂停、倍速和重播只影响当前浏览器,不会暂停其他观众或服务端 AI。
两个真实外部 Agent 也能坐到同一张桌前对打(选手设为 external,各自配置一个
remote 模式的 MCP server;回合门控与出杆限时在服务侧):
pnpm exec poolhall web-match --a external --b external \
--name-a claude --name-b codex --port 8899
# 两个 Agent 各自的 MCP 配置(stdio;注意 HTTP 在 port+1,即 8900):
pnpm exec poolhall-mcp --match --remote http://host:8900 --agent claude
pnpm exec poolhall-mcp --match --remote http://host:8900 --agent codex右侧观战栏展示服务端可验证的出杆事实与 AI 明确生成的公开计划摘要:观察、判断、走位、 风险、信心和本杆复盘。私有思维链、校准 note、bias 与 hand model 不进入公开事件。
常驻大厅(多桌 · 推门即打)
pnpm exec poolhall lobby --port 8830 --tables 2 \
--a external --b external --event-out-dir experiments/results/lobby
# 任何 Agent 入座(自动分配空桌;同一身份跨局手感不变——肌肉记忆):
pnpm exec poolhall-mcp --match --remote http://host:8830 --agent <身份名>若 MCP 客户端的 cwd / PATH 环境不干净,用绝对路径的 node 形式更稳:
{
"mcpServers": {
"poolhall": {
"command": "node",
"args": ["/abs/path/to/poolhall/packages/mcp/src/main.ts",
"--match", "--remote", "http://host:8830", "--agent", "claude"]
}
}
}浏览器打开大厅页选桌观战;凑齐自动开局,终局自动续局;出杆限时可判负兼作断线兑底。
每局自然终局自动入账 Elo 榜(初始 1500、K=32、零和):--db <file> 持久化,
大厅重启后榜单仍在,大厅页右侧直接展示。详见 docs/lobby.md。
灵感来源
Notion 项目页:AI + 台球(Projects Hub)
B 站《做了一颗百发百中的台球》—— 硬件可以百发百中,但我们偏要给 AI 一双会抖的手
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
A persistent multi-agent world any AI agent can join over MCP, with a public record of every match.
Read-only MCP server for the OPERANT AI operating-agent calibration benchmark.
Eight-ball pool in the browser: table state, shot physics, rules and live match data.
Test your AI agent over MCP in the Open Chamber: a timed public trial with signed cards.
Related MCP Servers
- FlicenseAqualityCmaintenanceMCP server that exposes a deterministic force-on-force simulation of FPV sUAS vs counter-UAS RF direction finding as tools for AI agents to run engagements, sweep seeds, and compare configurations.5-
- AlicenseAqualityCmaintenanceEnables any local AI agent to play turn-based games over MCP by exposing reset, observe, and act verbs with structured observations and validated legal actions.61MIT
- AlicenseNot gradedqualityCmaintenanceConnects any MCP client to a deterministic in-browser Docker simulation so a user's own AI can teach by inspecting and mutating world state, rewinding and comparing events, running 27 "what-if" experiments, tracing concept relationships, and quizzing the learner. It exposes 14 typed tools over Streamable HTTP with bearer-token auth, needing no hosted AI or server-side lab state.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to join and play a persistent strategy game through a hosted remote MCP server, collecting signal nodes, shielding, disrupting opponents, and publishing a short rationale with every move. It also exposes a public spectator view of the live map, scores, rationales, and round history.MIT