使用说明

项目简介

Hyperf MCP Server 是一个基于 Hyperf 协程框架构建的模型上下文协议 (MCP) 服务器实现。它旨在为大型语言模型 (LLM) 应用提供标准化的上下文信息和功能访问接口。通过 MCP 协议，服务器可以安全、可扩展地向 LLM 客户端提供资源管理、工具执行和 Prompt 模板渲染等核心服务。本实现使用 Server-Sent Events (SSE) 协议作为主要的通信方式。

主要功能点

资源管理 (Resources): (代码中 resources 相关功能未完全实现，但框架已预留接口) 支持托管和管理各种类型的数据资源，并提供 LLM 客户端访问这些资源的能力。（当前版本可能未完全实现资源管理功能，未来版本可能会完善）
工具注册和执行 (Tools): 允许开发者注册外部功能为工具，并通过简单的注解声明工具的名称、描述和参数。LLM 客户端可以通过 MCP 协议调用这些工具，扩展自身的功能。
Prompt 模板 (Prompts): (代码中 prompts 相关功能未实现) 支持定义和渲染 Prompt 模板，以便根据不同的上下文和需求，动态生成与 LLM 交互的 Prompt。（当前版本未实现 Prompt 模板功能）
基于 SSE 协议的通信: 使用高效的 SSE 协议与客户端进行实时通信，推送服务器端事件和响应客户端请求。
JSON-RPC 协议风格: 采用 JSON-RPC 风格的消息格式，方便客户端和服务端进行结构化数据的交换。
会话管理: 通过 sessionId 参数进行会话管理，支持有状态的长连接。

安装步骤

确保你的 PHP 环境满足 Hyperf 框架的要求 (PHP >= 8.1, Swoole 扩展等)。

使用 Composer 安装 mcp-incubator 仓库：

composer require hyperf/mcp

配置 Hyperf 服务器，启用 'mcp-sse' 服务器。修改 'autoload/server.php' 文件，添加或修改 servers 配置如下：

<?php

use Hyperf\Server\Server;
use Hyperf\Server\Event;
use Hyperf\Mcp\Server\McpServer;

return [
    'type' => Hyperf\Server\CoroutineServer::class,
    'servers' => [
        [
            'name' => 'mcp-sse',
            'type' => Server::SERVER_HTTP,
            'host' => '0.0.0.0',
            'port' => 3000,
            'sock_type' => SWOOLE_SOCK_TCP,
            'callbacks' => [
                Event::ON_REQUEST => [McpServer::class, 'onRequest'],
                Event::ON_CLOSE => [McpServer::class, 'onClose'],
            ],
        ],
    ],
];

注意: SSE 协议属于有状态长连接协议, 请确保你的 Nginx 配置支持长连接, 并且根据 'sessionId' 参数进行负载均衡。

服务器配置

MCP 客户端需要配置以下服务器信息以连接到 Hyperf MCP Server：

{
  "server": "mcp-sse",  // 服务器名称，与 autoload/server.php 中配置的 name 一致
  "command": "php",     // 启动服务器的命令
  "args": [             // 启动服务器命令的参数
    "bin/hyperf.php",
    "start"
  ]
}

基本使用方法

定义工具 (Tool): 在 Hyperf 控制器 (Controller) 中，使用 '#[Tool]' 注解声明工具。例如：

<?php

namespace App\Controller;

use Hyperf\Di\Annotation\Controller;
use Hyperf\Di\Annotation\Inject;
use Hyperf\Http\Annotation\GetMapping;
use Hyperf\Http\Annotation\PostMapping;
use Hyperf\Mcp\Annotation\Tool;
use Hyperf\Mcp\McpHandler;

#[Controller(server: 'mcp-sse')]
class IndexController
{
    #[Inject]
    protected McpHandler $mcpHandler;

    #[GetMapping(path: '/sse')]
    public function sse()
    {
        $this->mcpHandler->handler('/messages');
    }

    #[PostMapping(path: '/messages')]
    public function messages()
    {
        return $this->mcpHandler->message();
    }

    #[Tool(name: 'sum', description: '计算两个数的和')]
    public function sum(int $a, int $b = 0): int
    {
        return $a + $b;
    }
}

'#[Tool(name: 'sum', description: '计算两个数的和')]' 注解将 'sum' 方法注册为一个名为 'sum'，描述为 "计算两个数的和" 的工具。

启动服务器: 在项目根目录下运行 Hyperf 服务器启动命令：
```
php bin/hyperf.php start
```
客户端连接: MCP 客户端需要连接到服务器的 '/sse' 路径，并使用 '/messages' 路径发送 MCP 消息。客户端需要实现 MCP 协议的客户端逻辑，例如发送 'initialize' 请求以获取服务器能力，发送 'tools/call' 请求以调用工具等。
调用工具: 客户端可以通过发送 'tools/call' 消息来调用已注册的工具，消息体需要包含工具的名称和参数。服务器会执行相应的工具方法，并将结果返回给客户端。

注意: 此仓库为 MCP 协议的孵化版本，部分功能可能仍在完善中。请参考代码和文档进行更详细的了解和使用。

关键词