README

A PHP-based Model Context Protocol (MCP) server skeleton that supports both HTTP and stdio communication methods. This server can be integrated with VS Code Copilot and other MCP-compatible clients.

Features

Dual Communication: HTTP REST API and stdio (JSON-RPC 2.0)
Auto-discovery: Automatically discovers tools, prompts, and resources
Code Generation: Built-in commands to generate new tools and prompts
Flight PHP Framework: Lightweight and fast PHP framework
Logging: Comprehensive logging for debugging
Testing Scripts: Ready-to-use test scripts for both modes

Quick Start

Install Run this command from the directory in which you want to install your new Flight PHP application. (this will require PHP 7.4 or newer)
```
 composer create-project stribus/mcp-flightphp-server-skeleton cool-project-name
```

Run this command from the directory in which you want to install your new Flight PHP application. (this will require PHP 7.4 or newer)

Test HTTP Server

composer start
# or
php -S localhost:8000 -t public

Test stdio Server
```
php mcp-server.php
```

Usage Methods

1. HTTP Server Mode

The HTTP server exposes MCP functionality via REST endpoints:

Start the server:

composer start

Available endpoints:

GET / - Server information
POST /tools/list - List available tools
POST /tools/call - Execute a tool
POST /prompts/list - List available prompts
POST /prompts/get - Get a prompt
POST /resources/list - List available resources
POST /resources/read - Read a resource

Test the HTTP server:

# Windows PowerShell
.\test-http-server.ps1

# Or manually test endpoints
curl -X POST http://localhost:8000/tools/list
curl -X POST http://localhost:8000/tools/call -H "Content-Type: application/json" -d '{"name":"hello-world-tool","arguments":{"firstName":"John","lastName":"Doe"}}'

2. stdio Mode (JSON-RPC 2.0)

The stdio server communicates via standard input/output using JSON-RPC 2.0 protocol:

Start the server:

php mcp-server.php

Test JSON-RPC commands:

# Windows PowerShell
.\test-mcp-server.ps1

# Or send commands manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | php mcp-server.php
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | php mcp-server.php
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"hello-world-tool","arguments":{"firstName":"VS Code","lastName":"Copilot"}}}' | php mcp-server.php

3. VS Code Integration

For VS Code Copilot integration, configure the MCP server in your VS Code settings:

mcp-config.json example:

{
  "mcpServers": {
    "php-mcp-server": {
      "command": "php",
      "args": ["path/to/mcp-server.php"],
      "env": {}
    }
  }
}

Creating Tools

Tools are executable functions that can be called by MCP clients.

Generate a new tool:

vendor/bin/runway make:tool MyCustomTool

Tool Structure:

<?php

namespace app\tools;

use app\helpers\AbstractMCPTool;

class MyCustomTool extends AbstractMCPTool
{
    protected string $name = 'my-custom-tool';
    protected string $description = 'Description of what this tool does';
    protected ?string $title = 'My Custom Tool';

    protected array $arguments = [
        [
            'name' => 'input',
            'type' => 'string',
            'description' => 'Input parameter description',
            'required' => true,
        ],
    ];

    protected null|array|string $outputSchema = [
        'type' => 'object',
        'properties' => [
            'result' => [
                'type' => 'string',
                'description' => 'The result of the operation',
            ],
        ],
    ];

    public function execute(array $arguments): mixed
    {
        $input = $arguments['input'] ?? '';
        
        // Your tool logic here
        
        return [
            'result' => 'Processed: ' . $input,
        ];
    }
}

Tool Properties:

$name: Unique identifier for the tool
$description: What the tool does
$title: Human-readable title
$arguments: Array of input parameters with types and validation
$outputSchema: Expected output structure
execute(): Main logic that processes arguments and returns results

Creating Prompts

Prompts are templates that can generate dynamic text based on context.

Generate a new prompt:

vendor/bin/runway make:prompt MyCustomPrompt

Prompt Structure:

<?php

namespace app\prompts;

use app\helpers\AbstractMCPPrompt;

class MyCustomPrompt extends AbstractMCPPrompt
{
    protected string $name = 'my_custom_prompt';
    protected string $description = 'Generate custom content based on input';
    protected ?string $title = 'My Custom Prompt';
    
    protected array $arguments = [
        'topic' => [
            'type' => 'string',
            'description' => 'The topic to generate content about',
            'required' => true,
        ],
        'style' => [
            'type' => 'string',
            'description' => 'Writing style (formal, casual, technical)',
            'required' => false,
        ],
    ];

    public function getPromptText(array $context): string
    {
        $topic = $context['topic'] ?? '';
        $style = $context['style'] ?? 'formal';

        return "Write a {$style} explanation about {$topic}. " .
               "Include examples and practical applications.";
    }
}

Prompt Properties:

$name: Unique identifier for the prompt
$description: What the prompt generates
$title: Human-readable title
$arguments: Context variables the prompt expects
getPromptText(): Method that generates the prompt text based on context

Project Structure

├── app/
│   ├── tools/           # Tool implementations
│   ├── prompts/         # Prompt implementations
│   ├── resources/       # Resource implementations
│   ├── helpers/         # Abstract base classes
│   └── core/            # MCP service registries
├── commands/            # Runway commands for code generation
├── public/              # HTTP server entry point
├── mcp-server.php       # stdio server entry point
└── vendor/              # Dependencies

Available MCP Methods

JSON-RPC 2.0 Methods:

initialize - Initialize the MCP connection
tools/list - List all available tools
tools/call - Execute a specific tool
prompts/list - List all available prompts
prompts/get - Get a specific prompt
resources/list - List all available resources
resources/read - Read a specific resource

Logging and Debugging

The server generates detailed logs in mcp-server.log for debugging purposes. Monitor this file to see:

Incoming requests
Server responses
Errors and exceptions
Tool execution details

Common Issues

Server won't start: Ensure PHP is in your PATH and dependencies are installed
JSON parsing errors: Verify JSON-RPC message formatting
Tool not found: Check tool is properly registered and follows naming conventions
Permission errors: Verify write permissions for log files

Requirements

PHP 7.4 or higher
Composer
ext-json extension

License

MIT License - see LICENSE file for details.

stribus / mcp-flightphp-server-skeleton

Maintainers

Details