Aerith Admin MCP 服务器

Aerith Admin MCP（Model, Controller, Presenter）服务器实现了受MANUS启发的开发工作流程，适用于具有浏览器自动化功能的RBAC仪表板应用程序。此服务器设计为在本地运行，并通过Cursor IDE的MCP集成进行访问。

概述

该服务器通过一个5步工作流程提供结构化的开发方法：

1. USER_INSTRUCTION - 定义具有明确目标的开发任务
2. TASK_PLANNING - 将任务分解为具体的子任务
3. INFORMATION_GATHERING - 从各种来源收集相关信息
4. ANALYSIS_AND_ORCHESTRATION - 分析信息并创建执行计划
5. RESULT_SYNTHESIS - 执行步骤并生成全面的报告

安装

# Clone the repository
git clone https://github.com/your-org/aerith-admin.git
cd aerith-admin/mcp

# Run the installation script (creates virtual environment and installs dependencies)
./bin/install.sh

# Activate the virtual environment
source bin/activate_venv.sh

使用

服务器可以以两种模式运行：

HTTP模式（默认）

python server.py --port 8090

这将启动服务器在端口8090上（或者指定其他端口）。服务器提供了REST API和Server-Sent Events (SSE)用于实时更新。

STDIO模式

python server.py --stdio

这种模式是为与其他工具集成而设计的，通过标准输入/输出使用JSON-RPC协议进行通信。

弹性模式

对于生产环境或长时间开发会话，您可以运行弹性模式的服务器，该模式会自动监控服务器健康状况并在崩溃时自动重启：

# Using the convenient script
./bin/start_cursor_server.sh --resilient

# Or directly using the resilient server script
./bin/run_resilient_server.sh --mode http --port 8090

弹性模式包括：

• 持续健康监控
• 自动重启崩溃
• 优雅关闭处理
• 心跳检测与日志记录

监控

您可以使用监控脚本手动检查服务器健康状态或重启它：

# Check if the server is running and healthy
./bin/monitor_server.py --check-only

# Force restart the server
./bin/monitor_server.py --force-restart

Cursor IDE 集成

这个MCP服务器特别设计来与Cursor IDE一起工作。Cursor可以从编辑器直接连接到服务器以利用其功能。

设置Cursor集成：

1. 确保MCP服务器正在HTTP模式下运行：python server.py --port 8090
2. Cursor会自动使用.cursor/mcp.json配置文件检测MCP服务器：

   {
     "mcpServers": {
       "aerith-admin-mcp": {
         "url": "http://localhost:8090/sse"
       }
     }
   }
   

3. 在Cursor IDE中打开Aerith Admin项目
4. 使用Cursor MCP集成UI与服务器交互

项目结构

mcp/
├── bin/                    # Executable scripts
│   ├── activate_venv.sh    # Script to activate virtual environment
│   ├── install.sh          # Installation script
│   ├── check_env.py        # Environment validation script
│   └── run_tests.py        # Test runner script
├── requirements.txt        # Production dependencies
├── requirements-dev.txt    # Development dependencies
├── server.py               # Main MCP server implementation
├── tests/                  # Test suite
│   ├── conftest.py         # Pytest configuration and fixtures
│   ├── README.md           # Testing documentation
│   ├── test_browser_automation.py # Browser automation tests
│   ├── test_core_workflow.py      # Workflow step tests
│   ├── test_integration.py        # End-to-end integration tests
│   ├── test_resources.py          # Resource access tests
│   ├── test_server_modes.py       # Server operation mode tests
│   └── test_utils.py              # Utility function tests
└── venv/                   # Virtual environment (created by install.sh)

开发设置

该项目使用专用虚拟环境进行开发：

# Run the installation script
./bin/install.sh

# Or manually set up the environment
python -m venv venv
source bin/activate_venv.sh
pip install -r requirements-dev.txt

# For browser automation testing
python -m playwright install

测试

测试使用pytest编写，并位于tests/目录中。

运行测试

使用提供的脚本来运行测试：

# Run all tests except browser and slow tests
./bin/run_tests.py -v

# Run with coverage report
./bin/run_tests.py --coverage

# Include browser automation tests
./bin/run_tests.py --browser

# Include slow integration tests
./bin/run_tests.py --slow

# Run specific test files or patterns
./bin/run_tests.py test_core_workflow

环境变量

• MCP_DEBUG=true - 启用调试日志（由activate_venv.sh自动设置）
• 可根据需要配置其他环境变量

API文档

工具

服务器提供了以下工具：

指令管理

• create_instruction(title, description, goal, priority) - 创建新的开发指令
• get_instruction(instruction_id) - 检索现有的指令
• build_feature(title, description, goal, priority) - 高层次协调以构建完整的功能

工作流步骤

• create_task_plan(instruction_id, subtasks) - 将指令分解为具体的子任务
• gather_information(instruction_id, sources) - 从各种来源收集信息
• analyze_and_orchestrate(instruction_id, analysis, execution_plan) - 分析并创建执行计划
• execute_step(instruction_id, step_id, execution_details) - 执行计划中的特定步骤
• generate_final_report(instruction_id, include_details) - 生成最终报告

浏览器自动化

• run_browser_agent(goal) - 运行浏览器使用代理以实现指定目标

文件系统工具

• tree_directory(directory_path, max_depth, show_files, show_hidden, pattern, exclude_common, custom_excludes) - 生成目录结构的树状表示，类似于 Unix 的 'tree' 命令

Git 工具

• git_status(detailed) - 显示工作树状态
• git_log(count, show_stats, path, author, since, until) - 显示提交日志
• git_diff(file_path, staged, commit, compare_with) - 显示提交之间或与工作树之间的更改
• git_branch(create, delete, remote, branch_name, base_branch) - 列出、创建或删除分支
• git_checkout(branch_name, create, force) - 切换分支或恢复工作树文件
• git_commit(message, all_changes, amend) - 记录对仓库的更改
• git_push(remote, branch, force, tags) - 更新远程引用及其关联的对象
• git_pull(remote, branch, rebase) - 从另一个仓库拉取并集成
• git_add(paths) - 将文件内容添加到暂存区

资源

服务器提供以下资源：

• file://{path} - 根据路径获取文件内容
• project://structure - 以字典形式获取项目结构
• instructions://list - 获取所有指令列表

数据存储

所有指令及相关数据都存储在 .aerith/instructions 目录下的 JSON 文件中。

日志记录

日志存储在 .aerith/logs/mcp_server.log 中，并且也会输出到 stderr。当设置 MCP_DEBUG=true（默认在开发环境中）时，将启用详细的调试日志记录。

许可证

MIT License