# Pyramid Solver MCP

[![CI](https://github.com/finnestprogrammer111/pyramid-solver-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/finnestprogrammer111/pyramid-solver-mcp/actions/workflows/ci.yml)
[![M8ven Live Monitored](https://m8ven.ai/badge/mcp/finnestprogrammer111-pyramid-solver-mcp-1y2g88)](https://m8ven.ai/mcp/finnestprogrammer111-pyramid-solver-mcp-1y2g88)
[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/finnestprogrammer111/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

| Tool | What it does |
| --- | --- |
| `open_pyramid_solver` | Opens the blank interactive solver. |
| `solve_pyramid` | Solves 16 tile positions supplied row by row. Use `0` for the empty slot. |

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

## Run locally

Requirements: Node.js 20 or newer.

```bash
npm install
npm run build
npm start
```

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

```text
http://localhost:8787/mcp
```

## Test

```bash
npm test
npm run build
npm run smoke
```

You can inspect the MCP server with:

```bash
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](https://developers.openai.com/plugins/deploy/connect-chatgpt) guide for the current interface.

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

```text
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

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

## Project structure

```text
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