davidsmith3/mcp-server repository overview

curl -fsSL https://raw.githubusercontent.com/zero-to-prod/mcp-server/main/install.sh | bash

docker run --rm -v $(pwd):/init davidsmith3/mcp-server:latest init

cp .env.example .env

docker compose up -d

claude mcp add --transport http mcp1 http://localhost:8093

docker compose down && docker compose up -d

your-project/
├── .env
├── docker-compose.yml
└── src/
    ├── MyController.php    <- Create controllers here
    ├── Redis.php           <- Built-in controller (copied by installer)
    └── Mongodb.php         <- Built-in controller (copied by installer)

<?php
declare(strict_types=1);

// Namespaces are optional

// Include ALL imports needed by THIS file
use Mcp\Capability\Attribute\McpTool;
use Mcp\Capability\Attribute\Schema;
use Mcp\Exception\ToolCallException;
use Mcp\Schema\ToolAnnotations;

class PluginController {
// All methods and dependencies in one file
}

✓ service.user.get
✓ service.users.list
✓ service.order.create
✓ service.item.search_by_id
✓ api.logs.aggregate

✗ getUser              (missing service.noun)
✗ service_user_get     (underscores not dots)
✗ Service.User.Get     (not lowercase)
✗ service.users.get    (plural noun for singular action)

REDIS_HOST=redis          # Container name or IP
REDIS_PORT=6379
REDIS_PASSWORD=           # Optional

services:
mcp:
depends_on: [ redis ]
redis:
image: redis:7-alpine
command: redis-server --appendonly yes

redis.inspect("mykey")  // Returns: {key, metadata: {type, size, count}, preview: [...], ttl}

redis.get("mykey")  // Returns: complete dataset

redis.exists("mykey")  // Returns: {key, exists: bool, ttl: int|null}

redis.command("KEYS ref:*")     // Find keys by pattern
redis.command("SCAN 0 MATCH ref:* COUNT 100")  // Production-safe scanning
redis.command("TTL mykey")      // Get time to live

MONGODB_HOST=mongodb      # Container name or IP
MONGODB_PORT=27017
MONGODB_USERNAME=         # Optional
MONGODB_PASSWORD=         # Optional

services:
mcp:
depends_on: [ redis, mongodb ]
mongodb:
image: mongo:8
volumes:
  - mongodb-data:/data/db

mongodb.document.find(
"mydb",
"users",
"{\"status\": \"active\", \"_limit\": 10}"
)

// Insert one
mongodb.document.insert("mydb", "users", "{\"name\": \"John\", \"email\": \"[email protected]\"}")

// Insert many
mongodb.document.insert("mydb", "users", "[{\"name\": \"John\"}, {\"name\": \"Jane\"}]")

mongodb.document.update(
"mydb",
"users",
"{\"_id\": \"...\"}",
"{\"$set\": {\"status\": \"active\"}}"
)

// Delete one
mongodb.document.delete("mydb", "users", "{\"_id\": \"...\"}")

// Delete many
mongodb.document.delete("mydb", "users", "{\"status\": \"archived\", \"_multiple\": true}")

mongodb.data.aggregate(
"mydb",
"orders",
"[
{\"$match\": {\"status\": \"completed\"}},
{\"$group\": {\"_id\": \"$userId\", \"total\": {\"$sum\": \"$amount\"}}},
{\"$sort\": {\"total\": -1}},
{\"$limit\": 10}
]"
)

MONGODB_USERNAME=admin
MONGODB_PASSWORD=secure_password

docker compose restart

docker ps                                 # Running containers
docker compose ps                         # Compose services

docker logs mcp-server --tail 200         # Last 200 lines
docker logs -f mcp-server                 # Follow (real-time)
docker logs mcp-server --since 1h         # Last hour
docker compose logs mcp                   # Compose service

docker logs mcp-server 2>&1 | grep -i error
docker logs mcp-server 2>&1 | grep "tool_name"

docker exec mcp-server env | grep MCP     # MCP config
docker exec mcp-server env | grep REDIS   # Redis config

docker logs mcp1

# Path inside Docker container (your src/ directory is mounted to /app/src)
docker exec mcp1 php -l /app/src/YourController.php

docker exec mcp1 env | grep MCP

<?php
declare(strict_types=1);
// Namespaces are optional

class ControllerName {
// methods with attributes
}

#[McpTool(
name: 'tool_name',
description: 'Concise tool description (1-2 sentences). Key behavior if needed.',
annotations: new ToolAnnotations(
    title: 'tool_name'  // MUST match name exactly
)
)]
public function method(
#[Schema(
    type: 'TYPE',
    description: 'Purpose. Valid values/format. Example: "value"',
    pattern: '/regex/',      // optional validation
    enum: ['val1', 'val2']   // optional enum constraint
)]
TYPE $param
): RETURN_TYPE {
if (/* error */) {throw new ToolCallException('error: details');}
return $result;
}

#[McpTool(
name: 'tool.name',
description: 'Description...',
annotations: new ToolAnnotations(title: 'tool.name')  // <- HERE
)]
public function method(
#[Schema(type: 'string', description: 'Description...')]  // <- NO annotations
string $param
)

#[Schema(
type: 'string',
description: 'Description...',
annotations: new ToolAnnotations(...)  // <- NEVER DO THIS
)]

#[McpTool(
name: 'divide',
description: 'Divides two numbers. Returns float result. Throws exception if divisor is zero.',
annotations: new ToolAnnotations(
    title: 'divide'
)
)]
public function divide(
#[Schema(
    type: 'number',
    description: 'Dividend (number to be divided). Example: 10.5, -20, 100'
)]
float $a,
#[Schema(
    type: 'number',
    description: 'Divisor (cannot be zero). Example: 2.5, -4, 0.1'
)]
float $b
): float {
if ($b === 0.0) {throw new ToolCallException('cannot divide by zero');}
return $a / $b;
}

#[McpResource(
uri: 'scheme://path',                    // required, RFC 3986
name: 'Name',                            // optional
description: 'Concise resource description (what data it provides).',
mimeType: 'application/json',            // optional
size: 1024                               // optional, bytes
)]
public function method(): mixed {
if (/* error */) {throw new ResourceReadException('error: details');}
return $data;
}

#[McpResource(
uri: 'config://app/settings',
name: 'Application Settings',
description: 'Returns application configuration as JSON (runtime settings, feature flags, environment values).',
mimeType: 'application/json'
)]
public function getSettings(): array {
$file = '/path/to/settings.json';
if (!file_exists($file)) {throw new ResourceReadException("not found: {$file}");}
return json_decode(file_get_contents($file), true);
}

#[McpResourceTemplate(
uriTemplate: 'scheme://path/{var}',      // required, RFC 6570
name: 'Name',                            // optional
description: 'Concise resource template description (what data it provides by variable).',
mimeType: 'application/json'             // optional
)]
public function method(
#[Schema(
    type: 'string',
    description: 'Variable description (format, constraints). Example: "value"',
    pattern: '/^[a-z0-9]+$/'             // optional validation
)]
string $var
): mixed {
if (/* error */) {throw new ResourceReadException('error: details');}
return $data;
}

#[McpResourceTemplate(
uriTemplate: 'data://user/{userId}',
name: 'User Data',
description: 'Returns user data by ID from data store. Throws exception if not found.',
mimeType: 'application/json'
)]
public function getUser(
#[Schema(
    type: 'string',
    description: 'User ID (alphanumeric lowercase). Example: "user123", "abc456"',
    pattern: '/^[a-z0-9]+$/'
)]
string $userId
): array {
if (!ctype_alnum($userId)) {throw new ResourceReadException('userId must be alphanumeric');}
if (!$user = $this->find($userId)) {throw new ResourceReadException("not found: {$userId}");}
return $user;
}

#[McpPrompt(
name: 'name',                          // required
description: 'Concise prompt description (what it generates and purpose).'
)]
public function method(
#[Schema(
    type: 'TYPE',
    description: 'Parameter description. Valid values. Example: "value"',
    enum: ['opt1', 'opt2']             // optional
)]
TYPE $param
): array {
if (/* error */) {throw new PromptGetException('error: details');}
return [['role' => 'user', 'content' => ['type' => 'text', 'text' => 'prompt']]];
}

#[McpPrompt(
name: 'review',
description: 'Generates code review prompt with configurable style and rigor level.'
)]
public function review(
#[Schema(
    type: 'string',
    description: 'Review style. Valid: strict, balanced (default), lenient. Example: "balanced"',
    enum: ['strict', 'balanced', 'lenient']
)]
string $style = 'balanced'
): array {
$valid = ['strict', 'balanced', 'lenient'];
if (!in_array($style, $valid, true)) {throw new PromptGetException("invalid '{$style}': " . implode('|', $valid));}
return [['role' => 'user', 'content' => ['type' => 'text', 'text' => "Review with {$style} style"]]];
}

#[Schema(
type: 'TYPE',                // required: string|number|integer|boolean|array|object|null
description: 'Concise parameter description. Valid values/format. Example: "value"',
definition: [...],           // optional: complete JSON schema (highest priority)

// string constraints
minLength: 1,
maxLength: 100,
pattern: '/regex/',
format: 'email',             // email|uri|date-time

// number constraints
minimum: 0,
maximum: 100,
exclusiveMinimum: 0,
exclusiveMaximum: 100,

// array constraints
minItems: 1,
maxItems: 10,
uniqueItems: true,

// object constraints
properties: [...],           // property schemas
required: ['field1'],
patternProperties: [...],    // regex-based properties

// enum constraint (any type)
enum: ['opt1', 'opt2']
)]

#[Schema(
type: 'string',
format: 'email',
description: 'User email address. Example: "[email protected]"'
)]
string $email

#[Schema(
type: 'integer',
minimum: 1,
maximum: 100,
description: 'Page number. Range: 1-100, Default: 1'
)]
int $page

#[Schema(
type: 'string',
enum: ['asc', 'desc'],
description: 'Sort order. Valid: asc (ascending), desc (descending)'
)]
string $order

#[Schema(
type: 'array',
minItems: 1,
maxItems: 10,
description: 'Array of tags. Range: 1-10 items. Example: ["tag1", "tag2", "tag3"]'
)]
array $tags

#[Schema(
type: 'string',
minLength: 5,
maxLength: 50,
description: 'Username (5-50 chars, alphanumeric and underscore). Example: "john_doe", "user123"'
)]
string $username

// 1. Value lists (static strings)
#[CompletionProvider(['opt1', 'opt2', 'opt3'])]
string $param

// 2. Enum classes (backed or unit enums)
#[CompletionProvider(MyEnum::class)]
string $param

// 3. Custom classes (implementing ProviderInterface)
#[CompletionProvider(CustomProvider::class)]
string $param

#[McpTool(
name: 'search',
description: 'Searches items with configurable sorting. Returns ordered results.',
annotations: new ToolAnnotations(
    title: 'search'
)
)]
public function search(
#[Schema(
    type: 'string',
    description: 'Sort order. Valid: asc, desc, relevance (default). Example: "relevance"'
)]
#[CompletionProvider(['asc', 'desc', 'relevance'])]
string $sort = 'relevance'
): array {
return ['results' => []];
}

use Mcp\Exception\ToolCallException;       // tools
use Mcp\Exception\ResourceReadException;   // resources
use Mcp\Exception\PromptGetException;      // prompts

// empty
if (empty($val)) {throw new ToolCallException('param empty');}

// length
if (strlen($val) > 100) {throw new ToolCallException('param too long: max 100');}

// format
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {throw new ToolCallException("invalid email: {$email}");}

// enum
$valid = ['a', 'b', 'c'];
if (!in_array($val, $valid, true)) {throw new ToolCallException("invalid '{$val}': " . implode('|', $valid));}

// exists
if (!file_exists($path)) {throw new ToolCallException("not found: {$path}");}

// pattern
if (!preg_match('/pattern/', $val)) {throw new ToolCallException('invalid format: must match pattern');}

try {
$db->connect();
} catch (\PDOException $e) {
error_log("Internal: " . $e->getMessage());
throw new \RuntimeException('db failed');  // no details to client
}

Server::builder()
->addTool(callable: $callable, name: 'tool_name', description: 'desc')
->addResource(callable: $callable, uri: 'scheme://path', name: 'name', description: 'desc')
->addResourceTemplate(callable: $callable, uriTemplate: 'scheme://{var}', name: 'name', description: 'desc')
->addPrompt(callable: $callable, name: 'prompt_name', description: 'desc')
->build();

Server::builder()
->setServerInfo(name: 'Name', version: '1.0', description: 'desc', icons: [...], website: 'url')
->setPaginationLimit(50)                                    // max items per page (default: 50)
->setInstructions('AI guidance text')                       // usage instructions for AI models
->setDiscovery(basePath: __DIR__, scanDirs: ['src'], excludeDirs: ['vendor'], cache: $psr16)
->setSession(store: $sessionStore, ttl: 3600)              // or just ttl for InMemorySessionStore
->setLogger($psr3Logger)                                    // PSR-3 logger
->setContainer($psr11Container)                             // PSR-11 DI container
->setEventDispatcher($psr14Dispatcher)                      // PSR-14 event dispatcher
->addRequestHandler('method_name', callable)                // custom JSON-RPC handler
->addNotificationHandler('notification_name', callable)     // custom notification handler
->build()
->run($transport);

// 1. InMemorySessionStore (default, volatile)
new InMemorySessionStore(ttl: 3600, prefix: 'session_')

// 2. FileSessionStore (persistent)
new FileSessionStore(path: '/path/to/sessions')

// 3. Psr16StoreSession (Redis, Memcached, etc.)
new Psr16StoreSession(cache: $psr16Cache, ttl: 3600, prefix: 'mcp_')

// Custom: implement SessionStoreInterface
interface SessionStoreInterface {
public function exists(string $id): bool;
public function read(string $id): ?array;
public function write(string $id, array $data): void;
public function destroy(string $id): void;
public function gc(int $maxlifetime): void;
}