README

Build AI-powered tools for your Yii3 application with Model Context Protocol

A framework for building Model Context Protocol (MCP) servers in Yii3 applications. Enable AI assistants like GitHub Copilot to interact with your application through custom tools.

What is MCP?

Model Context Protocol is an open protocol that enables AI assistants to interact with external tools and data sources. Think of it as an API for AI - instead of REST endpoints for humans, MCP provides a standardized way for AI to:

Query your database
Read project files
Execute commands
Analyze data
Interact with your application

Features

Framework, not an app - Integrate into any Yii3 project
Tool-based architecture - Build custom tools by implementing McpToolInterface
Simple API - One interface (McpToolInterface) is all you need to create powerful AI tools
Type-safe - Full PHP 8.1+ type declarations and PHPDoc
Production-ready - Security patterns, error handling, validation
Easy integration - Works with VS Code, Cursor, and other MCP clients
Well-documented - Comprehensive guides and examples

Quick Start

1. Install via Composer

composer require ldkafka/yii3-mcp-server

2. Copy Configuration Templates

Configure based on your Yii3 app structure:

# For yiisoft/app template (uses config/console/ and config/common/di/):
cp vendor/ldkafka/yii3-mcp-server/config/commands.php config/console/commands.php
cp vendor/ldkafka/yii3-mcp-server/config/di/mcp-template.php config/common/di/mcp.php

# For custom Yii3 apps (uses config/ root level):
# cp vendor/ldkafka/yii3-mcp-server/config/commands.php config/commands.php
# cp vendor/ldkafka/yii3-mcp-server/config/di-console.php config/di-console.php

Note: The standard yiisoft/app template uses config/console/ for console commands and config/common/di/ for DI configuration.

Or manually edit config/console/commands.php (for yiisoft/app template):

use YiiMcp\McpServer\Command\McpCommand;

return [
    'hello' => Console\HelloCommand::class,
    'mcp:serve' => McpCommand::class, // Add this line
];

3. Configure DI Container

Create config/common/di/mcp.php (for yiisoft/app template):

<?php

declare(strict_types=1);

use YiiMcp\McpServer\McpServer;

return [
    McpServer::class => static fn() => new McpServer([
        // Add your tool instances here
        // new MyCustomTool(),
    ]),
];

For custom tool registration, optionally create config/di-console.php to define tool dependencies.

4. Run the Server

php yii mcp:serve

5. Create Your Own Tools

The power of this framework is in creating custom tools by implementing McpToolInterface:

use YiiMcp\McpServer\Contract\McpToolInterface;

class MyCustomTool implements McpToolInterface
{
    public function getName(): string
    {
        return 'my_custom_tool';
    }

    public function getDescription(): string
    {
        return 'Does something useful for AI assistants';
    }

    public function getInputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'input' => ['type' => 'string', 'description' => 'Input parameter'],
            ],
            'required' => ['input'],
        ];
    }

    public function execute(array $arguments): array
    {
        // Your tool logic here
        return [
            'result' => 'Tool executed successfully',
            'data' => $arguments['input'],
        ];
    }
}

Then register your tool in config/common/di/mcp.php:

return [
    McpServer::class => static fn() => new McpServer([
        new MyCustomTool(),
    ]),
];

See docs/CREATING_TOOLS.md for detailed guide.

6. Integrate with Your Editor

Add to VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "my-yii3-app": {
      "command": "php",
      "args": ["yii", "mcp:serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

That's it! Your AI assistant can now use your tools.

Example: Database Query Tool

The package includes MysqlQueryTool as a reference implementation:

use YiiMcp\McpServer\Contract\McpToolInterface;
use Yiisoft\Db\Connection\ConnectionInterface;

class MysqlQueryTool implements McpToolInterface
{
    public function __construct(private ConnectionInterface $db) {}
    
    public function getName(): string {
        return 'query_database';
    }
    
    public function getDescription(): string {
        return 'Execute read-only SQL queries';
    }
    
    public function getInputSchema(): array {
        return [
            'type' => 'object',
            'properties' => [
                'sql' => ['type' => 'string', 'description' => 'SQL SELECT query']
            ],
            'required' => ['sql']
        ];
    }
    
    public function execute(array $args): array {
        // Validate, execute, return results
    }
}

Ask Copilot: "What tables are in the database?" and it will use this tool automatically!

Creating Custom Tools

Implement McpToolInterface:

use YiiMcp\McpServer\Contract\McpToolInterface;

class MyCustomTool implements McpToolInterface
{
    public function getName(): string {
        return 'my_tool';
    }
    
    public function getDescription(): string {
        return 'What this tool does for the AI';
    }
    
    public function getInputSchema(): array {
        return [
            'type' => 'object',
            'properties' => [
                'param' => ['type' => 'string']
            ]
        ];
    }
    
    public function execute(array $args): array {
        // Your logic here
        return [
            'content' => [
                ['type' => 'text', 'text' => 'Result data']
            ]
        ];
    }
}

McpServer::class => [
    '__construct()' => [
        'tools' => [
            Reference::to(MyCustomTool::class),
        ],
    ],
],

Documentation

📖 Editor Integration - VS Code, Docker, WSL, SSH setup
📖 Creating Tools - Build custom tools guide
📖 Installation - Detailed setup instructions
📖 Deployment - Production deployment strategies
📖 Examples - Complete working examples

Deployment Scenarios

Local Development

{
  "command": "php",
  "args": ["yii", "mcp:serve"],
  "cwd": "${workspaceFolder}"
}

Docker

{
  "command": "docker",
  "args": ["exec", "-i", "app-container", "php", "yii", "mcp:serve"]
}

WSL (Windows)

{
  "command": "wsl",
  "args": ["bash", "-c", "cd /mnt/c/project && php yii mcp:serve"]
}

See EDITOR_INTEGRATION.md for more scenarios.

Security

Read-Only by Default: The example MysqlQueryTool enforces read-only operations:

// Only allows: SELECT, SHOW, DESCRIBE, EXPLAIN
$allowedKeywords = ['SELECT', 'SHOW', 'DESCRIBE', 'EXPLAIN'];

Recommendations:

Use dedicated read-only database users
Store credentials in params-local.php (gitignored)
Validate all tool inputs
Log tool usage for auditing

Requirements

PHP: 8.1 or higher
Yii3: yiisoft/yii-console ^2.0
Optional: Database extensions for DB tools

Architecture

┌─────────────┐
│ AI Assistant │ (GitHub Copilot, Claude Desktop, etc.)
└──────┬──────┘
       │ JSON-RPC over stdio
       ▼
┌─────────────────┐
│   McpServer     │  Framework core (this package)
│  - Tool registry │
│  - Protocol impl│
└────────┬────────┘
         │
    ┌────┴────┬────────┬─────────┐
    ▼         ▼        ▼         ▼
┌────────┐ ┌────┐  ┌────┐   ┌────────┐
│MySQL   │ │File│  │Cache│  │Custom  │
│Query   │ │Read│  │Tool │  │Tools   │
│Tool    │ │Tool│  │     │  │        │
└────────┘ └────┘  └────┘   └────────┘

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new features
Submit a pull request

License

This project is licensed under the BSD-3-Clause License.

Support

Issues: GitHub Issues
Documentation: docs/
MCP Specification: modelcontextprotocol.io

Credits

Built with ❤️ for the Yii3 community.

MCP Protocol: Anthropic
Yii Framework: Yii Software

Ready to empower your AI assistant? Install now and start building custom tools!

composer require ldkafka/yii3-mcp-server

ldkafka / yii3-mcp-server

Maintainers

Details