PHP MCP服务器——MCP应用MVP
支持以下功能的最小PHP MCP服务器 MCP应用程序 延长（2026-01-26）。它可能会跑过 标准 或 超文本传输协议 并被包装为 Claude桌面扩展 （.mcpb）。同一服务器公开了工具（例如。 hello_ui, GenerateDraft, PublishDraft)可选 嵌入式用户界面 （MCP应用程序），适用于支持它的主机。
需求
- PHP 8.1+
- Composer（用于自动加载和依赖关系）
- 用于打包Claude Desktop扩展：Node.js（用于
npx mcpb pack仅）
______________________________________________________________________
项目概述
这个项目是一个单一的 MCP服务器 （PHP）：
- 暴露 工具 和 资源 （包括
ui://MCP应用程序的资源）。 - 可以通过以下方式使用 标准 （例如克劳德桌面）或 超文本传输协议 （例如。 ext应用程序 基本主机或浏览器点击HTTP MCP端点）。
- 可选择运行 HTTP端点 通过内置的流工作进程或通过 CLI Symphony 服务
public/index.php.
在所有模式下使用相同的MCP逻辑和工具；只有 运输 （stdio与HTTP）以及 流程是如何启动的 （独立脚本vs web服务器）更改。
______________________________________________________________________
MCP应用程序为此项目添加了什么
MCP服务器传统上公开 工具 （和资源）返回文本或结构化数据。这 MCP应用程序 扩展（规格： specification/2026-01-26/apps.mdx 在extapps仓库中）允许服务器连接 交互式用户界面 工具：
- 服务器声明 工具 并将其链接到 UI资源 通过
_meta.ui.resourceUri一ui://URI）。 - 当主机支持MCP Apps时，它可以 运行该工具 和 获取并渲染 将该资源作为iframe（“视图”）。视图通过以下方式与主机通信
postMessage（JSON-RPC），而不是直接与PHP服务器连接。 - 与纯文本工具相比，这给出了 嵌入式用户界面 工具旁边的（表单、预览、控件）会导致对话。
在这个项目中，MCP应用程序被用作 通过UI增强的工具：例如。 hello_ui （演示）和文章相关工具(GenerateDraft, PublishDraft, RequestChanges)每个都有一个可选的UI资源(ui://darkwood/hello, ui://darkwood/article).主机（例如基本主机或克劳德桌面，当它支持MCP应用程序时）显示工具结果和交互式视图（如果可用）。
______________________________________________________________________
MCP应用程序的不同使用模式
同一MCP服务器有几种使用方式：
| 模式 | 运输 | 入口点 | 典型用途 |
|---|---|---|---|
| 工作室 | STDIN/STDOUT（行分隔JSON-RPC） | php server.php | Claude Desktop扩展（.mcpb），本地CLI客户端 |
| HTTP（流工作者） | HTTP POST/mcp | php bin/flow-worker.php | 单流程：MCP端点+可选流量标记；基本主机 |
| HTTP（Symfony服务器） | HTTP POST/mcp | symfony serve （文档根： public/) | Symfony CLI服务的MCP端点；此流程中没有Flow worker |
| Claude桌面扩展 | Stdio（引擎盖下） | 包装为.mcpb，运行 php server.php | 在Claude/Claude桌面中使用MCP应用程序 |
| MCP应用程序作为UI工具 | 以上任何一项 | 取决于主机 | 基本主机或任何支持MCP Apps的主机；工具调用+iframe中呈现的UI资源 |
1. 舞台
- 命令：
php server.php - 行为： 在STDIN上监听以行分隔的JSON-RPC请求；每行向STDOUT写入一个JSON-RPC响应。没有HTTP。与项目其余部分相同的MCP+Flow接线；只有传输是stdio。
- 使用案例： Claude Desktop扩展（.mcpb运行
php server.php)，或任何通过stdio与MCP通信的客户端。
2.HTTP（流工作者）
- 命令：
php bin/flow-worker.php - 行为： 启动HTTP服务器（默认值：
http://127.0.0.1:3000)并暴露 POST/mcp 对于JSON-RPC。与stdio相同的MCP处理程序；传输是HTTP。该过程还运行一个React事件循环（例如，用于周期性滴答）。端口可以用以下命令覆盖MCP_PORT. - 使用案例： 运行MCP端点 基本主机 或其他没有单独web服务器的HTTP MCP客户端。
3.Symfony服务器
- 命令：
symfony serve（文档根指向public/例如。public或public/). - 行为： 通过Symfony CLI提供应用程序； POST/mcp 由以下人员处理
public/index.phpMCP逻辑与flow worker和server.php相同；此进程中没有Flow工作循环。每个请求都是一个单独的PHP运行（经典的请求/响应）。 - 使用案例： 本地开发或部署，您希望在其前面有一个标准的web服务器
public/index.php而不是嵌入式流工作者。
替代方案（无Symfony CLI）： php -S localhost:3000 public/index.php --PHP内置服务器，相同的MCP端点。
4.克劳德桌面扩展
- 怎样： 将项目打包为.mcpb（参见 克劳德桌面扩展（.mcpb） 在......下面清单通过以下方式运行服务器 标准 (
php server.php). - 行为： Claude Desktop将服务器作为子进程启动，并通过STDIN/STDOUT进行通信。用户可以看到扩展的工具（例如。
hello_ui)以及，当客户端支持MCP Apps时，嵌入式UI。 - 使用案例： 直接在Claude/Claude Desktop中使用此MCP应用程序，而无需运行单独的HTTP服务器。
5.MCP App作为嵌入式UI工具
- 怎样： 使用上述任何一种（stdio或HTTP） MCP应用程序——功能强大的主机 （例如ext-apps基本主机，或支持MCP apps的Claude）。主机调用该工具，并使用
_meta.ui.resourceUri，获取UI资源并在iframe中呈现。 - 行为： 工具结果（文本/内容）加交互式视图；视图可以通过主机的MCP客户端（例如。
tools/call由主机转发）。
______________________________________________________________________
传输和编排差异
- Stdio和HTTP（流工作者）： 一个长期存在的过程。可以使用异步功能（例如React事件循环）；流工作者在与MCP HTTP处理程序相同的进程中运行一个滴答循环。对于stdio，同一进程处理STDIN读取和任何周期性工作。
- Symfony服务器（或
php -S随着public/index.php): 每个HTTP请求都是一个新的PHP进程（或请求）。模型是 同步 根据请求；没有进程内的Flow worker。多步骤工作流（如文章流）的编排旨在由以下人员处理 流动 在flow worker下运行时，或者在使用Symfony服务器时通过外部调度运行时。 - 克劳德桌面（stdio）： 每个会话一个子进程；没有HTTP。所有MCP流量都在STDIN/STDOUT上。
摘要： 使用 流动工人 当您想要一个流程用于MCP+可选的Flow勾选时；使用 Symfony服务器 （或PHP内置），当您需要一个标准的HTTP堆栈并且可能依赖于外部编排或单独的工作器时。
______________________________________________________________________
高层体系结构
- MCP主机 （例如基本主机，Claude Desktop）：连接到MCP服务器（stdio或HTTP），列出工具/资源，调用工具，并为MCP应用程序获取UI资源并在iframe中呈现。
- MCP应用程序UI（视图）： HTML/JS加载自
resources/read为了ui://URI；在主机的iframe中运行；通过以下方式与主持人交谈postMessage（JSON-RPC），而不是直接发送到PHP服务器。 - PHP MCP服务器： 这个项目。手柄
initialize,tools/list,tools/call,resources/list,resources/read；提供工具实现和UI资源内容。 - 流量： 用于多步骤工作流的可选编排层（在流工作器下运行时使用）。
详细的序列图和协议流程见 docs/php-mcp-apps-mvp-architecture.md.
______________________________________________________________________
有用的运行命令
# Install PHP dependencies
composer install
# --- Stdio (e.g. for manual testing or .mcpb) ---
php server.php
# --- HTTP: single process with MCP endpoint ---
php bin/flow-worker.php
# MCP endpoint: http://127.0.0.1:3000/mcp (or set MCP_PORT)
# --- HTTP: Symfony server (document root = public/) ---
symfony serve
# Then POST /mcp to the URL Symfony prints (e.g. http://127.0.0.1:8000/mcp)
# --- HTTP: PHP built-in server ---
php -S localhost:3000 public/index.php
# MCP endpoint: http://localhost:3000/mcp
# --- Claude Desktop extension: pack .mcpb ---
composer install --no-dev
npm run mcpb:pack
# Install the generated .mcpb in Claude Desktop (Settings → Extensions → Install Extension)使用基本主机（ext应用程序）： 启动MCP服务器（例如。 php bin/flow-worker.php)，然后从ext应用程序： SERVERS='["http://127.0.0.1:3000/mcp"]' npx tsx serve.ts 在 examples/basic-host，并打开http://localhost:8080.
______________________________________________________________________
克劳德桌面扩展（.mcpb）
将服务器打包为MCPB捆绑包，并将其安装在Claude Desktop中以获取工具（例如。 你好)当客户端支持时，使用MCP App UI。
1.安装MCPB（开发）并打包
cd /path/to/darkwood-publish-article-mcp-apps
npm install
composer install --no-dev
npm run mcpb:pack这产生了一个 .mcpb 文件（例如。 darkwood-php-mcp-apps-1.0.0.mcpb).回购包含一个有效的 manifest.json （服务器类型：二进制，条目： server.php，命令： php server.php).
2.在Claude Desktop中安装
- 打开 克劳德桌面版 （macOS或Windows）。
- 首选 设置→ 扩展→ 高级→ 安装扩展.
- 选择
.mcpb文件（或拖放）。 - 确认；扩展名将出现在您的列表中。
3.使用MCP应用程序
- 开始对话；启用 PHP MCP应用程序（Hello UI） 扩展。
- 让克劳德打电话 你好 （或其他工具）。您将获得工具结果，如果客户端支持MCP Apps，还将获得嵌入式UI。
注： .mcpb通过以下方式运行服务器 标准 (php server.php).PHP必须在你的 PATH Claude Desktop运行的地方。
______________________________________________________________________
实现JSON-RPC方法
| 方法 | 说明 |
|---|---|
initialize | 退货 protocolVersion, capabilities （工具、资源， io.modelcontextprotocol/ui), serverInfo. |
tools/list | 返回工具： hello_ui, GenerateDraft, PublishDraft, RequestChanges （与 _meta.ui.resourceUri 对于应用程序UI）。 |
tools/call | 退货 content （数组 { type, text })；支持hello_ui、GenerateDraft、PublishDraft、RequestChanges。 |
resources/list | 返回资源： ui://darkwood/hello, ui://darkwood/article. |
resources/read | 退货 contents 随着 text/html;profile=mcp-app 对于所请求的URI（hello或文章应用HTML）。 |
______________________________________________________________________
项目布局
darkwood-publish-article-mcp-apps/
├── manifest.json # MCPB manifest (server.type=binary, php server.php)
├── server.php # Stdio MCP server (for .mcpb and stdio clients)
├── package.json # npm scripts: mcpb:init, mcpb:pack
├── composer.json
├── README.md
├── docs/
│ └── php-mcp-apps-mvp-architecture.md
├── bin/
│ └── flow-worker.php # HTTP MCP server + optional Flow tick (single process)
├── public/
│ └── index.php # HTTP front controller: POST /mcp (Symfony serve or php -S)
├── var/ # Flow SQLite (flow.sqlite), lock (flow.lock)
└── src/
├── Mcp/
│ ├── McpServer.php
│ ├── JsonRpcHandler.php
│ └── StdioTransport.php
├── Flow/
│ ├── FlowEngine.php
│ ├── RunRepository.php
│ └── Lock.php
└── ...______________________________________________________________________
当前的限制和注意事项
- 音乐节目 ： 每行只有一个JSON-RPC请求；如果一行是批处理数组，则只处理第一个元素。 从不 将JSON-RPC响应行以外的任何内容写入STDOUT；对日志使用STDERR。
- 通知： 通知（例如。
ui/notifications/initialized)没有id--不要为他们发送回复。 - HTTP（此服务器）： POST/mcp返回一个 单 JSON-RPC响应体（无流式HTTP/SSE）。基本主机仍可连接；对于完整的流式HTTP，您需要不同的传输方式。
- Symfony服务器： 同一流程中没有Flow工人；编排是每个请求同步的，或者必须在其他地方处理。
- 克劳德桌面： MCP App UI渲染依赖于Claude对MCP Apps扩展的支持；工具结果总是有效的。
- 今天实施： Stdio和HTTP传输；工具和UI资源；.mcpb包装；基本主机兼容性；流工作者中的流集成。 可能的未来： 全批JSON-RPC、可流式HTTP传输、更深入的编辑工作流程文档。
______________________________________________________________________
规范参考
- MCP应用程序：
specification/2026-01-26/apps.mdx在 ext应用程序 回购。 - 快速入门（概念：工具+UI资源，在iframe中查看）： MCP应用程序快速入门.