MCP Server
An MCP server that makes Vortos conventions, architecture rules, best practices, and project config queryable by AI coding assistants — Claude Code, Cursor, Windsurf, and Codex.
MCP Server
vortos-mcp ships a Model Context Protocol server that makes the framework's knowledge queryable by AI coding tools. When it's running, your AI assistant can ask it for golden rules, architecture patterns, common mistakes, module APIs, best practices, and your project's own config files — and act on that information when generating code.
What MCP Is
MCP (Model Context Protocol) is an open standard for exposing context to AI tools. An MCP server runs as a subprocess alongside your AI client. The client sends tool calls over stdin/stdout; the server returns structured answers. No HTTP server, no API keys, no cloud dependency.
What the Server Provides
Seven tools are registered in the MCP server, each answering a different class of question:
| Tool | What it answers |
|---|---|
get_conventions | Golden rules, naming conventions, package registration order |
get_architecture | Layer responsibilities, CQRS/event flow, canonical directory structure |
get_best_practices | Performance, security, testing, worker mode, and Kafka practices |
get_mistakes | 15 common antipatterns with correct alternatives |
get_module_docs | API reference for any Vortos module |
list_project_modules | Which vortos/* packages are installed in your project |
read_project_config | The contents of your config/*.php files |
See Tools Reference for the full schema and example outputs.
Quick Setup
Install the package
composer require vortos/vortos-mcp --devWire it into your AI client
php bin/console vortos:mcp:installThis command auto-detects which AI clients are installed on your machine and writes the MCP server configuration into each one. You can also target a specific client:
php bin/console vortos:mcp:install --client=claude
php bin/console vortos:mcp:install --client=cursor
php bin/console vortos:mcp:install --client=windsurf
php bin/console vortos:mcp:install --client=codex
php bin/console vortos:mcp:install --client=allPass --global to write to your user-level config (~/) instead of the project-level config (.claude/, .cursor/, .windsurf/):
php bin/console vortos:mcp:install --client=claude --globalVerify the setup
php bin/console vortos:mcp:doctorOutput:
AI Clients
──────────────────────────────────────────────────
✔ Claude Code detected configured
- Cursor not found —
- Windsurf not found —
- Codex not found —
MCP Server
──────────────────────────────────────────────────
Command: php ./bin/console vortos:mcp:serve
Transport: stdio
Available Tools
──────────────────────────────────────────────────
• get_conventions Returns golden rules and naming conventions
• get_architecture Returns layer rules and CQRS/event flow
• get_best_practices Returns topic-filtered best practices
• get_mistakes Returns common antipatterns with corrections
• get_module_docs Returns module API reference
• list_project_modules Lists installed vortos/* packages
• read_project_config Returns config/ file contents
✔ Setup complete. Restart your AI client to activate.Restart your AI client
The MCP server is launched as a subprocess by the client. Restart the client after installing to pick up the new configuration.
How It Works
AI Client (Claude Code / Cursor / Windsurf / Codex)
│
│ tools/list ─────────────────────────────────────┐
│ tools/call get_conventions │
│ tools/call get_module_docs {module: "messaging"} │
▼ │
StdioTransport (stdin/stdout JSON-RPC 2.0) │
│ │
▼ │
McpServer::run() loop │
│ │
├── initialize → protocol handshake │
├── tools/list → returns all 7 tool schemas ──────┘
└── tools/call → routes to correct ToolInterface
├── GetConventionsTool
├── GetArchitectureTool
├── GetBestPracticesTool
├── GetMistakesTool
├── GetModuleDocsTool
├── ListProjectModulesTool ← reads your composer.lock
└── ReadProjectConfigTool ← reads your config/ directoryThe server speaks JSON-RPC 2.0 over stdin/stdout. The client launches php bin/console vortos:mcp:serve as a subprocess when it starts. No port is opened, no daemon runs in the background.
Supported Clients
| Client | Config Location | Format |
|---|---|---|
| Claude Code | .claude/settings.json | JSON |
| Cursor | .cursor/mcp.json | JSON |
| Windsurf | .windsurf/mcp.json | JSON |
| Codex | ~/.codex/config.toml | TOML (global only) |
Project vs Global Config
Project-level config (.claude/settings.json) is the default. It wires the MCP server only for the current project — the path to bin/console is project-specific. Use --global for clients like Codex that only support global config, or when you want the server available across all projects.