使用说明

Hello World MCP服务器-PHP实现

纯PHP中没有依赖关系的最小模型上下文协议（MCP）服务器实现。这展示了MCP是如何在基础层面上工作的。

MCP的工作原理

模型上下文协议（MCP）使像Claude这样的人工智能助手能够与外部工具和数据源进行交互。架构如下：

┌─────────────┐         JSON-RPC over stdio        ┌─────────────┐
│             │ ────────────────────────────────> │             │
│  MCP Client │                                    │  MCP Server │
│ (Claude)    │ <──────────────────────────────── │    (PHP)    │
└─────────────┘                                    └─────────────┘

关键概念

运输：通过stdio（标准输入/输出）进行通信
协议：所有消息均采用JSON-RPC 2.0格式
工具：服务器公开的客户端可以调用的函数
模式：每个工具都有一个描述其参数的输入模式

消息流

初始化：客户端发送具有功能的初始化请求
列出工具：客户请求可用的工具
呼叫工具：客户端使用参数调用工具
响应：服务器返回结果

文件

mcp-server.php -MCP服务器实现
mcp-config.json -Claude代码的配置
test-mcp.sh -测试脚本以验证服务器是否正常工作
README.md -此文件

先决条件

您的系统上需要安装PHP（建议使用PHP 7.4或更高版本）。

在macOS上安装PHP

# Using Homebrew
brew install php

# Verify installation
php --version

在Linux上安装PHP

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install php-cli

# Fedora/CentOS
sudo dnf install php-cli

# Verify installation
php --version

测试服务器

运行测试脚本以验证服务器是否正常工作：

./test-mcp.sh

您应该看到以下JSON响应：

服务器初始化
可用工具列表
工具执行结果

手动测试

您还可以通过管道JSON-RPC请求手动测试：

# Initialize the server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | php mcp-server.php

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | php mcp-server.php

# Call the helloWorld tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"helloWorld","arguments":{"name":"PHP"}}}' | php mcp-server.php

使用Claude代码

要将此MCP服务器与Claude代码一起使用：

选项A：将配置复制到Claude Code的全局配置

# Location of Claude Code config (adjust path if needed)
# macOS/Linux: ~/.claude-code/mcp.json
# Windows: %APPDATA%\claude-code\mcp.json

将此添加到 mcpServers 章节：

{
  "mcpServers": {
    "hello-world-php": {
      "command": "php",
      "args": ["mcp-server.php"],
      "cwd": "/Users/sergederhy/work/hello-world-mcp/test",
      "description": "Hello World MCP server in PHP"
    }
  }
}

选项B：使用本地配置文件

这 mcp-config.json 此目录中的文件可以用作参考。
重新启动Claude代码 加载新的MCP服务器
验证：Claude Code现在应该可以访问 helloWorld 工具

理解代码

服务器结构

class MCPServer {
    // Server metadata
    private $serverInfo = ['name' => '...', 'version' => '...'];

    // Registered tools
    private $tools = [];

    // Register a tool
    public function registerTool($name, $schema, $handler) { ... }

    // Handle incoming requests
    public function handleRequest($request) { ... }

    // Start listening on stdio
    public function start() { ... }
}

请求处理

服务器处理这些JSON-RPC方法：

初始化 -握手和能力谈判
工具/列表 -返回可用工具及其模式
工具/调用 -使用给定的参数执行工具

添加新工具

要添加新工具，请在构造函数中注册它：

$this->registerTool('myTool', [
    'description' => 'Description of what this tool does',
    'inputSchema' => [
        'type' => 'object',
        'properties' => [
            'param1' => [
                'type' => 'string',
                'description' => 'Parameter description'
            ]
        ]
    ]
], function($params) {
    // Your tool logic here
    return [
        'content' => [
            ['type' => 'text', 'text' => 'Result']
        ]
    ];
});

体系结构决策

此实现有意最小化，以演示MCP概念：

无依赖关系：纯PHP，无作曲家包
单个文件：所有代码都放在一个文件中，便于理解
同步：为了清晰起见，简单的阻塞I/O
基本验证：尽量减少错误处理，以保持代码可读性

对于生产使用，请考虑：

添加输入验证
更好的错误处理
记录到文件而不是stderr
使用异步I/O以获得更好的性能
添加更复杂的工具模式

常见问题

未找到PHP

# Install PHP first (see Prerequisites section)
brew install php  # macOS

权限不足

chmod +x mcp-server.php
chmod +x test-mcp.sh

服务器未响应

检查stderr输出中的调试消息：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | php mcp-server.php 2>&1

后续步骤

实验：修改helloWorld工具以执行不同的操作
添加工具：创建新工具（计算器、文件读取器等）
联系克劳德：配置Claude Code以使用此服务器
了解更多：阅读 MCP文件

许可证

国际协调委员会