项目简介

本项目是一个基于 Hyperf PHP 框架的 MCP (Model Context Protocol) 服务器演示应用。它展示了如何利用 Hyperf 框架的 MCP 组件来快速构建和管理微服务工具，并通过简单的注解方式将 PHP 类方法暴露为可供 LLM 客户端调用的工具。

主要功能点

工具注册与发现: 通过注解声明即可将 PHP 方法注册为 MCP 工具，并自动暴露给客户端。
参数描述: 使用注解为工具的参数添加详细描述，方便 LLM 理解工具的功能和使用方法。
基于 Hyperf 框架: 利用 Hyperf 框架的优势，提供高性能和稳定的服务器运行环境。
SSE 支持: 默认配置支持 Server-Sent Events (SSE) 协议，用于与 MCP 客户端进行实时通信。
易于扩展: 基于 Hyperf 框架的模块化设计，方便用户根据自身需求扩展功能。

安装步骤

克隆项目到本地

git clone https://github.com/huangdijia/hyperf-mcp-demo.git
cd hyperf-mcp-demo

安装 Composer 依赖

确保您的环境已安装 Composer，然后在项目根目录下执行：
```
composer install
```
复制并配置环境变量

复制 '.env.example' 文件并重命名为 '.env'，您可以根据需要修改 '.env' 文件中的配置，例如数据库连接等。
```
cp .env.example .env
```
启动 Hyperf 服务器

在项目根目录下，使用 Hyperf 命令行工具启动服务器：
```
php bin/hyperf.php start
```
默认情况下，HTTP 服务运行在 '9501' 端口，MCP-SSE 服务运行在 '3000' 端口。

服务器配置 (Cursor MCP 客户端)

如果您想在 Cursor 编辑器中使用此 MCP 服务器，需要配置 Cursor 的 'claude_desktop_config.json' 文件。

打开 Cursor 配置文件

在您的用户目录下，创建或打开 '/Users/[your-name]/Library/Application Support/Claude/claude_desktop_config.json' 文件。

添加 MCP 服务器配置

在 'mcpServers' 字段下，添加一个新的服务器配置，例如 'mcp-php'。配置内容如下：

{
  "mcpServers": {
    "mcp-php": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "http://127.0.0.1:3000/sse"
      ]
    }
  }
}

配置参数说明:

'"mcp-php"': 您为该 MCP 服务器配置自定义的名称，在 Cursor 中引用时使用。
'"command": "npx"': Cursor 启动 MCP 服务器的命令，这里使用 'npx' 来执行 'supergateway'。请注意，此配置可能需要根据实际使用的 MCP 客户端和工具链进行调整。仓库提供的配置是 'supergateway'，但仓库本身是 Hyperf PHP 项目，可能需要调整为直接运行 PHP 服务器，或者使用 'supergateway' 作为代理。根据仓库信息，更合理的配置应该是直接运行 PHP 服务器，而不是使用 'npx supergateway'。 以下提供更符合仓库实际情况的配置示例，用户可能需要根据自己的环境调整 PHP 执行路径。

更合理的配置示例 (直接运行 PHP 服务器):

{
  "mcpServers": {
    "mcp-php": {
      "command": "/usr/bin/php",  //  请替换为您的 PHP 可执行文件路径，可以使用 'which php' 命令查找
      "args": [
        "bin/hyperf.php",
        "start",
        "--server-name=mcp-sse" // 指定启动 mcp-sse 服务器
      ]
    }
  }
}

请注意: 上述配置示例直接运行 'bin/hyperf.php start' 启动 Hyperf 服务器，并通过 '--server-name=mcp-sse' 参数指定只启动 'mcp-sse' 服务。您需要根据您的 PHP 安装路径和实际需求调整 '"command"' 和 '"args"' 的配置。推荐先按照仓库 README 的 'php bin/hyperf.php start' 方式启动服务器并测试工具是否可用，再配置 Cursor 客户端。

基本使用方法

定义工具

在 'app/Tool' 目录下，您可以找到示例工具 'Foo.php'。使用 '#[Tool]' 注解定义工具名称、描述和关联的服务器名称 ('serverName' 需与 'config/server.php' 中 'servers' 下的 name 对应)。使用 '#[Description]' 注解为工具参数添加描述。

use Hyperf\Mcp\Annotation\Description;
use Hyperf\Mcp\Annotation\Tool;

class Foo
{
    #[Tool(
        name: 'getBirthday',
        description: 'Get the birthday of the person',
        serverName: 'mcp-sse'
    )]
    public function getBirthday(
        #[Description('姓名')]
        string $name
    ):mixed
    {
        return match ($name) {
            'John' => '1990-01-01',
            'Jane' => '1991-02-02',
            'Jack' => '1992-03-03',
            'Jill' => '1993-04-04',
            default => null,
        };
    }
}

在 Cursor 中调用工具

配置完成后，在 Cursor 中您可以使用 '@mcp-php:getBirthday name="John"' 这样的语法来调用 'getBirthday' 工具，其中 'mcp-php' 是您在 'claude_desktop_config.json' 中配置的服务器名称，'getBirthday' 是工具名称，'name="John"' 是传递给工具的参数。 Cursor 将会把请求发送到您配置的 MCP 服务器，并返回工具执行结果。

关键词

项目简介

主要功能点

安装步骤

服务器配置 (Cursor MCP 客户端)

基本使用方法

信息