npx mcpbar@latest install box3lab/engine-openapi-mcp -c claude

npx mcpbar@latest edit -c claude

{
  "mcpServers": {
    "box3-engine-openapi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@box3lab/engine-openapi-mcp"
      ],
      "env": {}
    }
  }
}

神岛引擎 OpenAPI MCP 工具集

这个项目提供了一系列用于神岛引擎的 OpenAPI MCP (Model Context Protocol) 工具，帮助 AI 更高效地调用引擎接口。

功能概览

该工具集提供以下核心功能：

• 脚本管理工具：用于创建、更新、重命名游戏脚本
• 存储管理工具：用于读取、写入、删除和查询游戏数据存储
• AI 辅助功能：提供基于大模型的代码审查、生成、优化和数据结构设计

API 工具详解

脚本管理工具 (Script Tools)

基础操作

工具名称	描述	必要参数
script.saveOrUpdate	A 保存或更新神岛引擎脚本	mapId, name, type, file
script.rename	重命名神岛引擎脚本	mapId, name, newName

代码辅助提示

提示名称	描述	必要参数
script.review	审查神岛引擎脚本代码，提供改进建议和潜在问题分析	code
script.generate	根据描述和需求生成神岛引擎脚本代码	description
script.optimize	优化神岛引擎脚本代码，提高性能或可读性	code

存储管理工具 (Storage Tools)

基础操作

工具名称	描述	必要参数
storage.get	存储空间单 key 值查询	key, mapId, storageName
storage.set	存储空间单 key 值写入/更新	key, mapId, storageName, value
storage.remove	存储空间单 key 值删除	key, mapId, storageName
storage.page	存储空间分页查询	mapId, storageName

存储辅助提示

提示名称	描述	必要参数
storage.designSchema	为游戏功能设计键值对数据存储结构	gameFeatures
storage.migrationPlan	设计存储数据迁移方案	currentSchema, targetSchema
storage.optimizeQuery	优化键值对数据查询方案	queryDescription

使用示例

脚本管理示例

// 上传脚本文件
const scriptResult = await mcpClient.callTool("script.saveOrUpdate", {
  mapId: "your-map-id",
  name: "example.js",
  type: "0", // 0-服务器脚本、1-客户端脚本
  file: "console.log('hi')",
  token: "your-auth-token",
  userAgent: "your-user-agent",
});

// 使用代码审查提示
const codeReview = await mcpClient.prompt("script.review", {
  code: "function example() { console.log('Hello'); }",
});

// 生成脚本代码
const generatedCode = await mcpClient.prompt("script.generate", {
  description: "实现一个计算玩家得分的系统",
  requirements: "支持多种得分方式,保存历史最高分,支持排行榜",
});

存储管理示例

// 读取存储值
const storageData = await mcpClient.callTool("storage.get", {
  key: "player_stats",
  mapId: "your-map-id",
  storageName: "gameData",
  token: "your-auth-token",
  userAgent: "your-user-agent",
});

// 写入存储值
const writeResult = await mcpClient.callTool("storage.set", {
  key: "player_stats",
  mapId: "your-map-id",
  storageName: "gameData",
  value: JSON.stringify({ score: 100, level: 5 }),
  token: "your-auth-token",
  userAgent: "your-user-agent",
});

// 使用数据结构设计提示
const schemaDesign = await mcpClient.prompt("storage.designSchema", {
  gameFeatures: "一个RPG游戏，需要存储玩家装备、背包物品、任务进度和成就",
  dataRequirements: "支持多人同时在线,支持离线进度保存,支持物品交易历史",
});

集成到客户端

浏览器端集成

import { McpClient } from "@modelcontextprotocol/sdk/client/index.js";

// 初始化客户端
const mcpClient = new McpClient({
  serverUrl: "https://your-mcp-server.com",
  headers: {
    "Content-Type": "application/json",
  },
});

// 使用工具
async function useTools() {
  const result = await mcpClient.callTool("storage.get", {
    // 参数...
  });

  // 处理结果
  console.log(result);
}

Node.js 端集成

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";

// 创建传输通道
const transport = new WebSocketClientTransport({
  url: "ws://localhost:3000",
});

// 初始化客户端
const client = new Client(
  { name: "dao3-client", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// 连接到服务器
await client.connect(transport);

// 使用工具
const result = await client.callTool({
  name: "script.list",
  arguments: {
    mapId: "your-map-id",
    token: "your-token",
    userAgent: "your-agent",
  },
});

认证

所有 API 调用都需要提供认证信息，包括：

• token: 授权令牌
• userAgent: 用户代理字符串

这些参数需要在每个工具调用时提供。

获取认证信息

1. 访问神岛引擎开发者平台获取开发者密钥
2. 使用开发者密钥生成认证令牌
3. 在 API 调用中提供认证信息

故障排除

请求超时

如果请求超时，可能是因为：

• 网络连接不稳定
• 服务器负载过高
• 请求数据量过大

尝试减少请求数据量或稍后重试。

类型错误

确保按照文档中指定的类型传递参数，特别是:

• 数值类型的参数（如 limit、offset）必须是数字
• 布尔值参数（如 isGroup）必须是布尔值

贡献指南

欢迎提交问题报告或 Pull Request 来帮助改进这个项目。

1. Fork 项目仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建一个 Pull Request