MCP Maze Runner

🎮 MCP迷宫跑者

一个通过自然语言聊天控制的交互式迷宫游戏，旨在演示模型上下文协议（MCP）与人工智能代理的集成。

概述

MCP迷宫跑者 是一个教育项目，演示了如何使用 模型上下文协议（MCP）.

概念

玩家通过用自然语言与AI代理聊天来导航迷宫。命令如下 *“前进”*, *“环顾四周”*，或 *“我在哪里？”* 由代理解释，并通过MCP工具转换为游戏动作。游戏可以完全通过聊天进行——代理提供您需要的所有信息：您的位置、附近的障碍物、可用的动作和基于文本的迷宫可视化。

为什么是这个项目？

这不是构建迷宫游戏的最有效方法——你可以用更少的资源创建相同的体验，而不需要LLM要求简单的动作。 这正是关键所在。

这个项目是一个学习沙箱，可以探索：

• 🔌 MCP集成：如何将环境控制作为人工智能代理可以使用的MCP工具公开
• 🤖 ADK代理开发：使用谷歌的代理开发工具包构建代理，包括会话内存和工具编排
• 🎨 界面层：在顶部添加Streamlit界面，以可视化游戏状态并简化交互
• 🔄 代理环境循环：了解代理人如何在受控环境中感知、决策和行动

实际应用

虽然迷宫游戏很简单，但模式可以扩展到有意义的用例：

• 机器人学：通过自然语言命令控制物理机器人
• 物联网系统：通过对话式人工智能管理智能设备和传感器
• 游戏NPC：创建响应上下文的智能非玩家角色
• 流程自动化：通过语音或文本指令指导复杂的工作流程

这个迷宫中的“玩家”也可以是仓库机器人、无人机或任何需要解释指令并与环境交互的系统。

建筑

graph LR
    A[User Chat Input] --> B[Streamlit UI]
    B --> C[Google ADK Agent]
    C --> D[MCP Server]
    D --> E[Game Logic]
    E -.-> D
    D -.-> C
    C -.-> B
    B -.-> A

    subgraph "Streamlit App"
        B
        C
        D
        E
    end

特性

游戏机制

• 🚶 运动：在四个方向上导航（向上、向下、向左、向右）
• 🧱 障碍：墙壁挡住了你的去路，需要战略思维
• 🔑 钥匙：收集钥匙以解锁特殊车门
• 🚪 退出：找到并到达迷宫出口获胜

MCP工具暴露

• move(direction) -向主要方向（上、下、左、右）移动玩家
• look_around(visibility_range) -查看附近的单元格、墙壁、按键和可用移动
• get_game_state() -获取完整的游戏状态（位置、按键、移动、状态）
• get_maze_display(fog_of_war) -获取迷宫的ASCII可视化
• reset_game() -重置游戏，以新的迷宫重新开始

安装与使用

1.如果您还没有安装uv：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# pip
pip install uv

2.克隆和设置：

# clone the repo
git clone https://github.com/MarinCervinschi/mcp-maze-runner.git
cd mcp-maze-runner

# install dependencies
uv sync

3.配置API密钥

• 创建一个 .env 文件在 root_agent 使用Google API密钥的目录：

GOOGLE_API_KEY=your_google_api_key_here

您可以从获取API密钥 谷歌AI工作室.

4.运行Streamlit UI：

uv run streamlit run main.py

• 这将启动Streamlit web界面，MCP服务器正在进程中运行。
• 打开浏览器并导航到 http://localhost:8501.
• 与AI代理聊天，在迷宫中导航！

5.ADK-Web调试（开发）：

uv run python scripts/dev_main.py

• 这将启动MCP服务器和ADK web界面进行测试和调试。
• 打开浏览器并导航到 http://localhost:8000.
• 选择 root_agent 在左侧面板上，开始新的聊天会话。

6.在终端中玩（无AI）：

uv run python scripts/run_game.py

• 这将在您的终端中启动游戏，允许您直接与迷宫互动。
• 在这种模式下，您不使用AI代理或MCP工具，但这是一种体验迷宫的有趣方式！

运行测试

uv run pytest tests/ -v

技术栈

截图

Streamlit UI Screenshot

许可证

麻省理工学院许可证-您可以自由使用此项目进行学习和教学。