# php-mcp-fileserver

**Repository Path**: az13js/php-mcp-fileserver

## Basic Information

- **Project Name**: php-mcp-fileserver
- **Description**: No description available
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-05
- **Last Updated**: 2026-03-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PHP MCP File Server
> 一个轻量、无第三方依赖的 PHP 文件服务器，严格遵循 [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) 规范。
本项目提供了一个基于 PHP-FPM 的 MCP 文件管理实现。它允许符合 MCP 协议的客户端（如 AI 模型或工具）通过标准的 JSON-RPC 2.0 接口安全地读写本地文件系统。
## 核心特性
- **零第三方依赖**：纯 PHP 7.4+ 实现，无需安装 `symfony/console` 或其他重型框架。
- **协议合规**：严格实现了 MCP `2024-11-05` 版本的核心方法（`initialize`, `tools/list`, `tools/call`）。
- **安全沙箱**：通过环境变量 `MCP_ALLOWED_DIRS` 严格控制访问权限，有效防止路径遍历攻击。
- **标准化接口**：基于 JSON-RPC 2.0 标准，支持 HTTP POST 通信。
## 环境要求
- PHP >= 7.4
- PHP-FPM（或任何能运行 PHP 的 Web 服务器，如 Nginx + PHP-FPM）
- Composer（仅用于 PSR-4 自动加载生成）
## 快速开始
### 1. 安装
克隆项目并生成自动加载文件：
```bash
git clone https://github.com/az13js/php-mcp-fileserver.git
cd php-mcp-fileserver
composer dump-autoload
```
### 2. 配置 Web 服务器
项目入口文件为 `public/index.php`。以下是 Nginx 配置示例：
```nginx
server {
    listen 80;
    server_name localhost;
    root /path/to/php-mcp-fileserver/public;
    index index.php;
    location / {
        if (!-e $request_filename) {
            rewrite ^(.*)$ /index.php?s=/$1 last;
        }
    }
    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000; # 或 unix socket
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

        # 关键：传递安全目录配置
        fastcgi_param MCP_ALLOWED_DIRS "/var/www/data:/tmp/uploads";
    }
}
```
> **注意**：如果不设置 `MCP_ALLOWED_DIRS`，服务器将**不限制**任何目录的访问权限（请谨慎使用）。
### 3. 协议接口说明
本服务遵循 JSON-RPC 2.0 规范，所有请求均通过 POST 发送至 `/index.php`，Content-Type 为 `application/json`。
#### 3.1 初始化握手 (`initialize`)
客户端应首先调用此方法完成协议握手。
**请求示例：**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "test-client",
      "version": "1.0.0"
    }
  }
}
```
**响应示例：**
```json
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": false },
      "resources": { "subscribe": false, "listChanged": false },
      "prompts": { "listChanged": false }
    },
    "serverInfo": {
      "name": "mcp-file-server",
      "version": "1.0.0"
    }
  },
  "id": 1
}
```
#### 3.2 列出可用工具 (`tools/list`)
获取服务器支持的所有文件操作工具定义。
**请求示例：**
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
```
**支持的工具列表：**
- `read_file`: 读取文件内容
- `write_file`: 写入文件内容
- `list_directory`: 列出目录内容
- `create_directory`: 创建目录
- `delete_file`: 删除文件或目录
- `get_file_info`: 获取文件或目录信息
#### 3.3 调用工具 (`tools/call`)
通过指定工具名称和参数执行文件操作。
**请求示例 (读取文件)：**
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": {
      "path": "/var/www/data/example.txt"
    }
  }
}
```
**响应示例：**
```json
{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"content\": \"Hello World\", \"size\": 11, \"mimeType\": \"text/plain\"}"
      }
    ],
    "isError": false
  },
  "id": 3
}
```
## 安全机制
### 路径遍历防护
服务器实现了双重安全检查机制，防止恶意访问系统关键文件：
1. **环境变量白名单**：只有配置在 `MCP_ALLOWED_DIRS` 中的目录及其子目录才允许访问。
2. **路径规范化**：使用 `realpath()` 解析所有符号链接和相对路径，确保路径的绝对真实性。
3. **边界检查**：防止 `/var/www` 匹配到 `/var/www-data` 等前缀相似但目录不同的情况。
### 错误处理
所有错误均按照 JSON-RPC 2.0 标准返回，常见的错误码如下：
| 错误码 | 含义 | 说明 |
| :--- | :--- | :--- |
| -32700 | Parse error | 请求体不是有效的 JSON 格式 |
| -32600 | Invalid Request | 请求不符合 JSON-RPC 2.0 规范 |
| -32601 | Method not found | 请求的方法不存在 |
| -32603 | Internal error | 服务器内部错误（如权限拒绝、文件不存在等） |
## 测试命令
您可以使用 `curl` 命令快速测试服务器是否正常运行：
```bash
# 1. 测试初始化
curl -X POST http://localhost/index.php \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'
# 2. 获取工具列表
curl -X POST http://localhost/index.php \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# 3. 测试读取文件 (请先确保目录和文件存在)
curl -X POST http://localhost/index.php \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"/var/www/data/test.txt"}}}'
```
## 许可证
本项目基于 [MIT](LICENSE) 协议开源。