Pyramid Solver MCP

An interactive solver for the 4×4 sliding puzzle. It works in two modes:

• as an MCP App rendered inside ChatGPT;

• as a regular browser app at the server root.

The project uses React for the widget, the official Model Context Protocol SDK for the server, and a self-contained Vite build that can be returned as an MCP UI resource.

MCP tools

The solver offers fast Weighted A* and optimal IDA* modes.

Related MCP server: playwright-mcp-server

Run locally

Requirements: Node.js 20 or newer.

npm install
npm run build
npm start

Open http://localhost:8787 for browser mode. The Streamable HTTP MCP endpoint is:

http://localhost:8787/mcp

Test

npm test
npm run build
npm run smoke

You can inspect the MCP server with:

npx @modelcontextprotocol/inspector@latest

Choose Streamable HTTP and connect to http://localhost:8787/mcp.

Deploy to a public URL

The quickest path is the Deploy to Render button at the top of this README:

1. Sign in to Render and allow it to access this GitHub repository.

2. Keep the Blueprint settings and choose Deploy Blueprint.

3. Wait for the service to become Live.

4. Copy the generated URL, such as https://pyramid-solver-mcp.onrender.com.

5. Check that <your-url>/health returns {"ok":true}.

The included render.yaml builds the Dockerfile, checks /health, and deploys changes only after GitHub CI passes. Render's free service can take longer to answer after being idle.

Connect it to ChatGPT

ChatGPT requires a public HTTPS MCP endpoint. After deployment:

1. In ChatGPT, open Settings → Security and login → Developer mode and enable it.

2. Open Plugins and select the + button.

3. Enter a name such as Pyramid Solver and a short description.

4. Set the endpoint to your complete Render URL ending in /mcp, for example https://pyramid-solver-mcp.onrender.com/mcp.

5. Review the discovered tools and finish adding the plugin.

If tool definitions change after a later deployment, refresh the plugin so ChatGPT loads the new metadata. See OpenAI's Connect your MCP server to ChatGPT guide for the current interface.

Once connected, try Open the Pyramid Solver or provide a board such as:

1 2 3 4
5 6 7 8
9 10 11 12
13 14 0 15

Useful checks:

• Open the Pyramid Solver.

• Solve this board with A*: 1 2 3 4 / 5 6 7 8 / 9 10 11 12 / 13 14 0 15.

• Solve this board optimally with IDA*: 1 2 3 4 / 5 6 7 8 / 9 10 11 12 / 13 14 0 15.

Docker

docker build -t pyramid-solver-mcp .
docker run --rm -p 8787:8787 pyramid-solver-mcp

Project structure

src/PyramidSolver.jsx  React interface
src/solver.js           A* and IDA* solver engine
src/mcpBridge.js        MCP Apps UI bridge
server.js               Streamable HTTP MCP server
test/solver.test.js     Solver tests

License

MIT