Custom Visual
Add data to get started
<%= contributor.name %>
Preparing search...
) : (
```
### Example 5: Asynchronous I/O in Node.js
```javascript
// BAD: Blocking file read
const data = fs.readFileSync('file.txt');
// GOOD: Non-blocking file read
fs.readFile('file.txt', (err, data) => {
if (err) throw err;
// process data
});
```
### Example 6: Profiling a Python Function
```python
import cProfile
import pstats
def slow_function():
...
cProfile.run('slow_function()', 'profile.stats')
p = pstats.Stats('profile.stats')
p.sort_stats('cumulative').print_stats(10)
```
### Example 7: Using Redis for Caching in Node.js
```javascript
const redis = require('redis');
const client = redis.createClient();
function getCachedData(key, fetchFunction) {
return new Promise((resolve, reject) => {
client.get(key, (err, data) => {
if (data) return resolve(JSON.parse(data));
fetchFunction().then(result => {
client.setex(key, 3600, JSON.stringify(result));
resolve(result);
});
});
});
}
```
---
## References and Further Reading
- [Google Web Fundamentals: Performance](https://web.dev/performance/)
- [MDN Web Docs: Performance](https://developer.mozilla.org/en-US/docs/Web/Performance)
- [OWASP: Performance Testing](https://owasp.org/www-project-performance-testing/)
- [Microsoft Performance Best Practices](https://learn.microsoft.com/en-us/azure/architecture/best-practices/performance)
- [PostgreSQL Performance Optimization](https://wiki.postgresql.org/wiki/Performance_Optimization)
- [MySQL Performance Tuning](https://dev.mysql.com/doc/refman/8.0/en/optimization.html)
- [Node.js Performance Best Practices](https://nodejs.org/en/docs/guides/simple-profiling/)
- [Python Performance Tips](https://docs.python.org/3/library/profile.html)
- [Java Performance Tuning](https://www.oracle.com/java/technologies/javase/performance.html)
- [.NET Performance Guide](https://learn.microsoft.com/en-us/dotnet/standard/performance/)
- [WebPageTest](https://www.webpagetest.org/)
- [Lighthouse](https://developers.google.com/web/tools/lighthouse)
- [Prometheus](https://prometheus.io/)
- [Grafana](https://grafana.com/)
- [k6 Load Testing](https://k6.io/)
- [Gatling](https://gatling.io/)
- [Locust](https://locust.io/)
- [OpenTelemetry](https://opentelemetry.io/)
- [Jaeger](https://www.jaegertracing.io/)
- [Zipkin](https://zipkin.io/)
---
## Conclusion
Performance optimization is an ongoing process. Always measure, profile, and iterate. Use these best practices, checklists, and troubleshooting tips to guide your development and code reviews for high-performance, scalable, and efficient software. If you have new tips or lessons learned, add them here—let's keep this guide growing!
---
================================================
FILE: instructions/php-mcp-server.instructions.md
================================================
---
description: 'Best practices for building Model Context Protocol servers in PHP using the official PHP SDK with attribute-based discovery and multiple transport options'
applyTo: '**/*.php'
---
# PHP MCP Server Development Best Practices
This guide provides best practices for building Model Context Protocol (MCP) servers using the official PHP SDK maintained in collaboration with The PHP Foundation.
## Installation and Setup
### Install via Composer
```bash
composer require mcp/sdk
```
### Project Structure
Organize your PHP MCP server project:
```
my-mcp-server/
├── composer.json
├── src/
│ ├── Tools/
│ │ ├── Calculator.php
│ │ └── FileManager.php
│ ├── Resources/
│ │ ├── ConfigProvider.php
│ │ └── DataProvider.php
│ ├── Prompts/
│ │ └── PromptGenerator.php
│ └── Server.php
├── server.php # Server entry point
└── tests/
└── ToolsTest.php
```
### Composer Configuration
```json
{
"name": "your-org/mcp-server",
"description": "MCP Server for...",
"type": "project",
"require": {
"php": "^8.2",
"mcp/sdk": "^0.1"
},
"require-dev": {
"phpunit/phpunit": "^10.0"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
```
## Server Implementation
### Basic Server with Attribute Discovery
Create your server entry point:
```php
#!/usr/bin/env php
setServerInfo('My MCP Server', '1.0.0')
->setDiscovery(__DIR__, ['.'])
->build();
$transport = new StdioTransport();
$server->run($transport);
```
### Server with Caching
Use PSR-16 cache for better performance:
```php
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;
$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery'));
$server = Server::builder()
->setServerInfo('My MCP Server', '1.0.0')
->setDiscovery(
basePath: __DIR__,
scanDirs: ['.', 'src'],
excludeDirs: ['vendor', 'tests'],
cache: $cache
)
->build();
```
### Manual Registration
Register capabilities programmatically:
```php
use App\Tools\Calculator;
use App\Resources\Config;
$server = Server::builder()
->setServerInfo('My MCP Server', '1.0.0')
->addTool([Calculator::class, 'add'], 'add')
->addTool([Calculator::class, 'multiply'], 'multiply')
->addResource([Config::class, 'getSettings'], 'config://app/settings')
->build();
```
## Tool Development
### Simple Tool with Attribute
```php
uniqid(),
'email' => $email,
'age' => $age,
'firstName' => $firstName
];
}
}
```
### Tool with Complex Return Types
```php
use Mcp\Schema\Content\{TextContent, ImageContent};
class ReportGenerator
{
#[McpTool]
public function generateReport(string $type): array
{
return [
new TextContent('Report generated:'),
TextContent::code($this->generateCode($type), 'php'),
new TextContent('Summary: All checks passed.')
];
}
#[McpTool]
public function getChart(string $chartType): ImageContent
{
$imageData = $this->generateChartImage($chartType);
return new ImageContent(
data: base64_encode($imageData),
mimeType: 'image/png'
);
}
}
```
### Tool with Match Expression
```php
#[McpTool(name: 'calculate')]
public function performCalculation(float $a, float $b, string $operation): float
{
return match($operation) {
'add' => $a + $b,
'subtract' => $a - $b,
'multiply' => $a * $b,
'divide' => $b != 0 ? $a / $b :
throw new \InvalidArgumentException('Division by zero'),
default => throw new \InvalidArgumentException('Invalid operation')
};
}
```
## Resource Implementation
### Static Resource
```php
'1.0.0',
'debug' => false,
'features' => ['auth', 'logging']
];
}
}
```
### Resource Template with Variables
```php
use Mcp\Capability\Attribute\McpResourceTemplate;
class UserProvider
{
/**
* Retrieves user profile information by ID and section.
*/
#[McpResourceTemplate(
uriTemplate: 'user://{userId}/profile/{section}',
name: 'user_profile',
description: 'User profile data by section',
mimeType: 'application/json'
)]
public function getUserProfile(string $userId, string $section): array
{
// Variable order must match URI template order
return $this->users[$userId][$section] ??
throw new \InvalidArgumentException("Profile section not found");
}
}
```
### Resource with File Content
```php
use Mcp\Schema\Content\{TextResourceContents, BlobResourceContents};
class FileProvider
{
#[McpResource(uri: 'file://readme.txt', mimeType: 'text/plain')]
public function getReadme(): TextResourceContents
{
return new TextResourceContents(
uri: 'file://readme.txt',
mimeType: 'text/plain',
text: file_get_contents(__DIR__ . '/README.txt')
);
}
#[McpResource(uri: 'file://image.png', mimeType: 'image/png')]
public function getImage(): BlobResourceContents
{
$imageData = file_get_contents(__DIR__ . '/image.png');
return new BlobResourceContents(
uri: 'file://image.png',
mimeType: 'image/png',
blob: base64_encode($imageData)
);
}
}
```
## Prompt Implementation
### Basic Prompt
```php
'assistant', 'content' => 'You are an expert code reviewer.'],
['role' => 'user', 'content' => "Review this {$language} code focusing on {$focus}:\n\n```{$language}\n{$code}\n```"]
];
}
}
```
### Prompt with Mixed Content
```php
use Mcp\Schema\Content\{TextContent, ImageContent};
use Mcp\Schema\PromptMessage;
use Mcp\Schema\Enum\Role;
#[McpPrompt]
public function analyzeImage(string $imageUrl, string $question): array
{
$imageData = file_get_contents($imageUrl);
return [
new PromptMessage(Role::Assistant, [
new TextContent('You are an image analysis expert.')
]),
new PromptMessage(Role::User, [
new TextContent($question),
new ImageContent(
data: base64_encode($imageData),
mimeType: 'image/jpeg'
)
])
];
}
```
## Completion Providers
### Value List Completion
```php
use Mcp\Capability\Attribute\{McpPrompt, CompletionProvider};
#[McpPrompt]
public function generateContent(
#[CompletionProvider(values: ['blog', 'article', 'tutorial', 'guide'])]
string $contentType,
#[CompletionProvider(values: ['beginner', 'intermediate', 'advanced'])]
string $difficulty
): array
{
return [
['role' => 'user', 'content' => "Create a {$difficulty} level {$contentType}"]
];
}
```
### Enum Completion
```php
enum Priority: string
{
case LOW = 'low';
case MEDIUM = 'medium';
case HIGH = 'high';
}
enum Status
{
case DRAFT;
case PUBLISHED;
case ARCHIVED;
}
#[McpResourceTemplate(uriTemplate: 'tasks/{taskId}')]
public function getTask(
string $taskId,
#[CompletionProvider(enum: Priority::class)]
string $priority,
#[CompletionProvider(enum: Status::class)]
string $status
): array
{
return $this->tasks[$taskId] ?? [];
}
```
### Custom Completion Provider
```php
use Mcp\Capability\Prompt\Completion\ProviderInterface;
class UserIdCompletionProvider implements ProviderInterface
{
public function __construct(
private DatabaseService $db
) {}
public function getCompletions(string $currentValue): array
{
return $this->db->searchUserIds($currentValue);
}
}
#[McpResourceTemplate(uriTemplate: 'user://{userId}/profile')]
public function getUserProfile(
#[CompletionProvider(provider: UserIdCompletionProvider::class)]
string $userId
): array
{
return $this->users[$userId] ??
throw new \InvalidArgumentException('User not found');
}
```
## Transport Options
### Stdio Transport
For command-line integration (default):
```php
use Mcp\Server\Transport\StdioTransport;
$transport = new StdioTransport();
$server->run($transport);
```
### HTTP Transport
For web-based integration:
```php
use Mcp\Server\Transport\StreamableHttpTransport;
use Nyholm\Psr7\Factory\Psr17Factory;
$psr17Factory = new Psr17Factory();
$request = $psr17Factory->createServerRequestFromGlobals();
$transport = new StreamableHttpTransport(
$request,
$psr17Factory, // Response factory
$psr17Factory // Stream factory
);
$response = $server->run($transport);
// Send response in your web framework
foreach ($response->getHeaders() as $name => $values) {
foreach ($values as $value) {
header("$name: $value", false);
}
}
http_response_code($response->getStatusCode());
echo $response->getBody();
```
## Session Management
### In-Memory Sessions (Default)
```php
$server = Server::builder()
->setServerInfo('My Server', '1.0.0')
->setSession(ttl: 7200) // 2 hours
->build();
```
### File-Based Sessions
```php
use Mcp\Server\Session\FileSessionStore;
$server = Server::builder()
->setServerInfo('My Server', '1.0.0')
->setSession(new FileSessionStore(__DIR__ . '/sessions'))
->build();
```
### Custom Session Store
```php
use Mcp\Server\Session\InMemorySessionStore;
$server = Server::builder()
->setServerInfo('My Server', '1.0.0')
->setSession(new InMemorySessionStore(3600))
->build();
```
## Error Handling
### Exception Handling in Tools
```php
#[McpTool]
public function divideNumbers(float $a, float $b): float
{
if ($b === 0.0) {
throw new \InvalidArgumentException('Division by zero is not allowed');
}
return $a / $b;
}
#[McpTool]
public function processFile(string $filename): string
{
if (!file_exists($filename)) {
throw new \InvalidArgumentException("File not found: {$filename}");
}
if (!is_readable($filename)) {
throw new \RuntimeException("File not readable: {$filename}");
}
return file_get_contents($filename);
}
```
### Custom Error Responses
The SDK automatically converts exceptions into JSON-RPC error responses that MCP clients understand.
## Testing
### PHPUnit Tests for Tools
```php
calculator = new Calculator();
}
public function testAdd(): void
{
$result = $this->calculator->add(5, 3);
$this->assertSame(8, $result);
}
public function testDivideByZero(): void
{
$this->expectException(\InvalidArgumentException::class);
$this->expectExceptionMessage('Division by zero');
$this->calculator->divide(10, 0);
}
}
```
### Testing Server Discovery
```php
public function testServerDiscoversTools(): void
{
$server = Server::builder()
->setServerInfo('Test Server', '1.0.0')
->setDiscovery(__DIR__ . '/../src', ['.'])
->build();
$capabilities = $server->getCapabilities();
$this->assertArrayHasKey('tools', $capabilities);
$this->assertNotEmpty($capabilities['tools']);
}
```
## Performance Best Practices
### Use Discovery Caching
Always use caching in production:
```php
use Symfony\Component\Cache\Adapter\RedisAdapter;
use Symfony\Component\Cache\Psr16Cache;
$redis = new \Redis();
$redis->connect('127.0.0.1', 6379);
$cache = new Psr16Cache(new RedisAdapter($redis));
$server = Server::builder()
->setServerInfo('My Server', '1.0.0')
->setDiscovery(
basePath: __DIR__,
scanDirs: ['src'],
excludeDirs: ['vendor', 'tests', 'var'],
cache: $cache
)
->build();
```
### Optimize Scan Directories
Only scan necessary directories:
```php
$server = Server::builder()
->setDiscovery(
basePath: __DIR__,
scanDirs: ['src/Tools', 'src/Resources'], // Specific dirs
excludeDirs: ['vendor', 'tests', 'var', 'cache']
)
->build();
```
### Use OPcache
Enable OPcache in production for better PHP performance:
```ini
; php.ini
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=10000
opcache.validate_timestamps=0
```
## Framework Integration
### Laravel Integration
```php
// app/Console/Commands/McpServer.php
namespace App\Console\Commands;
use Illuminate\Console\Command;
use Mcp\Server;
use Mcp\Server\Transport\StdioTransport;
class McpServer extends Command
{
protected $signature = 'mcp:serve';
protected $description = 'Start MCP server';
public function handle()
{
$server = Server::builder()
->setServerInfo('Laravel MCP Server', '1.0.0')
->setDiscovery(app_path(), ['Tools', 'Resources'])
->build();
$transport = new StdioTransport();
$server->run($transport);
}
}
```
### Symfony Integration
```php
// Use symfony/mcp-bundle for native integration
composer require symfony/mcp-bundle
```
## Deployment
### Docker Deployment
```dockerfile
FROM php:8.2-cli
# Install extensions
RUN docker-php-ext-install pdo pdo_mysql
# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
# Set working directory
WORKDIR /app
# Copy application
COPY . /app
# Install dependencies
RUN composer install --no-dev --optimize-autoloader
# Make server executable
RUN chmod +x /app/server.php
CMD ["php", "/app/server.php"]
```
### Systemd Service
```ini
[Unit]
Description=MCP PHP Server
After=network.target
[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/mcp-server
ExecStart=/usr/bin/php /var/www/mcp-server/server.php
Restart=always
[Install]
WantedBy=multi-user.target
```
## Configuration for MCP Clients
### Claude Desktop Configuration
```json
{
"mcpServers": {
"php-server": {
"command": "php",
"args": ["/absolute/path/to/server.php"]
}
}
}
```
### MCP Inspector Testing
```bash
npx @modelcontextprotocol/inspector php /path/to/server.php
```
## Additional Resources
- [Official PHP SDK Repository](https://github.com/modelcontextprotocol/php-sdk)
- [MCP Elements Documentation](https://github.com/modelcontextprotocol/php-sdk/blob/main/docs/mcp-elements.md)
- [Server Builder Documentation](https://github.com/modelcontextprotocol/php-sdk/blob/main/docs/server-builder.md)
- [Transport Documentation](https://github.com/modelcontextprotocol/php-sdk/blob/main/docs/transports.md)
- [Examples](https://github.com/modelcontextprotocol/php-sdk/blob/main/docs/examples.md)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
================================================
FILE: instructions/php-symfony.instructions.md
================================================
---
description: "Symfony development standards aligned with official Symfony Best Practices"
applyTo: "**/*.php, **/*.yaml, **/*.yml, **/*.xml, **/*.twig"
---
# Symfony Development Instructions
Instructions for developing Symfony applications following the official Symfony Best Practices and core framework philosophy.
## Project Context
- Symfony (latest stable or LTS)
- Default Symfony directory structure
- Autowiring and autoconfiguration enabled
- Doctrine ORM when persistence is needed
- Twig for templating
- Symfony Forms, Validator, Security, Messenger as needed
- PHPUnit for testing
- Attribute-based configuration where supported
## Project Structure
- Use the default Symfony directory structure
- Do not create bundles for application code
- Organize application code using PHP namespaces
- Keep configuration in `config/`, application code in `src/`, templates in `templates/`
## Configuration
### Environment Configuration
- Use environment variables for infrastructure-related configuration
- Use `.env` files to define environment-specific values
- Do not use environment variables to control application behavior
### Sensitive Configuration
- Store secrets (API keys, credentials) using Symfony Secrets
- Never commit secrets to the repository
### Application Configuration
- Use parameters in `config/services.yaml` for application behavior configuration
- Override parameters per environment only when needed
- Prefix parameters with `app.` to avoid collisions
- Use short, descriptive parameter names
- Use PHP constants for configuration values that rarely change
## Services & Dependency Injection
- Use dependency injection exclusively
- Prefer constructor injection
- Use autowiring and autoconfiguration by default
- Keep services private whenever possible
- Avoid accessing services via `$container->get()`
- Use YAML as the preferred format for service configuration
- Use interfaces where it improves decoupling or clarity
## Controllers
- Extend `AbstractController`
- Keep controllers thin and focused on glue code
- Do not place business logic in controllers
- Use attributes to configure routing, caching, and security
- Use dependency injection for services
- Use Entity Value Resolvers when convenient and appropriate
- Perform complex queries explicitly via repositories when needed
## Doctrine & Persistence
- Use Doctrine entities as plain PHP objects
- Define Doctrine mapping using PHP attributes
- Use repositories for querying data
- Avoid putting business logic in repositories
- Use migrations for all schema changes
## Templates (Twig)
- Use snake_case for template names, directories, and variables
- Prefix template fragments with an underscore
- Keep templates focused on presentation
- Avoid business logic in Twig templates
- Escape output by default
- Avoid using `|raw` unless content is trusted and sanitized
## Forms
- Define forms as PHP classes
- Do not build forms directly in controllers
- Add form buttons in templates, not in form classes
- Define validation constraints on the underlying object
- Use a single controller action to render and process each form
- Define submit buttons in controllers only when multiple submits are required
## Validation
- Use Symfony Validator constraints
- Validate data at application boundaries
- Prefer object-level validation over form-only validation when reuse is needed
## Internationalization
- Use XLIFF for translation files
- Use translation keys instead of literal content strings
- Use descriptive keys that express purpose, not location
## Security
- Prefer a single firewall unless multiple systems are required
- Use the auto password hasher
- Use voters for complex authorization logic
- Avoid complex security expressions in attributes
## Web Assets
- Use AssetMapper to manage web assets
- Avoid unnecessary frontend build complexity unless required
## Asynchronous Processing
- Use Symfony Messenger for async and background tasks
- Keep message handlers small and focused
- Configure failure transports for failed messages
## Testing
- Write functional tests using `WebTestCase`
- Add smoke tests to ensure all public URLs respond successfully
- Hard-code URLs in functional tests instead of generating routes
- Use unit tests where appropriate for isolated logic
- Add more specific tests incrementally as the application evolves
## General Guidelines
- Prefer clarity over abstraction
- Follow Symfony conventions before introducing custom patterns
- Keep configuration explicit and readable
- Avoid premature optimization
- Use Symfony Demo as a reference implementation
================================================
FILE: instructions/playwright-dotnet.instructions.md
================================================
---
description: 'Playwright .NET test generation instructions'
applyTo: '**'
---
# Playwright .NET Test Generation Instructions
## Test Writing Guidelines
### Code Quality Standards
- **Locators**: Prioritize user-facing, role-based locators (`GetByRole`, `GetByLabel`, `GetByText`, etc.) for resilience and accessibility. Use `await Test.StepAsync()` to group interactions and improve test readability and reporting.
- **Assertions**: Use auto-retrying web-first assertions. These assertions use `Expect()` from Playwright assertions (e.g., `await Expect(locator).ToHaveTextAsync()`). Avoid checking visibility unless specifically testing for visibility changes.
- **Timeouts**: Rely on Playwright's built-in auto-waiting mechanisms. Avoid hard-coded waits or increased default timeouts.
- **Clarity**: Use descriptive test and step titles that clearly state the intent. Add comments only to explain complex logic or non-obvious interactions.
### Test Structure
- **Usings**: Start with `using Microsoft.Playwright;` and either `using Microsoft.Playwright.Xunit;` or `using Microsoft.Playwright.NUnit;` or `using Microsoft.Playwright.MSTest;` for MSTest.
- **Organization**: Create test classes that inherit from `PageTest` (available in NUnit, xUnit, and MSTest packages) or use `IClassFixtureAdd data to get started