mcp -incubator

This MCP server is a Hyperf-based implementation of the Model Context Protocol (MCP). It exposes a set of annotation-driven tools, prompts and resources that can be registered programmatically in your Hyperf application. By leveraging Redis for session management and JSON schema validation, it provides type-safe, structured inputs and outputs for MCP tools, prompts and resources. You can register MCP tools, prompts, and resources using the #[McpTool], #[McpPrompt], and #[McpResource] annotations respectively, which automatically generate schemas from method signatures and wire up endpoints via the MCP server router. The server is designed for multi-server setups, allowing you to group related tools and enable or disable features as needed. Typical usage involves registering routes that route to the MCP server handler and configuring Redis-backed sessions for distributed deployments.

To interact with the server, send requests to the /mcp endpoint (or group-specific endpoints like /mcp/math or /mcp/dev if you configure grouped handlers). Tools will appear with their generated schemas, prompts will provide templated conversational or guidance content, and resources will expose data or read-only content such as system information or configuration dumps. Authentication and access control can be implemented via the MCP server’s metadata and Redis-backed session management. The annotation-driven approach means you can rapidly expose new utilities or prompts by simply annotating methods in your service classes.

Prerequisites

• PHP 8.0+ and Composer
• Redis (for session management and potentially distributed state)
• A running Hyperf application or project where you want to integrate the MCP server

Installation steps

1. Create or navigate to your Hyperf project
2. Install the MCP incubator package via Composer:

composer require hyperf/mcp-server-incubator

3. Configure routes to expose the MCP handler. In your routes file (e.g., config/routes.php), register the MCP route if not already present:

<?php
use Hyperf\Context\ApplicationContext;
use Hyperf\HttpServer\Router\Router;
use Hyperf\McpServer\Server;

Router::addRoute(['POST', 'GET', 'DELETE'], '/mcp', function () {
    return ApplicationContext::getContainer()->get(Server::class)->handler();
});

4. Ensure Redis is running and accessible. Set up environment variables as needed, e.g. in your .env or server config:

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
APP_ENV=production
APP_DEBUG=false

5. Publish or register your MCP tools, prompts, and resources by annotating PHP classes/methods with #[McpTool], #[McpPrompt], #[McpResource], as demonstrated in the documentation. Restart your Hyperf server to pick up changes.

6. Verify the MCP server is responding by hitting the /mcp endpoint with a test request (e.g., via curl or your frontend tooling).

Note: If you prefer not to use Docker, you can adapt the mcp_config to a PHP-native run command or a PHP-FPM based deployment, but the example provided uses Docker for portability.

Tips and common issues:

• Ensure Redis is accessible from your Hyperf environment to enable Redis-backed sessions and distributed state.
• When using annotations, make sure PHP's opcache is configured to recognize changes to annotated methods without requiring a full server restart.
• Grouping tools (e.g., by 'math' or 'development') via route handlers helps keep large MCP deployments organized and reduces surface area for route exposure.
• The automatic JSON schema generation relies on base PHP types (string, int, float, bool, array). Complex types (classes/interfaces) are not included in the generated schema.
• If you modify annotation configurations, you may need to refresh the route handler cache or restart the Hyperf server to reflect changes.
• For production, consider enabling SSL/TLS at the web server level and integrating proper authentication for MCP endpoints.