pinoox-mcp

MCP server for the Pinoox 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) workflows.

Official docs: 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)

npx -y pinoox-mcp

Or install globally:

npm install -g pinoox-mcp

npm package: npmjs.com/package/pinoox-mcp

From source

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):

{
  "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

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

License

MIT