MCP State Of Play

游戏状态-LLM驱动的文本冒险MCP服务器

管理文本冒险游戏状态的最小MCP（模型上下文协议）服务器。使用Python、FastMCP、Redis和FastAPI构建。

特性

• MCP服务器：将游戏操作作为MCP工具，用于LLM交互
• 多种传输协议：支持stdio和可流式传输的http
• Redis状态管理：持久游戏状态存储
• Web仪表板：实时游戏状态监控
• Docker支持：使用Docker Compose轻松部署
• Zork风格游戏：经典的文本冒险机制

建筑

state-of-play/
├── src/
│   ├── main.py              # MCP server entry point
│   ├── game_engine.py       # Core game logic
│   ├── state_manager.py     # Redis state management
│   ├── web_interface.py     # FastAPI web server
│   └── models/
│       ├── game_state.py    # Game state models
│       └── entities.py      # Room, Item, NPC models
├── config/
│   └── game_config.json    # Game scenario configuration
├── docker-compose.yml
├── Dockerfile
└── requirements.txt

快速开始

使用Docker（推荐）

1. 克隆存储库：

git clone 
cd state-of-play

1. 启动服务：

docker-compose up -d

1. 访问web仪表板 http://localhost:8000

1. 通过HTTP访问MCP服务器 http://localhost:8001/mcp

1. 要运行不同的服务器模式，请执行以下操作：

# MCP server with stdio transport (for local LLM clients)
RUN_MODE=mcp python -m src.main

# MCP server with HTTP transport (for remote LLM clients)
RUN_MODE=mcp-http python -m src.main

# All servers (web + MCP HTTP)
RUN_MODE=all python -m src.main

地方发展

1. 安装Redis：

# Ubuntu/Debian
sudo apt install redis-server

# macOS
brew install redis

1. 启动Redis：

redis-server

1. 安装Python依赖项：

pip install -r requirements.txt

1. 运行web服务器：

python -m src.main

运行不同的MCP服务器模式：

# MCP with stdio transport (local clients)
RUN_MODE=mcp python -m src.main

# MCP with HTTP transport (remote clients)
RUN_MODE=mcp-http python -m src.main

# All servers together
RUN_MODE=all python -m src.main

MCP工具

服务器公开这些MCP工具用于LLM交互：

• move_player(direction) -向某个方向移动（北、南、东、西、上、下）
• look_around() -获取当前房间描述
• take_item(item_name) -从当前房间拿走一件物品
• drop_item(item_name) -将项目放入当前房间
• use_item(item_name, target) -在目标上使用项目（可选）
• talk_to_npc(npc_name, message) -与NPC交谈
• check_inventory() -列出玩家的库存
• get_available_actions() -获取上下文感知操作列表
• get_game_status() -获取当前游戏状态摘要
• start_new_game(player_name) -开始新游戏
• end_game() -结束游戏并生成摘要

游戏配置

游戏通过以下方式配置 config/game_config.json.包括的示例特征：

• 设置：神秘的实验室逃生室
• 目标：找到并组装逃跑的万能钥匙
• 力学：物品收集、NPC对话、解谜
• 房间：实验室入口、主实验室、储藏室、安全保险库
• 物品：钥匙卡、电池、工具、钥匙碎片
• 前体细胞：有用的科学家与对话树

Web仪表板

web界面位于 http://localhost:8000 提供：

• 实时游戏状态可视化
• 带有玩家位置的交互式房间地图
• 库存和物品跟踪
• 带有游戏历史记录的事件日志
• 游戏重置功能
• 自动刷新显示（每5秒一次）

Redis数据结构

游戏状态存储在Redis中，具有以下关键模式：

• game:{game_id}:state -完整的游戏状态JSON
• game:{game_id}:rooms -房间数据哈希
• game:{game_id}:items -项目数据哈希
• game:{game_id}:npcs -NPC数据哈希
• game:{game_id}:players -玩家数据哈希
• game:{game_id}:logs -按时间顺序排列的事件列表
• game:{game_id}:flags -全球游戏旗帜

环境变量

• REDIS_URL -Redis连接URL（默认值： redis://localhost:6379)
• MCP_PORT -MCP HTTP服务器端口（默认值： 8001)
• WEB_PORT -Web接口端口（默认值： 8000)
• RUN_MODE -服务器模式： web （默认）， mcp, mcp-http, combined，或 all

运行模式

• web -仅限Web仪表板（默认）
• mcp -带stdio传输的MCP服务器（用于本地客户端）
• mcp-http -具有流式http传输的MCP服务器（用于远程客户端）
• combined -Web仪表板+MCP stdio
• all -Web仪表板+MCP HTTP服务器

Docker编写配置文件

# Default: web dashboard only
docker-compose up

# MCP HTTP server only
docker-compose --profile mcp-only up mcp-server

# Web dashboard + MCP HTTP server
docker-compose --profile all-services up all-servers

发展

运行测试

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest

代码的风格

该项目遵循PEP 8，并全程使用类型提示。格式化代码：

pip install black isort
black .
isort .

扩展游戏

添加新房间

编辑 config/game_config.json 并使用以下命令添加房间对象：

• 独特 id
• 描述性的 name 和 description
• connections 其他房间
• items 和 npcs 列表
• 可选的 access_requirements

添加项目

项目支持：

• takeable 和 useable 旗帜
• 自定义 properties
• use_effects 用于游戏状态更改
• 位置跟踪（房间、玩家或NPC）

添加NPC

NPC的特点：

• 具有状态转换的对话树
• 库存管理
• 基于位置的交互

api参考

Web API终结点

• GET / -游戏仪表板HTML
• GET /api/state -当前游戏状态JSON
• GET /api/logs -游戏事件历史JSON
• POST /api/reset -将游戏重置为初始状态

游戏引擎方法

看 src/game_engine.py 对于完整的API，包括：

• 玩家动作和动作
• 项目操作
• NPC交互
• 状态持久性
• 事件日志记录

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

• 查看GitHub问题页面
• 查看配置示例
• 检查web仪表板的状态调试