基于 awesome-copilot 的 php-mcp-development 插件用官方 PHP SDK 打造属性驱动的 MCP 服务器【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilotphp-mcp-development 是 awesome-copilot 社区仓库中专门面向 PHP 开发者的一套 GitHub Copilot 扩展插件它把「PHP MCP 服务器开发」沉淀为一条 Slash 命令、一位专家 Agent 与一份最佳实践指令。本文以该插件的 README 为骨架结合其引用的 Agent 定义、项目生成技能 与 开发指令 源码完整讲解如何通过#[McpTool]、#[McpResource]、#[McpPrompt]等属性声明式地构建、测试并部署生产级 PHP MCP 服务器。读完本文你将掌握插件安装方式、项目一键生成流程以及从传输层选择、发现缓存到框架集成与容器化部署的完整实战链路。插件速览一个命令、一位专家、一套规范该插件的定位是「使用官方 PHP SDK基于属性发现构建 Model Context Protocol 服务器的综合资源」涵盖最佳实践、项目生成与专家协助。其元数据定义在 plugin.json 中关键字为php、mcp、model-context-protocol、server-development、sdk、attributes、composer版本 1.0.0MIT 许可。安装方式插件通过 Copilot CLI 安装命令与仓库通用约定一致见 README.plugins.mdcopilot plugin install php-mcp-developmentawesome-copilot安装完成后插件会注册以下能力类型名称说明Slash 命令/php-mcp-development:php-mcp-server-generator使用官方 PHP SDK 生成包含工具、资源、提示词与测试的完整 PHP MCP 服务器项目Agentphp-mcp-expert精通官方 PHP SDK 与属性发现的 PHP MCP 服务器开发专家助手从 plugin.json 的extensions结构可以看出插件通过com.github.awesome-copilot扩展点挂载了./agents/php-mcp-expert.md与./skills/php-mcp-server-generator/二者正是插件的两大能力来源。项目一键生成php-mcp-server-generator技能交互式需求采集调用/php-mcp-development:php-mcp-server-generator后生成技能会先向你确认 6 项关键输入见 SKILL.md项目名称如my-mcp-server服务器描述如 A file management MCP server传输类型stdio、http或两者皆可要包含的工具如 file read、file write、list directory是否包含资源与提示词PHP 版本要求 8.2生成的项目结构技能会按以下标准布局生成完整工程{project-name}/ ├── composer.json ├── .gitignore ├── README.md ├── server.php ├── src/ │ ├── Tools/ │ │ └── {ToolClass}.php │ ├── Resources/ │ │ └── {ResourceClass}.php │ ├── Prompts/ │ │ └── {PromptClass}.php │ └── Providers/ │ └── {CompletionProvider}.php └── tests/ └── ToolsTest.php其中server.php是服务器入口src/下按工具、资源、提示词、补全提供者分目录组织tests/存放 PHPUnit 测试。生成的 composer.json 模板技能生成的composer.json具备生产就绪的配置SKILL.md{ name: your-org/{project-name}, description: {Server description}, type: project, require: { php: ^8.2, mcp/sdk: ^0.1 }, require-dev: { phpunit/phpunit: ^10.0, symfony/cache: ^6.4 }, autoload: { psr-4: { App\\: src/ } }, autoload-dev: { psr-4: { Tests\\: tests/ } }, config: { optimize-autoloader: true, preferred-install: dist, sort-packages: true } }要点说明运行时依赖仅mcp/sdk官方 PHP SDK^0.1测试与缓存依赖phpunit/phpunit、symfony/cache放在require-dev保证生产安装的精简PSR-4 同时覆盖App\与Tests\两个命名空间optimize-autoloader、preferred-install: dist、sort-packages三项配置分别优化自动加载性能、加速依赖下载与保持依赖顺序整洁。生成的 server.php 入口生成器产出的服务器入口结合了属性发现与 PSR-16 发现缓存SKILL.md#!/usr/bin/env php ?php declare(strict_types1); require_once __DIR__ . /vendor/autoload.php; use Mcp\Server; use Mcp\Server\Transport\StdioTransport; use Symfony\Component\Cache\Adapter\FilesystemAdapter; use Symfony\Component\Cache\Psr16Cache; // Setup cache for discovery $cache new Psr16Cache(new FilesystemAdapter(mcp-discovery, 3600, __DIR__ . /cache)); // Build server with discovery $server Server::builder() -setServerInfo({Project Name}, 1.0.0) -setDiscovery( basePath: __DIR__, scanDirs: [src], excludeDirs: [vendor, tests, cache], cache: $cache ) -build(); // Run with stdio transport $transport new StdioTransport(); $server-run($transport);入口脚本以#!/usr/bin/env phpshebang 开头可直接执行setDiscovery限定扫描src/并排除vendor、tests、cacheFilesystemAdapter(mcp-discovery, 3600, ...)为发现结果设置 3600 秒1 小时的缓存生命周期避免每次启动都重复扫描类文件。从零实现核心能力属性驱动的三类要素Agent 定义php-mcp-expert.agent.md将专家能力聚焦在四个属性上#[McpTool]、#[McpResource]、#[McpPrompt]与#[Schema]。下面逐一展开。工具Tools#[McpTool]工具是 MCP 服务器最常用的能力。最简单的方式是直接在方法上标注#[McpTool]SDK 会自动根据方法签名生成工具定义?php declare(strict_types1); namespace App\Tools; use Mcp\Capability\Attribute\McpTool; use Mcp\Capability\Attribute\Schema; class FileManager { /** * Reads file content from the filesystem. * * param string $path Path to the file * return string File contents */ #[McpTool(name: read_file)] public function readFile(string $path): string { if (!file_exists($path)) { throw new \InvalidArgumentException(File not found: {$path}); } if (!is_readable($path)) { throw new \RuntimeException(File not readable: {$path}); } return file_get_contents($path); } /** * Validates and processes user email. */ #[McpTool] public function validateEmail( #[Schema(format: email)] string $email ): bool { return filter_var($email, FILTER_VALIDATE_EMAIL) ! false; } }要点name参数可为工具指定对外名称如read_file不指定时默认使用方法名工具方法中的异常会被 SDK 自动转换为 JSON-RPC 错误响应客户端可直接识别#[Schema]属性声明参数约束如format: emailSDK 会据此生成 JSON Schema 校验。资源Resources#[McpResource]与#[McpResourceTemplate]资源分两类静态资源用固定 URI模板资源支持 URI 中的变量占位符。静态资源示例来自 php-mcp-expert.agent.md#[McpResource( uri: config://app/settings, name: app_config, mimeType: application/json )] public function getSettings(): array { return [ version 1.0.0, debug false ]; }模板资源示例use Mcp\Capability\Attribute\{McpResource, McpResourceTemplate}; #[McpResourceTemplate( uriTemplate: user://{userId}/profile/{section}, name: user_profile, mimeType: application/json )] public function getUserProfile(string $userId, string $section): array { // Variables must match URI template order return $this-users[$userId][$section] ?? throw new \RuntimeException(Profile not found); }注意注释中的关键约束方法参数顺序必须与 URI 模板中变量的出现顺序一致{userId}→$userId{section}→$section。资源还可以返回 SDK 提供的TextResourceContents/BlobResourceContents承载文件内容见 instructions/php-mcp-server.instructions.mduse Mcp\Schema\Content\{TextResourceContents, BlobResourceContents}; #[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) ); }提示词Prompts#[McpPrompt]与#[CompletionProvider]提示词生成器返回按role/content组织的消息数组供客户端直接组装多轮对话。结合#[CompletionProvider]可为参数提供候选值列表在客户端触发自动补全use Mcp\Capability\Attribute\{McpPrompt, CompletionProvider}; class CodePrompts { #[McpPrompt(name: code_review)] public function reviewCode( #[CompletionProvider(values: [php, javascript, python])] string $language, string $code, #[CompletionProvider(values: [security, performance, style])] string $focus general ): array { return [ [role assistant, content You are an expert code reviewer.], [role user, content Review this {$language} code focusing on {$focus}:\n\n{$language}\n{$code}\n] ]; } }#[CompletionProvider]支持三种来源instructions/php-mcp-server.instructions.md值列表values: [bug, feature, improvement]适合固定枚举PHP 枚举enum: Priority::classSDK 自动取枚举成员作为候选值要求string型枚举或纯枚举自定义提供者实现Mcp\Capability\Prompt\Completion\ProviderInterface的getCompletions(string $currentValue): array方法支持从数据库等动态数据源实时查询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); }参数校验#[Schema]的完整能力#[Schema]是让工具/提示词参数获得类型安全与自动校验的关键完整示例见 php-mcp-expert.agent.md 的 Schema Validation 一节use Mcp\Capability\Attribute\Schema; #[McpTool] public function createUser( #[Schema(format: email)] string $email, #[Schema(minimum: 18, maximum: 120)] int $age, #[Schema( pattern: ^[A-Z][a-z]$, description: Capitalized first name )] string $firstName, #[Schema(minLength: 8, maxLength: 100)] string $password ): array { return [ id uniqid(), email $email, age $age, name $firstName ]; }常用约束维度总结约束适用类型说明formatstring语义格式如emailminimum/maximumint/float数值下界与上界patternstring正则表达式匹配minLength/maxLengthstring字符串长度范围description任意为模型生成 schema 补充语义说明传输层Stdio 与 StreamableHTTPStdio 传输默认适合命令行集成与桌面客户端本地调用是最简单直接的形态use Mcp\Server\Transport\StdioTransport; $transport new StdioTransport(); $server-run($transport);StreamableHTTP 传输适合 Web 场景。SDK 基于 PSR-7配合Nyholm\Psr7的工厂从全局变量构造请求并将响应回传给框架php-mcp-expert.agent.mduse 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 PSR-7 response http_response_code($response-getStatusCode()); foreach ($response-getHeaders() as $name $values) { foreach ($values as $value) { header({$name}: {$value}, false); } } echo $response-getBody();构造器同时接收请求、响应工厂与流工厂便于与任意 PSR-7 实现对接。会话管理HTTP 传输场景下需要管理会话。SDK 提供多种会话存储策略instructions/php-mcp-server.instructions.md内存会话默认-setSession(ttl: 7200)TTL 以秒为单位2 小时后过期文件会话-setSession(new FileSessionStore(__DIR__ . /sessions))适合多进程/重启场景自定义会话存储-setSession(new InMemorySessionStore(3600))可精确控制过期时间。手动注册能力若不希望依赖自动发现也可以显式注册工具与资源instructions/php-mcp-server.instructions.mduse 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();addTool接收「类方法回调 工具名」addResource接收「回调 URI」。手动注册适合工具数量少、希望完全掌控注册清单的场景。测试策略PHPUnit 双管齐下工具层测试生成器自带完整的tests/ToolsTest.php模板覆盖正常路径与异常路径SKILL.md?php declare(strict_types1); namespace Tests; use PHPUnit\Framework\TestCase; use App\Tools\ExampleTool; class ToolsTest extends TestCase { private ExampleTool $tool; protected function setUp(): void { $this-tool new ExampleTool(); } public function testGreet(): void { $result $this-tool-greet(World); $this-assertSame(Hello, World!, $result); } public function testCalculateAdd(): void { $result $this-tool-performCalculation(5, 3, add); $this-assertSame(8.0, $result); } public function testCalculateDivideByZero(): void { $this-expectException(\InvalidArgumentException::class); $this-expectExceptionMessage(Division by zero); $this-tool-performCalculation(10, 0, divide); } public function testCalculateInvalidOperation(): void { $this-expectException(\InvalidArgumentException::class); $this-expectExceptionMessage(Invalid operation); $this-tool-performCalculation(5, 3, modulo); } }配套的phpunit.xml.dist通过bootstrapvendor/autoload.php加载依赖testsuite指向tests目录并用coverage块将src纳入覆盖率统计。服务器发现层测试除了直接测试工具类还可以验证属性发现是否生效instructions/php-mcp-server.instructions.mdpublic 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]); }通过getCapabilities()断言tools键存在且非空可在 CI 中拦截「属性写错、扫描目录配错」这类回归。框架集成Laravel 与 SymfonyLaravelArtisan 命令包装在 Laravel 中推荐将服务器启动逻辑封装为 Artisan 命令php-mcp-expert.agent.md// app/Console/Commands/McpServerCommand.php namespace App\Console\Commands; use Illuminate\Console\Command; use Mcp\Server; use Mcp\Server\Transport\StdioTransport; class McpServerCommand extends Command { protected $signature mcp:serve; protected $description Start MCP server; public function handle(): int { $server Server::builder() -setServerInfo(Laravel MCP Server, 1.0.0) -setDiscovery(app_path(), [Tools, Resources]) -build(); $transport new StdioTransport(); $server-run($transport); return 0; } }setDiscovery(app_path(), [Tools, Resources])直接扫描 Laravel 应用目录下的Tools与Resources子目录与框架的目录约定自然契合。Symfony官方 BundleSymfony 场景推荐直接使用官方symfony/mcp-bundle并以 YAML 配置服务器信息instructions/php-mcp-server.instructions.mdcomposer require symfony/mcp-bundle# config/packages/mcp.yaml mcp: server: name: Symfony MCP Server version: 1.0.0性能优化三件套1. 开启 OPcache生产环境建议在php.ini中启用 OPcache加速 PHP 字节码执行opcache.enable1 opcache.memory_consumption256 opcache.interned_strings_buffer16 opcache.max_accelerated_files10000 opcache.validate_timestamps0 ; Production onlyvalidate_timestamps0关闭文件变更检测仅限生产环境使用开发时若开启会导致修改不生效。2. 使用发现缓存生产必配属性发现涉及文件扫描与反射解析是启动期的主要开销。生产环境务必接入 PSR-16 缓存文件系统或 Redis 均可php-mcp-expert.agent.mduse 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() -setDiscovery(__DIR__, [src], cache: $cache) -build();同时应缩小扫描范围scanDirs只写必要目录如[src/Tools, src/Resources]excludeDirs排除vendor、tests、var、cache从源头减少扫描成本。3. 优化 Composer 自动加载composer dump-autoload --optimize --classmap-authoritative--classmap-authoritative生成完整类映射跳过运行时文件存在性检查换取最快的加载速度。部署实战Docker、Systemd 与客户端接入Docker 镜像官方推荐的容器方案基于php:8.2-cliphp-mcp-expert.agent.mdFROM php:8.2-cli RUN docker-php-ext-install pdo pdo_mysql opcache COPY --fromcomposer:latest /usr/bin/composer /usr/bin/composer WORKDIR /app COPY . /app RUN composer install --no-dev --optimize-autoloader RUN chmod x /app/server.php CMD [php, /app/server.php]--no-dev剔除测试与缓存依赖、--optimize-autoloader优化类加载共同保证镜像体积与启动速度。Systemd 常驻服务面向常驻进程可配置 Systemd 服务自动拉起与崩溃重启php-mcp-expert.agent.md[Unit] DescriptionPHP MCP Server Afternetwork.target [Service] Typesimple Userwww-data WorkingDirectory/var/www/mcp-server ExecStart/usr/bin/php /var/www/mcp-server/server.php Restartalways RestartSec3 [Install] WantedBymulti-user.target客户端接入Claude Desktop 与 MCP Inspector桌面客户端如 Claude Desktop通过 JSON 配置注册服务器注意args中必须使用绝对路径{ mcpServers: { php-server: { command: php, args: [/absolute/path/to/server.php] } } }开发调试阶段推荐用官方 MCP Inspector 交互式验证instructions/php-mcp-server.instructions.mdnpx modelcontextprotocol/inspector php /path/to/server.php插件沉淀的九条最佳实践综合 Agent 与生成技能的实现指南php-mcp-expert.agent.md、SKILL.md插件沉淀出的最佳实践可归纳为始终使用严格类型所有文件头部声明declare(strict_types1);使用类型化属性类属性利用 PHP 7.4 类型属性声明善用枚举PHP 8.1 枚举用于常量与补全候选值生产环境必配发现缓存始终使用 PSR-16 缓存参数全类型化所有方法参数使用类型提示PHPDoc 文档化为每个方法补充 docblock既能辅助发现又能生成更优的 schema 描述全面测试为所有工具编写 PHPUnit 测试规范异常处理使用语义明确的异常类型如InvalidArgumentException/RuntimeException并附带清晰消息遵循 PSR-12按 PHP-FIG 编码标准组织代码。小结php-mcp-development 插件将 PHP 生态中「用官方 SDK 构建 MCP 服务器」的最佳路径完整沉淀了下来通过/php-mcp-development:php-mcp-server-generator一键生成含工具、资源、提示词与测试的完整工程借助php-mcp-expertAgent 获得属性发现、传输层、Schema 校验、框架集成与性能调优的专家指导。无论是本地开发Stdio Inspector 调试还是生产部署发现缓存 OPcache Docker/Systemd这套基于属性声明的开发范式都能显著降低 MCP 服务器的开发与维护成本。相关一手资料可继续在仓库内查阅插件说明、插件元数据、专家 Agent 定义、项目生成技能 与 PHP MCP 开发指令。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考