README

English | 中文

A PHP library providing contracts and interfaces for MCP (Model Context Protocol) tools integration, designed for Symfony applications.

Features

Tool Interface: Defines standard interface for MCP tools
Attribute Support: Provides AsTool attribute for tool registration
Symfony Integration: Built-in support for Symfony's dependency injection
Type Safety: Full PHP 8.1+ type declarations
Extensible: Easy to extend and customize for specific needs

Installation

composer require tourze/mcp-contracts

Quick Start

1. Implement the Tool Interface

<?php

use Tourze\MCPContracts\ToolInterface;
use Tourze\MCPContracts\Attribute\AsTool;
use OpenAIBundle\VO\FunctionParam;

#[AsTool(
    name: 'weather_tool',
    description: 'Get weather information for a specific location'
)]
class WeatherTool implements ToolInterface
{
    public function getName(): string
    {
        return 'weather_tool';
    }

    public function getDescription(): string
    {
        return 'Get weather information for a specific location';
    }

    public function getParameters(): \Traversable
    {
        yield new FunctionParam('location', 'string', 'City name or coordinates');
        yield new FunctionParam('units', 'string', 'Temperature units (celsius/fahrenheit)', false);
    }

    public function execute(array $parameters = []): string
    {
        $location = $parameters['location'] ?? '';
        $units = $parameters['units'] ?? 'celsius';
        
        // Your weather API integration here
        return "Weather in {$location}: 22°C, sunny";
    }
}

2. Register as Symfony Service

The tool will be automatically registered as a service with the mcp.tool tag thanks to the AutoconfigureTag attribute.

# config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\Tool\:
        resource: '../src/Tool/'

3. Use in Your Application

<?php

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;
use Tourze\MCPContracts\ToolInterface;

class ToolManager
{
    /** @param iterable<ToolInterface> $tools */
    public function __construct(
        #[TaggedIterator('mcp.tool')] private iterable $tools
    ) {}

    public function getTools(): array
    {
        return iterator_to_array($this->tools);
    }

    public function executeTool(string $name, array $parameters = []): string
    {
        foreach ($this->tools as $tool) {
            if ($tool->getName() === $name) {
                return $tool->execute($parameters);
            }
        }

        throw new \RuntimeException("Tool '{$name}' not found");
    }
}

API Reference

ToolInterface

Main interface for MCP tools.

Methods

getName(): string - Returns the tool's unique name
getDescription(): string - Returns tool description for LLM context
getParameters(): \Traversable<FunctionParam> - Returns parameter definitions
execute(array $parameters = []): string - Executes the tool with given parameters

AsTool Attribute

Attribute for tool registration and metadata.

Properties

string $name - Tool name
string $description - Tool description
string $method - Method to call (default: __invoke)

Contributing

Please see CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.

tourze / mcp-contracts

Maintainers

Details