rice-awa/mc-mcp-server

Minecraft MCP服务器文档索引

项目概述

Minecraft MCP服务器是一个集成系统，由两个核心组件组成：AIAgent(MCP-server)负责管理AI工具和处理LLM交互，以及基于WebSocket和脚本API的MC服务器负责处理游戏交互。系统支持两种请求路径：外部MCP客户端调用和游戏内聊天监听。

文档目录

1. 项目需求文档

• - 详细描述项目的核心功能、请求路径、用户交互流程和验收标准

2. 技术规范文档

• - 描述系统的整体架构、核心组件和技术栈
• - 定义客户端与服务器之间的WebSocket通信协议和脚本API集成
• - 说明如何集成Model Context Protocol标准和两种请求路径

3. 外部参考文档

• - Model Context Protocol的Python实现参考
• Minecraft脚本API文档 - Minecraft脚本API官方文档
• - 如何使用外部MCP客户端与服务器通信的示例

系统组件

1. AIAgent (mc-server) - 基于WebSocket和脚本API的服务器，处理游戏交互
2. MCP服务器 - 负责管理AI工具和处理LLM交互，通过MCP前端服务器实现外部MCP客户端的访问

请求路径

1. 外部MCP客户端路径 - 外部MCP客户端通过AIAgent与Minecraft交互
2. 游戏内聊天路径 - 玩家通过游戏内聊天触发AIAgent

快速入门

1. 阅读了解项目概况
2. 参考了解系统设计
3. 查看了解通信协议和脚本API集成
4. 学习了解LLM集成方式和请求路径

项目结构规范

mc-mcp-server/
├── server/
│   ├── __init__.py
│   ├── mc_server.py       # WebSocket服务器实现
│   ├── agent_server.py      # Agent服务器实现
│   └── utils/
│       ├── __init__.py
│       ├── auth.py        # 认证相关工具
│       ├── llm.py         # 大语言模型调用工具
│       └── logging.py     # 日志工具
│
├── resources/             # MCP资源定义
│   ├── __init__.py
│   ├── player.py
│   └── world.py
├── tools/                 # MCP工具定义
│   ├── __init__.py
│   ├── commands.py
│   └── messages.py
├── config/                # 配置文件
│   ├── default.json
│   └── production.json
├── tests/                 # 测试目录
│   ├── __init__.py
│   ├── test_mc_server.py
│   └── test_mcp_server.py
├── docs/                  # 文档目录
├── main.py                # 主入口文件
├── requirements.txt       # 依赖声明
└── README.md              # 项目说明

开发指南

1. 安装依赖:

   pip install -r requirements.txt
   

2. 设置环境变量:

   export DEEPSEEK_API_KEY=your_api_key
   

3. 启动MC服务器:

使用uv (推荐)

• 安装uv

pip install uv

• 使用uv运行

uv run main.py --full --mcp

• 调试模式（记录WebSocket数据包）

uv run main.py --full --mcp --debug

• 直接运行

python main.py --full --mcp

• 调试模式

python main.py --full --mcp --debug

4. 连接Minecraft客户端到MC服务器(默认端口8080)
5. (可选)连接外部mcp客户端(http://0.0.0.0:8000/sse)

调试与日志

服务器提供了调试模式和增强的日志功能，帮助开发者诊断和解决问题：

• 调试模式：使用 --debug 参数启动服务器，记录所有WebSocket数据包
• 日志文件：日志自动保存在 logs 目录下
  • 主服务器日志：logs/server_YYYYMMDD-HHMMSS.log
  • WebSocket数据包日志：logs/packets/packets_YYYYMMDD-HHMMSS.log

详细信息请参阅 。

贡献指南

1. 遵循项目的代码风格和架构设计
2. 提交前确保代码通过测试
3. 更新相关文档以反映代码变更

版本历史

许可信息

• 本项目以开源
• 其他项目许可证见