pcg MCP

PCG MCP服务器

一种模型上下文协议（MCP）服务器，为过程内容生成提供波形函数折叠（WFC）。

⚠️ 状态：早期开发/未准备好生产 该项目正在积极开发中，有几个已知的局限性： - 图像处理：图像加载需要可选的依赖关系(nx_image, nx)默认情况下不可用。颜色量化被简化，可能无法很好地处理复杂的图像。 - 错误处理：可以改进MiniZinc输出的错误处理和提取。DZN解析中的一些边缘情况没有得到完全处理。 - WFC限制：没有回溯支持-矛盾会导致错误，而不是自动恢复。缺少状态序列化验证。 - 构建问题：Docker构建包括以下解决方法 gen_state_machine OTP 26兼容性问题。 - 测试：虽然所有测试都通过了，但代码库有依赖关系的类型警告，需要更全面的边缘用例测试。 使用风险自负。 这是仅适用于开发和测试目的的实验软件。

特性

• 波函数崩溃（WFC） -程序级生成算法

- 从样本图像或阵列中提取模式 - 基于频率的模式权重 - 边缘兼容邻接规则 - 支持基于图像的样本（当nx_image可用时）

• MiniZinc约束程序设计 -高级约束求解

- 使用缓冲求解器求解MiniZinc模型 - 验证MiniZinc模型 - 自动标准库包含

• MCP协议支持

- 通过STDIO或HTTP传输的JSON-RPC 2.0协议 - 服务器发送事件（SSE）支持流式响应

• 命令行工具

- mix pcg.generate -从命令行生成PCG级别

快速开始

先决条件

• 灵丹妙药1.18+
• MiniZinc已安装并可在PATH中使用（WFC内部使用）

备注MiniZinc会自动安装在Docker镜像中。

安装

git clone 
cd pcg-mcp
mix deps.get
mix compile

用法

STDIO传输（默认）

对于当地发展：

mix mcp.server

或使用release：

./_build/prod/rel/pcg_mcp/bin/pcg_mcp start

HTTP传输

对于web部署（例如Smithery）：

PORT=8081 MIX_ENV=prod ./_build/prod/rel/pcg_mcp/bin/pcg_mcp start

终点：

• POST / -JSON-RPC 2.0 MCP请求
• GET /sse -服务器发送流媒体事件
• GET /health -健康检查

码头工人

docker build -t pcg-mcp .
docker run -d -p 8081:8081 --name pcg-mcp pcg-mcp

工具

服务器提供以下MCP工具：

MiniZinc工具（高级/实用）

minizinc_solve

使用带槽求解器（固定，不可配置）求解MiniZinc模型。

参数：

• model_content （字符串，必填）：MiniZinc模型内容（.mzn）为字符串
• data_content （string，可选）：DZN数据内容为字符串（例如。， "n = 8;").必须是有效的DZN格式。已解析并包含在响应中 input_data 现场。
• timeout （整数，可选）：可选超时（毫秒）（默认值：30000，即30秒）。允许的最大值为30000毫秒（30秒）；超过此值的上限为30秒。
• auto_include_stdlib （boolean，可选）：自动包含标准MiniZinc库（例如。， alldifferent.mzn)如果不存在（默认值： true)

minizinc_validate

通过检查语法和类型检查来验证MiniZinc模型，而无需求解。在尝试解决模型之前，对调试模型很有用。

参数：

• model_content （字符串，必填）：MiniZinc模型内容（.mzn）为字符串
• data_content （string，可选）：DZN数据内容为字符串（例如。， "n = 8;").必须是有效的DZN格式。
• auto_include_stdlib （boolean，可选）：自动包含标准MiniZinc库（例如。， alldifferent.mzn)如果不存在（默认值： true)

响应格式：

• valid （boolean）：模型是否有效
• errors （array）：错误消息列表（如果有的话）
• warnings （array）：警告消息列表（如果有的话）
• message （string）：人类可读消息（有效时）
• raw_output （string）：原始MiniZinc验证输出（无效时）

MiniZinc Tool Examples

求解一个简单的模型：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minizinc_solve",
    "arguments": {
      "model_content": "var int: x; constraint x > 0; constraint x  0; solve satisfy;"
    }
  }
}

波函数折叠工具（主要）

wfc_init

从示例图案初始化波浪函数折叠生成器。提取模式、计算权重并构建邻接规则。

参数：

• sample （数组或字符串，必填）：二维图块ID数组 [[1,1,1],[1,0,1],[1,1,1]] 或图像文件的路径
• pattern_size （整数，可选）：要提取的图案大小（默认值：3）
• output_width （整数，必填）：输出网格的宽度
• output_height （整数，必填）：输出网格的高度
• tile_size （整数，可选）：从图像加载时每个图块的大小（像素）（默认值：1）

退货： 带有网格、模式、权重和邻接规则的WFC状态对象

wfc_tick

执行一次波函数折叠迭代。找到熵最低的单元格并将其折叠为图块。

参数：

• state （对象，必填）：WFC状态来自 wfc_init 或以前 wfc_tick

退货： 更新WFC状态和 complete 指示生成是否完成的标志

wfc_run

运行波浪函数折叠，直到完成或达到最大迭代次数。

参数：

• state （对象，必填）：WFC状态来自 wfc_init
• max_iterations （整数，可选）：最大迭代次数（默认值：1000）

退货： 最终状态、所有中间状态的历史记录和迭代计数

wfc_get_output

从WFC状态中提取最终输出网格作为二维图块ID数组。

参数：

• state （对象，必填）：WFC状态（来自 wfc_init, wfc_tick，或 wfc_run)

退货： 表示生成级别的二维图块ID数组

WFC Tool Examples

从模式初始化WFC：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "wfc_init",
    "arguments": {
      "sample": [[1,1,1],[1,0,1],[1,1,1]],
      "pattern_size": 2,
      "output_width": 10,
      "output_height": 10
    }
  }
}

运行一个勾选：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "wfc_tick",
    "arguments": {
      "state": { /* state from wfc_init */ }
    }
  }
}

运行至完成：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "wfc_run",
    "arguments": {
      "state": { /* state from wfc_init */ },
      "max_iterations": 500
    }
  }
}

获取输出：

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "wfc_get_output",
    "arguments": {
      "state": { /* state from wfc_run */ }
    }
  }
}

配置

环境变量：

• MCP_TRANSPORT -运输类型("http" 或 "stdio")
• PORT -HTTP服务器端口（默认值：8081）
• HOST -HTTP服务器主机（默认值： 0.0.0.0 如果设置了端口，否则 localhost)
• MIX_ENV -环境(prod, dev, test)
• ELIXIR_ERL_OPTIONS -Erlang选项（设置为 "+fnu" 对于UTF-8）
• MCP_SSE_ENABLED -启用/禁用服务器发送事件（默认值： true，设置为 "false" 禁用）

运输选择：

1. 如果 MCP_TRANSPORT 已设置，请使用该传输
2. 如果 PORT 已设置，请使用HTTP传输
3. 否则，使用STDIO传输（默认）

故障排除

未找到MiniZinc：确保MiniZinc已安装并在PATH中可用（WFC内部要求）。对于Docker，MiniZinc包含在镜像中。

端口已在使用中：更改 PORT 环境变量或停止冲突的服务。

编译错误：运行 mix deps.get && mix clean && mix compile.

调试模式：使用 MIX_ENV=dev mix mcp.server 用于详细日志记录。

版本

当前版本： 1.0.0-dev2 （参见 mix.exs 最新版本）

需求

• 灵丹妙药1.18+
• Erlang/OTP 26+
• MiniZinc 2.9.3+已安装并在PATH中可用（或使用包含MiniZinc的Docker镜像）

Development

建筑

mix deps.get
mix compile

测试

# Run all tests
mix test

# Run specific test suites
mix test test/beam_server_*.exs  # BEAM server integration tests
mix test test/wfc_test.exs       # WFC unit tests
mix test test/adhoc_test.exs     # Adhoc tests

测试结构：

• test/beam_server_minizinc_test.exs -通过BEAM服务器进行MiniZinc工具测试
• test/beam_server_wfc_test.exs -WFC工具通过BEAM服务器进行测试
• test/beam_server_integration_test.exs -完整的工作流集成测试
• test/beam_server_error_test.exs -错误处理测试
• test/wfc_test.exs -使用夹具进行WFC单元测试
• test/adhoc_test.exs -交互式临时测试

建筑发布

MIX_ENV=prod mix release

本地运行

对于STDIO传输（默认）：

mix mcp.server

对于HTTP传输：

MCP_TRANSPORT=http PORT=8081 mix run --no-halt

生成级别

使用“混合”任务生成PCG级别：

# Default: simple pattern, 30x20
mix pcg.generate

# Custom pattern and size
mix pcg.generate simple 25 15
mix pcg.generate checkerboard 30 20
mix pcg.generate dungeon 40 25

可用图案： simple, checkerboard, dungeon

许可证

MIT许可证-有关详细信息，请参阅License.md。

版权

版权所有（c）2025年至今K.S.Ernest（iFire）Lee