使用说明

项目简介

本项目 'ai-agent-zork' 仓库包含一个基于 Model Context Protocol (MCP) 实现的 Zork 游戏工具服务器。该服务器旨在为大型语言模型（LLM）驱动的智能体提供与经典文本冒险游戏 Zork 交互的标准接口。通过 MCP 协议，LLM 客户端可以调用服务器提供的工具来执行游戏指令，例如导航、查看物品、拿取物品等，从而实现 AI 智能体自动玩 Zork 游戏。

主要功能点

提供 Zork 游戏环境的工具集: 服务器实现了如 'navigate' (导航), 'examine' (查看), 'take' (拿取), 'inventory' (查看物品栏) 等一系列工具，允许客户端通过结构化的方式与 Zork 游戏世界互动。
基于 MCP 协议: 服务器遵循 MCP 协议标准，使用 JSON-RPC 格式进行请求和响应，确保与任何兼容 MCP 协议的客户端进行通信。
使用 Stdio 传输协议: 服务器通过标准输入输出 (stdio) 与客户端进行通信，简化部署和集成。
内置 Mock Zork 环境: 服务器集成了模拟的 Zork 游戏环境，无需依赖外部游戏引擎或解释器，即可独立运行并提供服务。
工具自描述: 服务器能够提供工具的定义和参数信息，客户端可以动态发现和理解可用的工具及其使用方法。

安装步骤

创建虚拟环境 (推荐):

python -m venv venv
source venv/bin/activate   # Linux/macOS
# venv\Scripts\activate.bat  # Windows (Command Prompt)
# venv\Scripts\Activate.ps1  # Windows (PowerShell)

安装项目依赖:
```
pip install -e .
```
此命令将安装项目所需的所有 Python 依赖包。

服务器配置

MCP 服务器配置信息 (JSON 格式，用于 MCP 客户端):

{
  "serverName": "zork-tools",
  "command": "node",
  "args": ["mcp/zork-tools/build/index.js"]
}

'serverName': MCP 服务器的名称，客户端用于识别和连接。
'command': 启动 MCP 服务器的命令，这里使用 'node' 解释器来运行 JavaScript 代码。
'args': 传递给启动命令的参数列表，指向服务器的入口文件 'mcp/zork-tools/build/index.js'。

请注意: MCP 客户端需要配置以上 JSON 信息，才能正确连接和使用此 Zork 工具 MCP 服务器。您需要确保 Node.js 环境已安装，并且可以执行 'node' 命令。

基本使用方法

启动 MCP 服务器: 打开终端，导航到仓库根目录下的 'mcp/zork-tools' 目录，并执行以下命令启动服务器：

npm install # 首次运行需要安装 nodejs 依赖
npm run build
node build/index.js

服务器成功启动后，将在 stdio 上监听 MCP 请求。

配置并运行 MCP 客户端: 在 'ai-agent-zork' 仓库中，已经提供了多种 MCP 客户端示例，例如 'src/run_mcp_agent.py' 和 'src/run_mcp_langgraph_agent.py'。您需要根据示例代码，配置 MCP 客户端以连接到刚刚启动的 'zork-tools' 服务器。通常，您需要指定服务器名称 "zork-tools" 以及服务器的启动命令（如上方的 JSON 配置所示）。
与 Zork 游戏互动: 运行 MCP 客户端后，客户端会通过 MCP 协议与服务器通信，调用服务器提供的 Zork 游戏工具，并根据 LLM 的决策自动进行游戏。您可以在终端中观察到 AI 智能体的思考过程、工具调用以及游戏环境的反馈。

注意: 为了使 LLM 智能体能够进行推理和决策，您可能需要配置 OpenAI API 密钥，具体方法请参考 'README.md' 文件中关于 "LLM Integration" 的说明。

关键词