TTTTT-垃圾话
一款双界面井字游戏 垃圾话是游戏的一部分！ 实施 模型上下文协议（MCP） 使像Claude Code这样的AI代理能够通过标准化的工具界面玩AND嘲讽。
🎯 项目状态：MCP服务器已完成✅
175+项测试通过 | 100%功能覆盖率 | 生产准备就绪 | 💬 垃圾话已启用！
什么在起作用
- ✅ 具有获胜检测功能的完整井字游戏逻辑
- ✅ 实时垃圾话系统 -从UI或MCP发送嘲讽！
- ✅ SQLite数据库持久性（游戏状态、移动、嘲讽）
- ✅ 服务器发送事件（SSE）用于实时更新
- ✅ JSON-RPC 2.0协议的实现
- ✅ 所有6个MCP工具均已完全实施和测试(
taunt_player包括！) - ✅ 带stdio传输的MCP服务器二进制文件
- ✅ 带有实时UI更新的REST API后端
- ✅ Yew/WASM前端UI，带垃圾话输入面板
- ✅ 全面的测试覆盖率（175+测试通过）
- ✅ 生产准备就绪，采用热装开发模式
🚀 快速开始
发展模式
./scripts/dev.sh通过热重新加载启动两台服务器：
- 后端API+MCP服务器：http://localhost:3000
- 前端开发服务器：http://localhost:8080
生产建设
./scripts/build.sh构建优化的后端二进制和前端WASM资产。
生产服务器
./scripts/serve.sh运行生产服务器（同时为API和静态前端提供服务）。
测试
# Run all tests
cargo test --all
# Test specific package
cargo test --package backend
cargo test --package frontend
cargo test --package shared
# WASM tests (requires wasm-pack)
cd frontend
wasm-pack test --headless --firefox🏗️ 建筑
┌─────────────────────────────────────────────────────┐
│ Claude Code (AI) │
│ (MCP Client) │
└──────────────────────┬──────────────────────────────┘
│ JSON-RPC 2.0 via stdio
▼
┌─────────────────────────────────────────────────────┐
│ MCP Server (Rust Binary) │
│ ┌────────────────────────────────────────────┐ │
│ │ 6 Tools: view_game_state, get_turn, │ │
│ │ make_move, taunt_player, restart_game, │ │
│ │ get_game_history │ │
│ └────────────────────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ Game State Manager │ │
│ │ (Coordinates game logic + persistence) │ │
│ └────────────────────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────┐ │
│ │ SQLite Database (game.db) │ │
│ │ • Games table (state, players, status) │ │
│ │ • Moves table (history with timestamps) │ │
│ │ • Taunts table (AI messages to player) │ │
│ └────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
▲ ▲
│ │
│ REST API │
│ │
┌────────┴─────────┐ ┌─────────┴────────┐
│ Browser (UI) │ │ AI Agent (MCP) │
│ (Yew/WASM) │ │ (Claude Code) │
└──────────────────┘ └──────────────────┘📦 项目结构
game-mcp-poc/
├── backend/ # Rust backend (MCP server)
│ ├── src/
│ │ ├── bin/
│ │ │ └── game-mcp-server.rs # Binary entry point
│ │ ├── db/ # Database layer
│ │ │ ├── schema.rs # SQLite schema
│ │ │ └── repository.rs # CRUD operations
│ │ ├── game/ # Game logic
│ │ │ ├── board.rs # Board state
│ │ │ ├── logic.rs # Win detection
│ │ │ ├── player.rs # Player assignment
│ │ │ └── manager.rs # Game coordinator
│ │ └── mcp/ # MCP implementation
│ │ ├── protocol.rs # JSON-RPC 2.0
│ │ ├── tools.rs # Tool handlers
│ │ └── server.rs # Server loop
│ ├── tests/
│ │ └── mcp_integration.rs # Integration tests
│ └── Cargo.toml
├── frontend/ # Yew/WASM frontend
│ └── src/lib.rs # Yew components
├── shared/ # Shared types (Player, Cell, GameState, etc.)
├── docs/ # Comprehensive documentation
│ ├── architecture.md
│ ├── prd.md
│ ├── design.md
│ ├── mcp-setup-and-testing.md
│ └── status.md
├── scripts/ # Build and dev scripts
│ ├── dev.sh # Development mode with hot-reload
│ ├── build.sh # Production build
│ └── serve.sh # Production server
└── test-mcp-manual.sh # Manual testing script🎮 MCP工具
服务器为AI代理提供了6个工具：
1. view_game_state
返回完整的游戏状态（棋盘、玩家、状态、历史、嘲讽）
输入: {} 输出：完整游戏状态对象
2. get_turn
返回轮到谁（X/O，人类/AI）
输入: {} 输出: {currentTurn, isHumanTurn, isAiTurn}
3. make_move
在董事会上采取行动
输入: {row: 0-2, col: 0-2} 输出: {success, gameState, message}
错误：越界、牢房被占用、游戏结束
4. taunt_player
向人类玩家发送嘲讽信息
输入: {message: string} 输出: {success, message}
5. restart_game
重新启动新游戏
输入: {} 输出: {success, gameState, message}
6. get_game_history
返回所有已完成的动作
输入: {} 输出: {moves: [{player, row, col, timestamp}]}
🔧 配置Claude代码
MCP配置文件
macOS/Linux: ~/.config/claude-code/mcp.json 视窗: %APPDATA%\claude-code\mcp.json
{
"mcpServers": {
"tic-tac-toe": {
"command": "/absolute/path/to/game-mcp-poc/target/release/game-mcp-server",
"args": [],
"env": {
"GAME_DB_PATH": "/path/to/game.db",
"RUST_LOG": "info"
}
}
}
}环境变量
GAME_DB_PATH：SQLite数据库位置（默认值：game.db)RUST_LOG：日志记录级别（跟踪、调试、信息、警告、错误）
重新启动Claude代码
配置后，重新启动Claude Code以加载MCP服务器。
🧪 使用Claude代码进行测试
基本游戏流程
- 开始游戏:
User: "Let's play tic-tac-toe! Show me the board."- 采取行动:
User: "I'll take the center (row 1, col 1)"- 轮到AI了:
User: "Your turn!"- AI嘲讽:
User: "Can you taunt me?"- 查看历史:
User: "Show me all the moves so far"- 玩到赢/平局
- 重启:
User: "Let's play again!"📊 测试覆盖率
单元测试（79项测试）
- 游戏逻辑 （24项测试）：棋盘操作、获胜检测、玩家分配
- 数据库 （9个测试）：模式、CRUD操作、持久性
- 游戏管理员 （10个测试）：状态协调、移动验证
- MCP协议 （10个测试）：JSON-RPC解析、验证、序列化
- MCP工具 （16个测试）：所有工具+错误场景
- MCP服务器 （12个测试）：请求处理、调度、边缘情况
集成测试（12项测试）
- 模拟AI客户端：通过子进程+stdio进行完整游戏
- 错误场景：无效移动、边界检查、游戏超限检测
- 状态持久性：服务器重启时的数据库持久性
手动测试
- CLI脚本 (
test-mcp-manual.sh)：使用视觉输出测试所有6个工具 - 所有测试均已通过 ✅
🛠️ 发展
先决条件
- Rust 2024版本（稳定版）
- SQLite 3
trunk（由构建脚本自动安装）wasm-bindgen-cli（由构建脚本自动安装）wasm32-unknown-unknown目标（由脚本自动添加）
代码质量
# Format code
cargo fmt --all
# Run clippy
cargo clippy --all-targets --all-features -- -D warnings
# Both should pass clean ✅TDD工作流程
该项目如下 严格TDD （测试驱动开发）：
- 红：编写失败测试
- 绿色：编写要传递的最小代码
- 重构：提高代码质量
看 docs/process.md 了解详情。
提交前检查表
承诺前：
- \[\]所有测试均通过：
cargo test --all - \[\]已格式化：
cargo fmt --all - \[\]无警告：
cargo clippy --all-targets --all-features -- -D warnings - \[\]文件已更新
🔍 调试
查看服务器日志
日志转到 标准错误 （不是stdout，它用于JSON-RPC）：
# Run with debug logs
RUST_LOG=debug GAME_DB_PATH=./test.db target/debug/game-mcp-server检查JSON-RPC流量
使用带有详细输出的手动测试脚本：
# Pretty-print responses
./test-mcp-manual.sh常见问题
克劳德代码中未显示服务器:
- 检查MCP配置文件路径和JSON语法
- 确保二进制路径是绝对的
- 完全重新启动Claude代码
数据库错误:
- 确保
GAME_DB_PATH目录可写 - 删除损坏的数据库：
rm $GAME_DB_PATH
权限错误:
- 使二进制文件可执行：
chmod +x target/release/game-mcp-server
🏆 成就
- ✅ 94项测试通过 （目标是50+）
- ✅ 100%覆盖率 已实施的模块
- ✅ 完整JSON-RPC 2.0 协议遵从
- ✅ 所有6个MCP工具 正确工作
- ✅ 综合集成测试 使用Mock AI
- ✅ 生产就绪代码质量 （生锈+刮干净）
- ✅ Yew/WASM前端 具有漂亮的UI
📈 指标
- 代码行：~2500（后端）+~1500（测试）+~2000（文档）
- 测试覆盖率：100%已实施的模块
- 建造时间：\<30秒（发布版本）
- 二进制大小：约8 MB（发布，带SQLite）
🚧 路线图
第一阶段：MCP服务器✅ 完成
- \[x\] TDD游戏逻辑
- \[x\] 数据库持久性
- \[x\] JSON-RPC 2.0协议
- \[x\] 所有6个MCP工具
- \[x\] 二进制与stdio传输
- \[x\] 集成测试
- \[x\] 手动测试
第二阶段：前端用户界面✅ 完成
- \[x\] 紫杉组件（板、状态、日志）
- \[x\] WebAssembly构建
- \[x\] 具有热重载功能的开发脚本
第3阶段：集成测试⏭️ 下一个
- \[\]使用实际的Claude Code实例进行测试
- \[\]记录发现的任何边缘案例
- \[\]根据反馈进行迭代
阶段4：REST API🔄 计划的
- \[\]Axum web服务器
- \[\]路线定义
- \[\]静态文件服务
- \[\]API测试
📝 文档
🤝 贡献
这是一个演示MCP集成的概念验证项目。请随意：
- 报告问题
- 提出改进建议
- 添加功能
- 改进文档
📄 许可证
麻省理工学院
🔗 参考文献
______________________________________________________________________
用Rust 2024构建 | 测试驱动开发 | 生产就绪