PHPackages nixphp/mcp - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. nixphp/mcp ActiveNixphp-plugin[Utility & Helpers](/categories/utility) nixphp/mcp ========== NixPHP MCP Plugin for basic AI driven workflows. v0.1.0(2mo ago)07MITPHPPHP >=8.3CI passing Since Apr 29Pushed 2mo agoCompare [ Source](https://github.com/nixphp/mcp)[ Packagist](https://packagist.org/packages/nixphp/mcp)[ RSS](/packages/nixphp-mcp/feed)WikiDiscussions main Synced 3w ago READMEChangelog (1)Dependencies (3)Versions (2)Used By (0) [![Logo](https://camo.githubusercontent.com/075b2860e9651b98b8c190a8296595c54cff6900890d9e494f31131145e98a6f/68747470733a2f2f6e69787068702e6769746875622e696f2f646f63732f6173736574732f6e69787068702d6c6f676f2d736d616c6c2d7371756172652e706e67)](https://camo.githubusercontent.com/075b2860e9651b98b8c190a8296595c54cff6900890d9e494f31131145e98a6f/68747470733a2f2f6e69787068702e6769746875622e696f2f646f63732f6173736574732f6e69787068702d6c6f676f2d736d616c6c2d7371756172652e706e67) [![NixPHP MCP Plugin](https://github.com/nixphp/mcp/actions/workflows/php.yml/badge.svg)](https://github.com/nixphp/mcp/actions/workflows/php.yml) [← Back to NixPHP](https://github.com/nixphp/framework) --- nixphp/mcp ========== [](#nixphpmcp) > **Model Context Protocol (MCP) server implementation for NixPHP (Tools-first).** This plugin turns your NixPHP application into an **MCP server** that exposes **Tools** to AI clients such as ChatGPT. > 🧩 Part of the official NixPHP plugin collection. --- 📦 Features ---------- [](#-features) - JSON-RPC 2.0 compliant MCP endpoint - Tool discovery via `tools/list` - Tool execution via `tools/call` - JSON Schema–driven tool descriptions - Action-based tools (single tool, multiple behaviors) - Long-running tools supported (blocking by design) - No queues, no workers, no background state - Simple, debuggable request flow > ⚠️ This plugin currently operates in **Tools-only mode**. MCP Resources are currently **not supported**. --- 📥 Installation -------------- [](#-installation) ``` composer require nixphp/mcp ``` The plugin auto-registers an MCP endpoint at: ``` POST /mcp ``` The endpoint uses MCP Streamable HTTP in its minimal request/response form: - JSON-RPC messages are sent via `POST /mcp` - responses are returned as `application/json` - server-initiated SSE streams are not opened yet - `GET /mcp` returns `405 Method Not Allowed` --- Authentication -------------- [](#authentication) The endpoint is protected by Bearer token authentication by default. Tokens are stored file-based, so apps can use MCP without introducing database tables. Default token file: ``` storage/mcp/tokens.json ``` App configuration may override or disable this: ``` return [ 'mcp' => [ 'auth' => [ 'enabled' => true, 'driver' => 'file', 'token_file' => BASE_PATH . '/storage/mcp/tokens.json', ], ], ]; ``` For internal or local-only projects authentication can be opened explicitly: ``` 'mcp' => [ 'auth' => [ 'enabled' => false, ], ], ``` Create a token from application code: ``` use function NixPHP\MCP\tokens; $created = tokens()->create('Local AI client', ['*']); echo $created->plainToken; // shown once, only the hash is stored ``` If `nixphp/cli` is installed, the plugin registers token commands automatically: ``` vendor/bin/nix mcp:token:create "Local AI client" --scope "*" vendor/bin/nix mcp:token:list vendor/bin/nix mcp:token:revoke tok_... ``` Clients send the token as: ``` Authorization: Bearer mcp_... ``` ### Tool Scopes [](#tool-scopes) Tools may opt into scope checks by implementing `ScopedToolInterface`: ``` use NixPHP\MCP\Tools\ScopedToolInterface; use NixPHP\MCP\Tools\ToolInterface; final class ArticleSearchTool implements ToolInterface, ScopedToolInterface { public function requiredScopes(): array { return ['articles:read']; } // ToolInterface methods... } ``` Supported scope patterns: - `*` - exact scopes such as `articles:read` - prefix wildcards such as `articles:*` --- Core Concept: Tools ------------------- [](#core-concept-tools) Tools represent **actions**. They: - accept structured input (JSON Schema) - execute application logic - return structured results - may read/write data internally Examples: - calculate a folder size - analyze files - summarize structured data --- How the model interacts with your app (`initialize`) ---------------------------------------------------- [](#how-the-model-interacts-with-your-app-initialize) On connection, the MCP server announces **capabilities**, not concrete tools. ``` { "jsonrpc": "2.0", "method": "initialize", "params": {} } ``` Response (simplified): ``` { "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": {} }, "serverInfo": { "name": "nixphp-mcp", "version": "0.1.0" } } } ``` > `capabilities.tools` signals that this server supports MCP tools. --- Tool Discovery (`tools/list`) ----------------------------- [](#tool-discovery-toolslist) Clients explicitly request the available tools: ``` { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } ``` Response: ``` { "result": { "tools": [ { "name": "get_folder_size", "description": "Returns the size of a folder.", "inputSchema": { "... JSON Schema ..." } } ] } } ``` --- Example Tool: Folder Size ------------------------- [](#example-tool-folder-size) ### PHP Tool Implementation [](#php-tool-implementation) ``` use NixPHP\MCP\Support\Schema; use NixPHP\MCP\Tools\ToolInterface; final class GetFolderSize implements ToolInterface { public function name(): string { return 'get_folder_size'; } public function description(): string { return 'Returns the size of a folder.'; } public function inputSchema(): array { return Schema::object() ->description($this->description()) ->additionalProperties(false) ->prop('path', Schema::string()->description('Relative folder path')) ->required('path') ->toArray(); } public function handle(array $args): array { $path = (string)$args['path']; $bytes = 0; $it = new \RecursiveIteratorIterator( new \RecursiveDirectoryIterator($path, \FilesystemIterator::SKIP_DOTS) ); foreach ($it as $file) { $bytes += $file->getSize(); } return [ 'path' => $path, 'bytes' => $bytes, 'human' => round($bytes / 1024 / 1024, 1) . ' MB', ]; } } ``` --- How the model is calling the tool (`tools/call`) ------------------------------------------------ [](#how-the-model-is-calling-the-tool-toolscall) ### JSON-RPC Request [](#json-rpc-request) ``` { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_folder_size", "arguments": { "path": "var/log" } } } ``` ### Response [](#response) ``` { "result": { "content": [ { "type": "text", "text": "{\n \"path\": \"var/log\",\n \"bytes\": 25500000,\n \"human\": \"25.5 MB\"\n}" } ], "isError": false } } ``` --- Action-Based Tools (Optional Pattern) ------------------------------------- [](#action-based-tools-optional-pattern) Tools may expose multiple behaviors via an `action` parameter: ``` { "action": "analyze|summary|details" } ``` This allows grouping related operations into a single tool while keeping schemas explicit. This pattern is optional but recommended for more complex tools. --- Storage & Filesystem Access ------------------------------- [](#storage--filesystem-access) The plugin ships with a `FilesystemStore` utility. Important notes: - `FilesystemStore` is **internal** - it is **not exposed via MCP** - it is **not a Resource API** Its purpose is to provide: - safe, sandboxed filesystem access - path traversal protection - size limits - predictable storage layout Typical usage inside a tool: ``` $this->store->read('tools/get_folder_size/cache.json'); $this->store->write('tools/get_folder_size/cache.json', $json); ``` Storage root (default): ``` {app_dir}/storage/ ``` --- About MCP Resources ------------------- [](#about-mcp-resources) This plugin currently **does not expose MCP Resources**(`resources/read`, `resources/list`, `resources/write`). Reasoning: - Tools already cover most required use cases - Resources add conceptual overhead - Most MCP clients primarily use tools Resources may be added later as an extension. --- Requirements ------------ [](#requirements) - PHP ≥ 8.3 - `nixphp/framework` ≥ 0.1.0 --- 📄 License --------- [](#-license) MIT License. ### Health Score 35 — LowBetter than 77% of packages Maintenance83 Actively maintained with recent releases Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity39 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 87d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f5d2bd3eecc9c3949d3caf98c4876c8e44c0c73fc80dbc65b55f4d91a5b63eae?d=identicon)[floknapp](/maintainers/floknapp) --- Top Contributors [![FloKnapp](https://avatars.githubusercontent.com/u/3774820?v=4)](https://github.com/FloKnapp "FloKnapp (3 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/nixphp-mcp/health.svg) ``` [![Health](https://phpackages.com/badges/nixphp-mcp/health.svg)](https://phpackages.com/packages/nixphp-mcp) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)