Simple Maze

MCPAI代理

提供方 PowerinvGames

AI代理 stdio · 本地进程 无需鉴权 社区 / 第三方
查看接入方式

一个基于Python的迷宫游戏,支持GUI界面、HTTP API和MCP协议控制,适用于AI集成和游戏开发学习。

一句话选型结论

按资料字段整理

Simple Maze 属于AI代理类 MCP 服务器,stdio · 本地进程,无需鉴权,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 4 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量4暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

迷宫游戏Python本地部署AI控制HTTPAPIMCP协议游戏开发

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
python -m venv .venv

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 4 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 4 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Simple Maze当前 4 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方PowerinvGames上游标注的维护方 PowerinvGames
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

10.3 KB
来自项目仓库与上游目录的原文,未做删改

简易迷宫AI游戏


一、🎮 项目概述

一个基于Python的迷宫游戏,集成了本地GUI界面、HTTP API服务和MCP(Model Context Protocol)服务,支持多种交互方式控制游戏进程。项目采用模块化设计,实现了游戏逻辑、UI展示、API服务和MCP服务的清晰分离。

> 🚨 重要说明
>
> 整个项目几乎99%的代码和文档都是基于AI生成的哦! 🤖 由DeepSeek AI模型(DeepSeek-V3.2)协助开发完成,展示了AI在软件开发中的强大能力。

二、🚀 快速开始

2.1 环境要求

  • Python 3.7+
  • 依赖包:参见 requirements.txt

2.2 安装步骤```bash

克隆项目

git clone
cd maze_game

创建虚拟环境

python -m venv .venv

激活虚拟环境

Windows:

.venv\Scripts\activate

Linux/Mac:

source .venv/bin/activate

安装依赖

pip install -r requirements.txt


## 2.3  运行游戏```bash
python python/main.py

启动后,游戏窗口将自动打开,同时:

  • HTTP API服务将在 http://127.0.0.1:8080 启动
  • MCP SSE服务将在 http://127.0.0.1:8000 启动

三、📁 项目结构```text

SimpleMaze/
├── python/ # 主要源代码目录
│ ├── main.py # 程序入口
│ ├── constants.py # 常量配置
│ ├── logger.py # 日志配置
│ ├── app/ # 应用层
│ │ ├── ApplicationController.py
│ │ └── GameEventBus.py
│ ├── core/ # 核心游戏逻辑
│ │ ├── models/ # 数据模型
│ │ │ ├── GameModels.py
│ │ │ └── MazeModels.py
│ │ ├── game/ # 游戏服务
│ │ │ └── MazeGameService.py
│ │ ├── maze/ # 迷宫生成
│ │ │ └── MazeGenerator.py
│ ├── ui/ # 用户界面
│ │ ├── GameWindow.py # 主窗口
│ │ ├── MazeRenderer.py # 迷宫渲染器
│ │ └── components/ # UI组件
│ │ ├── GameInfoPanel.py
│ │ ├── ControlPanel.py
│ │ ├── FunctionPanel.py
│ │ └── MazePanel.py
│ ├── server/ # 服务器
│ │ ├── HttpGameServer.py # HTTP服务器
│ │ └── McpGameServer.py # MCP服务器
│ └── utils/ # 工具类
│ └── FontManager.py
├── resources/ # 资源文件
│ ├── HarmonyOS_SansSC_Regular.ttf # 中文字体
│ ├── LICENSE.txt # 中文字体许可证
│ └── doc_imgs # 文档图片
│ ├── game_ui.jpg
│ └── mcp_client_demo.jpg
├── .gitignore
├── requirements.txt # 项目依赖
├── README.md # 项目说明
└── LICENSE # 许可证


# 四、🎯 游戏特性

## 4.1  三种控制方式

1. 本地GUI界面:可视化操作,支持按钮和键盘控制
2. 键盘快捷键:
- 方向键/WASD:控制移动
- 空格键:等待
- R键:重置当前关卡
- N键:生成新关卡
3. HTTP API:支持程序化控制,便于AI集成
4. MCP协议:通过标准MCP协议供AI自然语言调用

## 4.2  游戏机制

- 随机生成迷宫(55×35大小)
- 玩家从左下角出发,目标到达右上角出口
- 实时显示移动次数和位置信息
- 到达终点时显示胜利界面

# 五、🌐 HTTP API接口

## 5.1  基础信息

- 服务器地址:http://127.0.0.1:8080
- 请求格式:JSON
- 响应格式:JSON

## 5.2  可用接口```text
GET    /api/health     # 健康检查
GET    /api/state      # 获取游戏状态
POST   /api/move       # 移动玩家
POST   /api/reset      # 重置当前关卡
POST   /api/new-level  # 生成新关卡

5.3 游戏状态数据结构```json

{
"maze_size": {"width": 55, "height": 35},
"player_position": {"col": 1, "row": 33},
"exit_position": {"col": 53, "row": 1},
"move_count": 0,
"is_completed": false
}


## 5.4  移动方向

- `up`:向上移动
- `down`:向下移动
- `left`:向左移动
- `right`:向右移动
- `wait`:等待(不移动)

## 5.5  API调用示例```python
import requests

# 移动玩家
response = requests.post(
"http://127.0.0.1:8080/api/move",
json={"direction": "up"}
)

# 获取游戏状态
state = requests.get("http://127.0.0.1:8080/api/state").json()

# 重置关卡
requests.post("http://127.0.0.1:8080/api/reset")

六、🤖 MCP (Model Context Protocol) 服务

6.1 MCP服务器信息

  • 服务器地址:http://127.0.0.1:8000
  • 协议:SSE (Server-Sent Events)
  • 框架:fastmcp

6.2 MCP端点```text

GET /sse # SSE事件流
POST /tools/call # 调用MCP工具
GET /tools # 获取工具列表


## 6.3  可用MCP工具

### 6.3.1  get_game_state

**描述**:获取当前游戏状态信息

**使用示例**:```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_game_state",
"arguments": {}
}
}

6.3.2 move_player

描述:移动玩家到指定方向

参数:

  • direction:移动方向,可选值:up(上), down(下), left(左), right(右), wait(等待)

使用示例:```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "move_player",
"arguments": {"direction": "up"}
}
}


### 6.3.3  reset_level

**描述**:重置当前关卡,将玩家放回起点

**使用示例**:```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "reset_level",
"arguments": {}
}
}

6.3.4 new_level

描述:生成全新迷宫关卡

使用示例:```json
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "new_level",
"arguments": {}
}
}


## 6.4  AI集成配置(示例)

### 6.4.1  CherryStudio 配置

在 CherryStudio 配置文件中添加:```json
{
"mcpServers": {
"maze_game": {
"name": "SimpleMaze迷宫游戏API",
"description": "",
"baseUrl": "http://localhost:8000/sse",
"command": "python",
"args": [
"python/server/mcp/McpServer.py"
],
"env": {},
"isActive": true,
"type": "sse",
"longRunning": true,
"provider": "Powerinv",
"providerUrl": "https://github.com/PowerinvGames/SimpleMaze",
"logoUrl": "",
"tags": [
"游戏"
]
}
}
}

6.4.2 其他MCP客户端

任何支持MCP协议的客户端都可以通过以下方式连接:

  • SSE端点:http://127.0.0.1:8000/sse
  • 工具调用端点:http://127.0.0.1:8000/tools/call

6.5 MCP使用示例

6.5.1 Python客户端示例```python

import requests
import json

调用MCP工具

def call_mcp_tool(tool_name, arguments=None):
url = "http://127.0.0.1:8000/tools/call"
payload = {
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": tool_name,
"arguments": arguments or {}
}
}

response = requests.post(url, json=payload)
return response.json()

获取游戏状态

result = call_mcp_tool("get_game_state")
print(result)

移动玩家

result = call_mcp_tool("move_player", {"direction": "right"})
print(result)

重置关卡

result = call_mcp_tool("reset_level")
print(result)

生成新关卡

result = call_mcp_tool("new_level")
print(result)


### 6.5.2  AI自然语言调用示例

AI可以直接使用自然语言调用工具,例如:```text
用户:告诉我当前游戏状态
AI:调用 get_game_state() 工具

用户:让玩家向右移动
AI:调用 move_player({"direction": "right"}) 工具

用户:重新开始这一关
AI:调用 reset_level() 工具

用户:生成一个新的迷宫
AI:调用 new_level() 工具

七、🛠️ 开发说明

7.1 设计模式

  • 事件驱动架构:使用事件总线解耦UI与游戏逻辑
  • 模块化组件:UI元素封装为独立组件
  • MVC分离:模型、视图、控制器清晰分离
  • 协议分离:HTTP API与MCP协议独立实现

7.2 MCP服务器特点

  • 精简核心功能:只提供4个核心工具,对应HTTP API的核心功能
  • 独立运行:MCP服务器独立于HTTP服务器,使用不同端口
  • 标准协议:基于官方MCP协议,兼容所有MCP客户端
  • 自然语言友好:工具设计简洁,适合AI自然语言调用
  • 异步支持:完全异步设计,性能优秀

7.3 字体配置

项目中包含中文字体文件(HarmonyOS Sans SC),确保中文正常显示。如需更换字体,请:

  1. 将新字体文件放入 resources/ 目录
  2. 在 python/constants.py 中更新 ResourcePaths.FONT_FILE 路径

7.4 日志系统

  • 使用Python标准logging模块
  • 日志级别:INFO
  • 输出到控制台

八、📋 命令行参数```bash

python python/main.py --help


可用参数:

- `--host`:HTTP服务器主机地址(默认:127.0.0.1)
- `--port`:HTTP服务器端口(默认:8080)
- `--maze-width`:迷宫宽度(默认:55)
- `--maze-height`:迷宫高度(默认:35)

# 九、🔧 故障排除

## 9.1  常见问题

1. **中文显示乱码**
- 确保 resources/HarmonyOS_SansSC_Regular.ttf 文件存在
- 检查字体文件路径是否正确
2. **端口占用**
- 默认使用8080端口,如被占用会自动尝试其他端口
- 可通过 --port 参数指定其他端口
3. MCP连接失败
- 确保MCP服务器正在运行(与主程序一起启动)
- 检查端口是否被防火墙阻止
- 验证SSE连接:访问 http://127.0.0.1:8000/sse
4. **依赖安装失败**
- 确保使用Python 3.7+
- 尝试升级pip:`pip install --upgrade pip`
- 确保fastmcp正确安装:`pip install fastmcp`

## 9.2  调试模式

如需更详细的日志,可修改 python/logger.py 中的日志级别:```python
logger.setLevel(logging.DEBUG)  # 改为DEBUG级别

十、📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

十一、🤝 贡献指南

  1. Fork 本仓库
  2. 创建功能分支:git checkout -b feature/新功能
  3. 提交更改:git commit -m '添加新功能'
  4. 推送到分支:git push origin feature/新功能
  5. 提交 Pull Request

十二、📞 联系方式

如有问题或建议,请提交GitHub Issue。


开始你的迷宫冒险吧! 🚶‍♂️➡️🎯

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Simple Maze 怎么安装?

在客户端按下面的安装命令接入:python -m venv .venv。装完在客户端配置里引用同一个包或端点。

Simple Maze 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Simple Maze 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Simple Maze 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

Simple Maze 能提供哪些能力?

资料显示约 4 个工具;能力标签包括 游戏开发、Python、AI控制、API集成。具体工具清单以官方文档为准。

Simple Maze 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Simple Maze 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。