AI导哈

PHP MCP服务器

一个带有Web仪表板的PHP MCP服务器，提供远程可调用工具集、加密秘密管理和多模式操作支持。

  • by mafio69
  • PHP
  • 本地部署
  • 更新于
在 GitHub 查看 mafio69/enhanced-php-mcp-server

使用说明

带有Web仪表板的增强型PHP MCP服务器

高级PHP MCP服务器，具有全面的工具集和web界面。该服务器使用基于JSON的协议通过标准输入/输出进行通信，并提供了一套丰富的远程可调用工具，以及一个用于管理和测试的现代web仪表板。

🚀 特性

  • 10个内置工具：你好，时间，计算器，文件操作，系统信息，JSON解析，天气，HTTP请求
  • 管理面板：密码保护的管理仪表板，带有系统信息和秘密管理
  • 秘密经理：API密钥和凭证的加密存储（AES-256-CBC）
  • MCP服务器管理：通过API或CLI动态添加外部MCP服务器
  • 安全：路径限制、文件大小限制、输入验证
  • 配置：具有环境支持的集中式配置系统
  • 日志记录：具有可配置级别的全面日志记录
  • CLI和HTTP：双模式操作支持
  • 现代PHP：需要PHP 8.1+和适当的自动加载
  • 全面测试：单元测试、集成测试、性能测试

🐳 套件集成（Devbox）

此MCP服务器正式集成为 docker快速php日志 开发者套件生态系统。

在集成Docker环境中运行时：

  • Web仪表板： 自动访问 http://localhost:8000
  • 集装箱： 自动运行 mcp-server Docker服务
  • 安装： 通过套件内的Composer在全球范围内进行全面管理(mafio69/enhanced-php-mcp-server)

如果您正在使用套件 不 需要使用 ./start.sh。只需通过套件脚本进行管理：

./suite start
# or individually:
./suite mcp:start

📋 需求

  • PHP>=8.1
  • 作曲家
  • 所需扩展： json, curl

🛠️ 安装

  1. 克隆或下载存储库
  2. 安装依赖项：
    composer install
  3. 使启动脚本可执行：
    chmod +x start.sh

🎯 快速开始

🚀 快速入门（推荐）

# 1. Install dependencies
./start.sh 6

# 2. Run web server (browser interface)
./start.sh 2

打开http://localhost:8794以访问API。

🎮 交互菜单

./start.sh

这将显示一个彩色菜单，其中包含可供选择的选项。

🌐 Web API（用于浏览器）

./start.sh 2      # Run web server on http://localhost:8794

📡 CLI模式（适用于MCP客户端）

./start.sh 1      # Run MCP server via stdin/stdout

🔍 服务器管理

./start.sh 4      # Check status
./start.sh 5      # View logs

🖥️ CLI模式（交互菜单）

./start.sh

如果终端不是交互式的，它将显示带有选项的菜单：

./start.sh        # Show menu with options
./start.sh 1      # CLI Mode - MCP server via stdin/stdout
./start.sh 2      # Web Mode - HTTP server with Slim Framework
./start.sh 3      # All Modes - CLI + Web simultaneously
./start.sh 4      # Status - check server status
./start.sh 5      # Logs - show recent logs
./start.sh 6      # Install - install dependencies

CLI使用示例

# Run server in interactive mode (shows menu)
./start.sh

# Run directly in CLI mode (for MCP clients)
./start.sh 1

# Run web server (for browser)
./start.sh 2

# Check status of running servers
./start.sh 4

# View recent logs
./start.sh 5

手动启动

php index.php

作曲家脚本

composer start

📚 可用工具

服务器提供了10个强大的工具：

1. 你好

用名字问候一个人。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"hello","arguments":{"name":"John"}}}' | php index.php

2. 获取时间

返回当前日期和时间信息。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_time"}}' | php index.php

3. 计算

执行数学运算（加、减、乘、除）。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"calculate","arguments":{"operation":"add","a":10,"b":5}}}' | php index.php

4. read_file

安全读取项目目录中的文件内容。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"README.md"}}}' | php index.php

5. write_file

安全地将内容写入项目目录中的文件。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"write_file","arguments":{"path":"test.txt","content":"Hello World"}}}' | php index.php

6. 列表文件

列出指定路径中的文件和目录。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_files","arguments":{"path":"."}}}' | php index.php

7. 系统信息

返回全面的系统和PHP信息。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"system_info"}}' | php index.php

8. http_request

向外部API发出HTTP请求。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"http_request","arguments":{"url":"https://api.github.com","method":"GET"}}}' | php index.php

9. jsonparse

解析和格式化JSON字符串。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"json_parse","arguments":{"json":"{\"test\": true}"}}}' | php index.php

10. get_weather

获取指定城市的天气信息。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_weather","arguments":{"city":"London"}}}' | php index.php

🌐 Web API（HTTP模式）

当服务器在Web模式下运行时(./start.sh 2)，以下端点可用：

基本终点

  • GET / -服务器信息/登录页面
  • GET /api/tools -可用工具列表
  • GET /api/status -服务器状态和指标
  • GET /api/metrics -系统指标
  • GET /api/health -健康检查端点

工具执行

  • POST /api/tools/call -执行工具

日志管理

  • GET /api/logs -最近的日志条目
  • GET /api/logs/download -将日志下载为文件
  • GET /api/logs/stats -日志统计
  • DELETE /api/logs -清除所有日志

工具调用示例：

# Greeting
curl -X POST http://localhost:8794/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "hello", "arguments": {"name": "John"}}'

# Calculation
curl -X POST http://localhost:8794/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "calculate", "arguments": {"operation": "add", "a": 10, "b": 5}}'

# File listing
curl -X POST http://localhost:8794/api/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_files", "arguments": {"path": "src"}}'

🔐 管理面板

服务器包括一个受密码保护的管理面板，用于管理和监控。

访问面板

./start.sh 2                     # Start web server
# Open http://localhost:8794/admin/login

默认凭据： admin / admin123

⚠️ 首次登录后立即更改默认密码。通过设置自定义凭据 ADMIN_USERNAME 和 ADMIN_PASSWORD 环境变量。

身份验证方法

管理面板支持两种身份验证方法：

  • 基于Cookie：登录表单设置HttpOnly，SameSite=Strict cookie（8小时会话）
  • 持有者代币：API请求可以使用 Authorization: Bearer <session_id> 头球

管理员路由

路线 方法 描述
/admin/login GET 登录页面
/admin/login POST 验证用户身份
/admin/dashboard GET 管理仪表板（需要身份验证）
/admin/logout POST 结束会话
/admin/user GET 当前用户信息
/admin/change-password POST 更改管理员密码
/admin/config GET 身份验证配置状态
/admin/system-info GET 详细系统信息

系统信息

已认证 /admin/system-info 端点返回全面的数据：

  • 系统：操作系统、主机名、正常运行时间、平台详细信息
  • PHP：版本、内存限制、扩展名、错误报告
  • 服务器：软件、协议、端口、SSL状态
  • MCP服务器：名称、版本、调试模式、启用的工具
  • 资源：内存使用率（当前/峰值）、磁盘空间、平均负载
  • 安全：会话状态、open_basedir、disable_functions

📋 环境变量

变量 默认值 描述
ADMIN_USERNAME admin 管理面板用户名
ADMIN_PASSWORD admin123 管理面板密码
MCP_SECRET_KEY 自动生成 用于机密的AES-256-CBC加密密钥

💡 注： 这 MCP_SECRET_KEY 在首次启动时自动生成并安全保存到 .env 项目根目录中的文件。除非您希望提供自己的预定义密钥，否则不需要手动配置它。

🔧 配置

服务器配置通过以下方式管理 config/server.php:

return [
    'server' => [
        'name' => 'enhanced-php-mcp-server',
        'version' => '2.1.0',
    ],
    'logging' => [
        'enabled' => true,
        'file' => __DIR__ . '/../logs/server.log',
        'level' => 'info',
    ],
    'security' => [
        'allowed_paths' => [__DIR__ . '/..'],
        'max_file_size' => 10 * 1024 * 1024, // 10MB
    ],
    // ... more configuration
];

🔐 秘密经理

该服务器包括一个加密的秘密存储系统，用于API密钥和证书等敏感数据。

概述

  • 加密：AES-256-CBC，每个值具有唯一的IV
  • 存储：中的加密文件 storage/secrets/ 具有受限权限（0600）
  • 密钥管理：来自的加密密钥 MCP_SECRET_KEY env-var，自动生成 storage/.secret_key 文件，或首次使用时新生成的

管理员API端点

所有端点都需要管理员身份验证（承载令牌或会话cookie）。

方法 路线 描述
GET /admin/api/secrets 列出所有存储的秘密（仅密钥）
POST /admin/api/secrets 存储新秘密
GET /admin/api/secrets/{key} 检索机密值
DELETE /admin/api/secrets/{key} 删除机密
GET /admin/api/secrets/{key}/check 检查是否存在秘密
POST /admin/api/secrets/encrypt 加密值而不存储
POST /admin/api/secrets/decrypt 解密一个值
POST /admin/api/secrets/migrate 从配置中迁移机密

例子

# Store a secret
curl -X POST http://localhost:8794/admin/api/secrets \
  -H "Content-Type: application/json" \
  -d '{"key": "api.openai.key", "value": "sk-..."}'

# Retrieve a secret
curl http://localhost:8794/admin/api/secrets/api.openai.key

# List all secrets
curl http://localhost:8794/admin/api/secrets

# Encrypt a value
curl -X POST http://localhost:8794/admin/api/secrets/encrypt \
  -H "Content-Type: application/json" \
  -d '{"value": "my-sensitive-data"}'

# Decrypt a value
curl -X POST http://localhost:8794/admin/api/secrets/decrypt \
  -H "Content-Type: application/json" \
  -d '{"encrypted": "base64encrypteddata..."}'

秘密移民

运行迁移终结点以自动检测并从以下位置迁移机密 config/server.php:

curl -X POST http://localhost:8794/admin/api/secrets/migrate

迁移器检测与常见模式匹配的值（OpenAI sk-*谷歌 AIza*、长字母数字键等）。

🔗 MCP服务器管理

服务器支持通过管理员API和CLI对外部MCP服务器进行动态管理。

配置

外部MCP服务器可以在中定义 config/server.php 在...之下 mcpServers 按键：

'mcpServers' => [
    'Brave-search' => [
        'mcpServers' => [
            'brave-search' => [
                'command' => 'npx',
                'args' => ['-y', '@brave/brave-search-mcp-server', '--transport', 'http'],
                'env' => [
                    'BRAVE_API_KEY' => '${BRAVE_API_KEY}',
                ],
            ],
        ],
    ],
],

管理员API

方法 路线 描述
POST /admin/api/servers 添加新的MCP服务器

CLI命令

php index.php app:add-server <name> <ipAddress> <port>

📁 项目结构

enhanced-php-mcp-server/
├── config/              # Configuration files
│   └── server.php       # Server configuration
├── src/                 # Source code
│   ├── Commands/        # CLI commands (AddServerCommand)
│   ├── Config/          # ServerConfig class
│   ├── Controllers/     # HTTP controllers (Admin, Logs, Secret, Server, Status, Tools)
│   ├── DTO/             # Data Transfer Objects (AddServer, Error, ServerInfo, Status, Tool)
│   ├── Middleware/      # PSR-15 middleware (AdminAuth)
│   ├── Routing/         # Route definitions (ApiRoutes)
│   ├── Services/        # Business logic (AdminAuth, Monitoring, SecretManager, Server, Tool)
│   ├── Utils/           # Helpers (ApiResponse)
│   ├── AppContainer.php # PHP-DI container builder
│   ├── Logger.php       # PSR-3 logger wrapper
│   ├── MCPServer.php    # CLI mode implementation
│   └── MCPServerHTTP.php # HTTP mode implementation
├── templates/           # HTML templates
│   └── views/
│       ├── admin/       # Admin panel views (dashboard, login)
│       └── loading.php  # Landing page
├── tests/               # Test files (Unit, Integration, Performance)
├── logs/                # Log files
├── storage/             # Session & secrets storage
├── vendor/              # Composer dependencies
├── index.php            # Main entry point
├── start.sh             # Start script
├── composer.json        # Dependencies and autoloading
└── README.md            # This file

🔒 安全特性

  • 路径限制：文件操作仅限于允许的目录
  • 文件大小限制：可配置的操作最大文件大小
  • 输入验证：所有输入都经过验证和消毒
  • 错误处理：全面的错误处理，不会暴露敏感信息
  • 路径横向保护：防止访问项目目录外的文件

🧪 测试

该项目包括全面的测试套件：

快速测试

# Simple bash tests
./tests/simple_test.sh

PHPUnit测试

# Run all unit tests
composer test

# Run specific test
./vendor/bin/phpunit --filter testHelloTool

# Generate coverage report
./vendor/bin/phpunit --coverage-html coverage-html

集成测试

# Full HTTP API tests
./tests/run_comprehensive_tests.sh

性能测试

# Performance testing plan
./tests/PERFORMANCE_TESTS_PLAN.md

📝 发展

代码风格

composer cs-check    # Check code style
composer cs-fix      # Fix code style issues

测试

composer test        # Run all tests

依赖项

composer install     # Install dependencies
composer update      # Update dependencies

📝 日志记录

日志在中自动创建 logs/server.log 带有时间戳和严重性级别：

[2024-01-01 12:00:00] INFO Server started
[2024-01-01 12:00:01] INFO Tool 'hello' executed

🌟 例子

初始化服务器

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | php index.php

列出所有工具

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | php index.php

连锁经营

# Write a file, then read it back
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"write_file","arguments":{"path":"demo.txt","content":"Hello from MCP!"}}}' | php index.php

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"demo.txt"}}}' | php index.php

🚨 故障排除

常见问题

  1. 权限不足：确保 start.sh 脚本是可执行的(chmod +x start.sh)
  2. 缺少依赖关系：运行 composer install
  3. 缺少扩展：安装所需的PHP扩展(php-json, php-curl)
  4. 文件访问：检查项目目录中的文件权限
  5. 端口冲突：服务器自动检测端口8794、8795、8890

调试模式

通过将日志级别设置为启用详细日志记录 debug 在 config/server.php.

📊 性能指标

服务器包括内置监控：

  • 响应时间跟踪
  • 内存使用监控
  • 工具执行统计
  • 系统指标收集

通过以下方式访问 /api/status 或 /api/metrics 端点。

📝 更新日志

v2.1.0（当前）

安全和加密：

  • 修复了IV分离器碰撞错误 SecretManagerService -IV现在采用base64编码，以防止与 :: 随机二进制数据中的分隔符
  • 保持向后兼容性：旧的加密秘密（原始二进制IV）继续工作
  • 新的加密秘密使用base64编码的IV格式

基础设施：

  • 已删除已弃用 public/router.php -静态文件处理已移至 public/index.php
  • 已更新Dockerfile以供使用 public/index.php 直接
  • 固定的 curl_close() HTTP客户端工具中的资源泄漏

配置：

  • 从中删除了硬编码的开发人员路径 ServerConfig::getLogFile()
  • 改进的 getAllowedPaths() 始终包含项目根

测试：

  • 将测试脚本合并为单个 tests.sh
  • 删除了过时的测试脚本(test.sh, tests/simple_test.sh, tests/run_comprehensive_tests.sh)
  • 修复了Playwright的E2E测试配置

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🤝 贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

📞 支持

对于问题和疑问：

  • 检查登录 logs/server.log
  • 查看中的配置 config/server.php
  • 确保满足所有要求
  • 运行测试套件以诊断问题

相关 MCP