# pinoox-mcp

MCP server for the [Pinoox](https://www.pinoox.com/) PHP HMVC platform — gives any **MCP-compatible AI client** real project context (Cursor, Claude Desktop, VS Code, Windsurf, Zed, and more).

Supports **multi-app platform** (`php pinoox`) and **single-app pinx** ([pinoox/pinx-cli](https://github.com/pinoox/pinx-cli)) workflows.

Official docs: [github.com/pinoox/docs](https://github.com/pinoox/docs)

## Features

### Documentation (no `PINOOX_ROOT` required)

| Tool | Description |
|------|-------------|
| `search_docs` | Search docs by keyword |
| `fetch_doc` | Fetch a full markdown page |
| `list_doc_topics` | List curated doc paths |

### Project introspection (requires `PINOOX_ROOT`)

| Tool | Description |
|------|-------------|
| `project_info` | PHP version, pincore/pinx-cli, composer packages, project kind |
| `list_cli_commands` | `pinoox list` or `pinx list` |
| `list_routes` | Named route actions (`route:actions` / `pinx routes`) |
| `list_apps` | Apps under `apps/` or single-app package |
| `read_app_manifest` | Read `app.php` |
| `read_project_file` | Read allowed project files |
| `list_config_keys` | Config file keys |
| `list_env_keys` | `.env` variable names (redacted) |
| `list_models` | Eloquent models under `Model/` |
| `migration_status` | Migration status |
| `db_schema` | Tables inferred from migration files |
| `read_log_entries` | Last N log lines |
| `project_doctor` | `pinx doctor --json` (single-app) |
| `deps_status` | Composer/npm status (`pinx deps:st`) |
| `pinker_status` | Pinker cache status |
| `frontend_info` | Vite/theme info (`pinx fe:info`) |
| `run_cli` | Safe read-only CLI execution |

### Resources

- `pinoox://docs/index` — documentation table of contents
- `pinoox://docs/{lang}/{path}` — individual doc pages
- `pinoox://conventions` — Pinoox coding conventions for AI

### Prompts

- `create-pinoox-app` — scaffold a new app
- `pinx-workflow` — pinx-cli day-to-day commands

## Requirements

- Node.js 18+
- PHP 8.1+ (project tools)
- An MCP-compatible client (IDE, desktop app, or CLI agent)
- Pinoox 3.x platform **or** single-app pinx project

## Install

### npm (recommended)

```bash
npx -y pinoox-mcp
```

Or install globally:

```bash
npm install -g pinoox-mcp
```

npm package: [npmjs.com/package/pinoox-mcp](https://www.npmjs.com/package/pinoox-mcp)

### From source

```bash
git clone https://github.com/pinoox/pinoox-mcp.git
cd pinoox-mcp
npm install
npm run build
```

## MCP client configuration

`pinoox-mcp` uses **stdio** transport — any client that supports MCP servers can connect. Recommended config (from `examples/mcp.json`):

```json
{
  "mcpServers": {
    "pinoox": {
      "command": "npx",
      "args": ["-y", "pinoox-mcp"],
      "env": {
        "PINOOX_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}
```

For local development, use `node` with the path to `build/index.js` instead of `npx`.

`PINOOX_ROOT` works for both:

- **Platform:** directory with `index.php` + `pinoox`
- **Single-app:** directory with `app.php` + `bin/pinx`

Optional alias: `PINX_ROOT` (same as `PINOOX_ROOT`).

### Where to put the config

| Client | Config file / location |
|--------|------------------------|
| **Cursor** | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **VS Code** (Copilot / MCP) | `.vscode/mcp.json` or user MCP settings |
| **Windsurf** | MCP settings (same JSON shape as Cursor) |
| **Zed** | `~/.config/zed/settings.json` → `context_servers` |
| **Other** | See your client's MCP server documentation |

### AI agent rules

Copy `rules/AGENTS.md` into your project or add it to your client's system instructions / rules (Cursor Rules, Claude project instructions, etc.).

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PINOOX_ROOT` | For project tools | Platform or pinx project root |
| `PINX_ROOT` | Alias | Same as `PINOOX_ROOT` |

## Allowed CLI commands

`run_cli` only permits **read-only** commands. Lists differ by project kind:

**Platform (`php pinoox`):** `list`, `app:list`, `route:actions`, `migrate:status`, `pinker:status`, `log:view`, `version`, …

**Single-app (`pinx`):** `list`, `info`, `doctor`, `routes`, `migrate:st`, `pinker:st`, `deps:st`, `fe:info`, `log:view`, …

Destructive commands (`migrate`, `app:delete`, `cache:clear`, …) are blocked.

## Development

```bash
npm run dev    # watch TypeScript
npm run build  # compile to build/
npm start
```

## License

MIT