Tiled MCP

平铺式mcp服务器

A. 模型上下文协议（MCP） 服务器 平铺地图编辑器 --使AI代理能够以编程方式读取、创建和操纵图块贴图、图块集和图层。

使用TypeScript构建。通过Docker MCP Toolkit或stdio在macOS、Windows和Linux上运行。

为什么存在

Tiled是游戏开发中使用最广泛的开源磁贴地图编辑器。它输出 .tmj （JSON）和 .tmx （XML）文件，几乎每个2D游戏引擎都可以导入。但是，人工智能助手无法直接使用平铺地图——你只能复制粘贴平铺ID、手动描述层结构或导出截图以获取上下文。

平铺式mcp服务器 弥合这一差距。它让AI代理：

• 阅读并理解现有的地图、图位集和图层层次结构
• 从头开始创建新地图和倾斜集
• 跨层放置、移动和编辑图块
• 管理对象层（生成点、碰撞区域、触发器）
• 查询互动程序属性和自定义元数据
• 在格式（TMJ、TMX、Tiled Lua）之间导出映射

这意味着你可以说这样的话 *“沿3层底部添加一排水砖”* 或 *“使用地面层和对象层创建新的64x64正交地图”* 你的AI助手可以做到这一点。

建筑

┌─────────────────────┐     stdio / HTTP      ┌──────────────────────┐
│   AI Client         │◄────────────────────►  │  tiled-mcp-server    │
│   (Claude, Cursor,  │    MCP Protocol        │                      │
│    VS Code, etc.)   │                        │  ┌────────────────┐  │
└─────────────────────┘                        │  │  Tool Registry  │  │
                                               │  └───────┬────────┘  │
                                               │          │           │
                                               │  ┌───────▼────────┐  │
                                               │  │  Tiled I/O     │  │
                                               │  │  (read/write   │  │
                                               │  │  .tmj/.tsj)    │  │
                                               │  └───────┬────────┘  │
                                               │          │           │
                                               │  ┌───────▼────────┐  │
                                               │  │  File System   │  │
                                               │  └────────────────┘  │
                                               └──────────────────────┘

服务器正在运行 直接基于Tiled的JSON格式 (.tmj 对于地图， .tsj 瓷砖）。它不需要Tiled运行——它读取和写入Tiled使用的相同文件，因此您可以在Tiled中无缝地在人工智能辅助编辑和手动编辑之间来回切换。

对于实时编辑场景（平铺同时打开），服务器使用文件监视来保持同步。

支持的平铺格式

设计决策： 我们只写信给 .tmj/.tsj 因为JSON更易于编程操作，更易于验证，并且在所有功能上都与TMX具有同等地位。Tiled可以互换读取这两种格式。

工具

工具遵循MCP命名约定： tiled_{action}_{resource}.

地图工具

图层工具

瓷砖工具

拼贴工具

对象工具

属性工具

实用工具

项目结构

tiled-mcp-server/
├── Dockerfile
├── docker-compose.yml
├── package.json
├── tsconfig.json
├── README.md
├── LICENSE
├── .dockerignore
├── .gitignore
├── src/
│   ├── index.ts                 # Entry point, transport selection, server init
│   ├── constants.ts             # Shared constants (defaults, limits, format enums)
│   ├── types.ts                 # TypeScript interfaces for Tiled data structures
│   ├── schemas/
│   │   ├── map.ts               # Zod schemas for map tool inputs
│   │   ├── layer.ts             # Zod schemas for layer tool inputs
│   │   ├── tile.ts              # Zod schemas for tile tool inputs
│   │   ├── tileset.ts           # Zod schemas for tileset tool inputs
│   │   ├── object.ts            # Zod schemas for object tool inputs
│   │   └── property.ts          # Zod schemas for property tool inputs
│   ├── tools/
│   │   ├── maps.ts              # Map CRUD tools
│   │   ├── layers.ts            # Layer CRUD tools
│   │   ├── tiles.ts             # Tile placement and query tools
│   │   ├── tilesets.ts          # Tileset management tools
│   │   ├── objects.ts           # Object layer tools
│   │   ├── properties.ts        # Property management tools
│   │   └── utility.ts           # Validation and summary tools
│   └── services/
│       ├── tiled-io.ts          # Core read/write for .tmj/.tsj files
│       ├── format-converter.ts  # TMX/TSX → JSON conversion (read-only)
│       ├── file-watcher.ts      # Optional file watching for live sync
│       ├── validator.ts         # Map/tileset validation logic
│       └── error-handler.ts     # Shared error formatting
├── tests/
│   ├── fixtures/                # Sample .tmj/.tsj files for testing
│   ├── tools/                   # Tool-level integration tests
│   └── services/                # Service unit tests
└── eval/
    └── evaluation.xml           # MCP evaluation questions

安装

Docker MCP工具包（推荐）

最简单的跨平台设置。需要 启用MCP工具包。

docker pull rocketsnailgames/tiled-mcp-server:latest

然后将其添加到Docker MCP Toolkit配置文件中或手动配置：

// ~/.docker/mcp/config.json
{
  "servers": {
    "tiled": {
      "image": "rocketsnailgames/tiled-mcp-server:latest",
      "env": {
        "TILED_PROJECT_DIR": "/workspace"
      },
      "volumes": [
        "${HOME}/my-game-project:/workspace"
      ]
    }
  }
}

克劳德桌面（stdio）

// claude_desktop_config.json
{
  "mcpServers": {
    "tiled": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${HOME}/my-game-project:/workspace",
        "-e", "TILED_PROJECT_DIR=/workspace",
        "rocketsnailgames/tiled-mcp-server:latest"
      ]
    }
  }
}

本地（npm）

对于没有Docker的开发或环境：

git clone https://github.com/rocketsnailgames/tiled-mcp-server.git
cd tiled-mcp-server
npm install
npm run build

stdio模式（默认）：

TILED_PROJECT_DIR=/path/to/your/maps npm start

HTTP模式（用于远程或多客户端）：

TRANSPORT=http PORT=3000 TILED_PROJECT_DIR=/path/to/your/maps npm start

配置

所有配置都是通过环境变量进行的，保持简单和容器友好。

与跨平台支持

该服务器设计为在macOS、Windows和Linux上以相同的方式运行。

Docker（所有平台）： Dockerfile使用一个纤细的Node.js Alpine映像。卷装载处理对本地项目目录的文件访问。这是推荐的方法，因为它消除了特定于操作系统的路径问题和依赖关系冲突。

原生（所有平台）： 服务器使用Node.js path 整个模块用于操作系统感知路径处理。文件操作使用 fs/promises 没有特定于操作系统的系统调用。测试时间：

• macOS 13+（arm64，x64）
• Windows 10/11（x64）
• Ubuntu 22.04+/Debian 12+（x64，arm64）

路径处理： 平铺地图通常包含到平铺图像的相对路径。服务器使用以下命令对这些路径进行标准化 path.resolve() 与映射文件的目录相对应，因此跨平台项目无需修改即可工作。

Docker构建

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json ./
COPY src/ ./src/
RUN npm run build

FROM node:22-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./
ENV NODE_ENV=production
ENTRYPOINT ["node", "dist/index.js"]

多阶段构建使最终映像保持较小（~80MB），没有开发依赖关系或TypeScript源代码。

发展

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode with auto-reload
npm run dev

# Run tests
npm test

# Lint
npm run lint

# Type check without emitting
npm run typecheck

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

添加新工具

1. 在中定义Zod输入模式 src/schemas/
2. 在适当的位置实施工具处理程序 src/tools/ 文件
3. 在中注册该工具 src/index.ts 使用 server.registerTool()
4. 在中添加测试 tests/tools/
5. 更新此自述文件

技术选择

拼接脚本API（未来）

Tiled有一个内置 JavaScript脚本API （由Qt的JS引擎提供支持），TypeScript定义可通过 @mapeditor/tiled-api.此API允许使用自定义格式、工具和自动化来扩展Tiled。

此服务器的未来版本可以选择通过Tiled扩展脚本桥接到正在运行的Tiled实例，从而实现以下实时操作：

• 触发Tiled的撤销/重做堆栈
• 访问当前选择
• 运行自定义工具脚本
• 实时对用户编辑做出反应

这是第二阶段的目标。第一阶段侧重于基于文件的操作，涵盖了绝大多数用例，不需要打开Tiled。

路线图

• \[x\] README和架构设计
• \[ \] 第一阶段：核心文件操作

- \[\]平铺I/O服务（读/写 .tmj/.tsj) - \[\]平铺JSON模式的TypeScript接口 - \[\]映射CRUD工具 - \[\]层CRUD工具 - \[\]瓷砖放置工具 - \[\]Tileset管理工具 - \[\]对象层工具 - \[\]财产工具 - \[\]验证和摘要实用程序 - \[\]Docker镜像和MCP工具包配置 - \[\]带有夹具图的测试套件 - \[\]MCP评估问题

• \[ \] 第二阶段：高级功能

- \[\]TMX/TSX读取支持（XML→ JSON转换） - \[\]文件监视实时同步 - \[\]王集/地形工具 - \[\]磁贴动画支持 - \[\]模板对象支持 - \[\]无限地图支持（分块图层）

• \[ \] 第三阶段：砖砌桥梁

- \[\]用于双向通信的平铺扩展脚本 - \[\]实时选择和撤消/重做集成 - \[\]从AI代理注册自定义工具

贡献

欢迎投稿！请在提交大型PR之前打开一个问题进行讨论。

添加工具时，请遵循中建立的模式 src/tools/ 并确保：

• Zod模式 .strict() 执行和 .describe() 在每个领域
• 工具注释(readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
• 包含输入/输出文档的全面工具描述
• 使用夹具进行测试 .tmj 文件
• 建议后续步骤的错误消息

参考文献

• 平铺地图编辑器
• 平铺JSON映射格式
• 拼接脚本API
• @mapeditor/tiled-api TypeScript定义
• MCP规范
• MCP TypeScript SDK

许可证

MIT许可证——见 许可证 了解详情。