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