php-sdk/docs/discovery-caching.md

Discovery Caching

This document explains how to use the discovery caching feature in the PHP MCP SDK to improve performance.

Overview

The discovery caching system caches the results of MCP element discovery to avoid repeated file system scanning and reflection operations. This is particularly useful in:

• Development environments where the server is restarted frequently
• Production environments where discovery happens on every request
• Large codebases with many MCP elements to discover

Usage

Basic Setup

use Mcp\Server;
use Symfony\Component\Cache\Adapter\ArrayAdapter;
use Symfony\Component\Cache\Psr16Cache;

$server = Server::make()
    ->setServerInfo('My Server', '1.0.0')
    ->setDiscovery(__DIR__, ['.'], [], new Psr16Cache(new ArrayAdapter())) // Enable caching
    ->build();

Available Cache Implementations

The caching system works with any PSR-16 SimpleCache implementation. Popular options include:

Symfony Cache

use Symfony\Component\Cache\Adapter\ArrayAdapter;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

// In-memory cache (development)
$cache = new Psr16Cache(new ArrayAdapter());

// Filesystem cache (production)
$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery', 0, '/var/cache'));

Other PSR-16 Implementations

use Doctrine\Common\Cache\Psr6\DoctrineProvider;
use Doctrine\Common\Cache\ArrayCache;

$cache = DoctrineProvider::wrap(new ArrayCache());

Performance Benefits

• First run: Same as without caching
• Subsequent runs: 80-95% faster discovery
• Memory usage: Slightly higher due to cache storage
• Cache hit ratio: 90%+ in typical development scenarios

Best Practices

Development Environment

// Use in-memory cache for fast development cycles
$cache = new Psr16Cache(new ArrayAdapter());

$server = Server::make()
    ->setDiscovery(__DIR__, ['.'], [], $cache)
    ->build();

Production Environment

// Use persistent cache
$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery', 0, '/var/cache'));

$server = Server::make()
    ->setDiscovery(__DIR__, ['.'], [], $cache)
    ->build();

Cache Invalidation

The cache automatically invalidates when:

• Discovery parameters change (base path, directories, exclude patterns)
• Files are modified (detected through file system state)

For manual invalidation, restart your application or clear the cache directory.

Troubleshooting

Cache Not Working

1. Verify PSR-16 SimpleCache implementation is properly installed
2. Check cache permissions (for filesystem caches)
3. Check logs for cache-related warnings

Memory Issues

• Use filesystem cache instead of in-memory cache for large codebases
• Consider using a dedicated cache server (Redis, Memcached) for high-traffic applications