pepflow MCP

PEPFlow MCP

使用PEPFlow框架进行优化算法收敛分析的MCP工具

目录

• 概述
• 安装
• 本地使用（脚本）
• MCP服务器安装
• 使用Claude代码
• 与Gemini CLI一起使用
• 可用工具
• 例子
• 故障排除

概述

PEPFlow MCP提供了使用性能估计问题（PEP）框架分析优化算法收敛性的工具。PEP是一种数学方法，可以对光滑凸函数的一阶优化方法进行最坏情况分析。

特性

• 梯度下降分析：O（1/k）收敛性验证与分析证明
• 加速梯度法：O（1/k²）收敛与θ序列计算
• 算法比较：跨多种优化方法的性能基准测试
• 批处理：用于算法调整的参数扫描和灵敏度分析

目录结构

./
├── README.md                           # This file
├── env/                                # Conda environment
├── src/
│   ├── server.py                       # MCP server (15 tools)
│   └── jobs/                          # Job management system
├── scripts/
│   ├── gradient_descent_analysis.py   # O(1/k) convergence analysis
│   ├── accelerated_gradient_analysis.py # O(1/k²) AGM analysis
│   ├── pep_optimization_framework.py  # Multi-algorithm framework
│   └── lib/                           # Shared utilities (45 functions)
├── examples/
│   ├── use_case_1_gradient_descent.py # Example GD analysis
│   ├── use_case_2_accelerated_gradient.py # Example AGM analysis
│   ├── use_case_3_pep_optimization.py # Example comparison analysis
│   └── data/                          # Algorithm notebooks and examples
├── configs/                           # Configuration files
│   ├── gradient_descent_config.json   # GD parameters
│   ├── accelerated_gradient_config.json # AGM parameters
│   └── pep_optimization_config.json   # General framework config
├── reports/                           # Step-by-step documentation
└── repo/                              # Original PEPFlow repository
    └── PEPFlow/                       # PEPFlow framework source

______________________________________________________________________

安装

快速设置

运行自动安装脚本：

./quick_setup.sh

这将创建环境并自动安装所有依赖项。

手动设置（高级）

对于手动安装或自定义，请执行以下步骤。

先决条件

• Conda或Mamba（建议使用曼巴以加快安装速度）
• Python 3.10+
• PEPFlow框架依赖关系（NumPy、SymPy、CVXPY、Matplotlib）

创建环境

请按照以下环境设置程序进行操作 reports/step3_environment.md经过验证的工作流程是：

# Navigate to the MCP directory
cd /home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/pepflow_mcp

# Create conda environment (use mamba if available)
mamba create -p ./env python=3.10 -y
# or: conda create -p ./env python=3.10 -y

# Activate environment
mamba activate ./env
# or: conda activate ./env

# Install PEPFlow Framework
cd repo/PEPFlow
mamba run -p ../../env pip install -e .

# Install MCP dependencies
cd ../../
mamba run -p ./env pip install fastmcp loguru --ignore-installed

# Install mathematical solvers
mamba install -c conda-forge osqp clarabel scs -y

______________________________________________________________________

本地使用（脚本）

您可以在没有MCP的情况下直接使用脚本进行本地处理。

可用脚本

脚本示例

梯度下降分析

# Activate environment
mamba activate ./env

# Run gradient descent analysis
mamba run -p ./env python scripts/gradient_descent_analysis.py \
  --config configs/gradient_descent_config.json \
  --iterations 8 \
  --proof-steps 2 \
  --output results/gd_analysis

参数：

• --config, -c：配置文件路径（默认：使用内置配置）
• --iterations, -n：数值分析的迭代次数（默认值：8）
• --proof-steps, -p：分析证明的步骤数（默认值：2）
• --lipschitz, -L：Lipschitz常数L（默认值：1.0）
• --radius, -R：初始距离界限R（默认值：1.0）
• --output, -o：输出目录（默认：results/）
• --skip-plot：跳过绘图以加快执行速度

加速梯度分析

mamba run -p ./env python scripts/accelerated_gradient_analysis.py \
  --config configs/accelerated_gradient_config.json \
  --iterations 5 \
  --proof-steps 3 \
  --output results/agm_analysis

特殊功能：

• Theta序列计算：θₖ = (1 + √(1 + 4θₖ₋₁²))/2
• O（1/k²）收敛验证
• 双变量分析

算法比较

# Single algorithm
mamba run -p ./env python scripts/pep_optimization_framework.py \
  --algorithm gradient_descent \
  --iterations 5

# Heavy ball with momentum
mamba run -p ./env python scripts/pep_optimization_framework.py \
  --algorithm heavy_ball \
  --iterations 4 \
  --momentum 0.3

# Compare multiple algorithms
mamba run -p ./env python scripts/pep_optimization_framework.py \
  --algorithm comparison \
  --iterations 3

______________________________________________________________________

MCP服务器安装

选项1：使用fastmcp（推荐）

# Install MCP server for Claude Code
fastmcp install src/server.py --name pepflow-tools

选项2:Claude代码的手动安装

# Add MCP server to Claude Code
claude mcp add pepflow-tools -- $(pwd)/env/bin/python $(pwd)/src/server.py

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

{
  "mcpServers": {
    "pepflow-tools": {
      "command": "/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/pepflow_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/pepflow_mcp/src/server.py"]
    }
  }
}

______________________________________________________________________

使用Claude代码

安装MCP服务器后，您可以直接在Claude Code中使用它。

快速开始

# Start Claude Code
claude

示例提示

工具发现

What optimization analysis tools are available from pepflow-tools?

快速收敛分析（同步）

Analyze gradient descent convergence for 8 iterations with 2 proof steps. Verify the O(1/k) convergence rate.

大规模分析（提交API）

Submit a gradient descent analysis job for 50 iterations and 20 proof steps. Name the job "large_scale_gd" and track its progress.

检查作业状态

Check the status of job abc12345 and show me the execution logs.

算法比较

Compare the performance of gradient descent, heavy ball (momentum=0.3), and accelerated gradient methods for 10 iterations each.

参数扫描

Submit a parameter sweep job for the heavy_ball algorithm with:
- momentum values: [0.1, 0.3, 0.5, 0.7, 0.9]
- lipschitz_constant values: [0.5, 1.0, 2.0]
Run 15 iterations for each combination.

使用@引用

在克劳德代码中，使用 @ 引用文件和目录：

______________________________________________________________________

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

{
  "mcpServers": {
    "pepflow-tools": {
      "command": "/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/pepflow_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/CycPepMCP/CycPepMCP/tool-mcps/pepflow_mcp/src/server.py"]
    }
  }
}

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What optimization tools are available?
> Analyze gradient descent for 5 iterations
> Submit accelerated gradient analysis with 15 iterations

______________________________________________________________________

可用工具

快速操作（同步API）

这些工具会立即返回结果（\2分钟）：

作业管理工具

实用工具

______________________________________________________________________

例子

示例1：快速收敛验证

目标： 验证梯度下降的O（1/k）收敛速度

使用脚本：

mamba run -p ./env python scripts/gradient_descent_analysis.py \
  --iterations 8 \
  --proof-steps 2 \
  --skip-plot \
  --output results/quick_verification

使用MCP（克劳德代码）：

Analyze gradient descent convergence for 8 iterations with 2 proof steps. Show me if the O(1/k) theoretical bound is verified.

预期产量：

• 数值收敛值：\[0.166670，0.099995，…\]
• 分析界：L/（4N+2）≈100000000
• 收敛验证：真/假
• 最优函数值级数

示例2：加速梯度法分析

目标： 用theta序列计算分析O（1/k²）收敛性

使用脚本：

mamba run -p ./env python scripts/accelerated_gradient_analysis.py \
  --iterations 5 \
  --proof-steps 3 \
  --output results/agm_analysis

使用MCP（克劳德代码）：

Submit accelerated gradient analysis for 15 iterations and 8 proof steps. Track the job progress and show me the theta sequence when complete.

预期产量：

• Theta序列：\[1.618034，2.193527，2.701588，…\]
• O（1/k²）界：L/（2\*θₙ²）验证
• 收敛图和分析验证

示例3：算法性能比较

目标： 比较用于基准测试的多种优化方法

使用MCP（克劳德代码）：

Compare the performance of these optimization algorithms for 10 iterations each:
1. Gradient descent
2. Heavy ball with momentum 0.5
3. Accelerated gradient method

Show me which achieves the best convergence rate and at which iteration.

预期产量：

• 比较收敛值
• 最佳算法识别
• 每次迭代的性能指标
• 每种方法的收敛速度验证

______________________________________________________________________

演示数据

这 examples/data/ 目录包含算法笔记本和示例：

______________________________________________________________________

配置文件

这 configs/ 目录包含配置模板：

配置示例

{
  "_description": "Gradient descent convergence analysis configuration",
  "_source": "examples/use_case_1_gradient_descent.py",

  "algorithm": {
    "name": "gradient_descent",
    "stepsize": "1/L"
  },
  "analysis": {
    "iterations": 8,
    "proof_steps": 2
  },
  "parameters": {
    "lipschitz_constant": 1.0,
    "initial_radius": 1.0
  },
  "output": {
    "save_plot": true,
    "output_dir": "results/gradient_descent"
  },
  "numerical_settings": {
    "solver": "OSQP",
    "precision": 1e-10
  }
}

______________________________________________________________________

故障排除

环境问题

问题： 未找到环境

# Recreate environment
mamba create -p ./env python=3.10 -y
mamba activate ./env
cd repo/PEPFlow && mamba run -p ../../env pip install -e .
cd ../../ && mamba run -p ./env pip install fastmcp loguru

问题： PEPFlow导入错误

# Verify PEPFlow installation
mamba run -p ./env python -c "import pepflow; print('PEPFlow: OK')"

# If it fails, reinstall
cd repo/PEPFlow
mamba run -p ../../env pip install -e . --force-reinstall

问题： 求解器错误（OSQP、SCS、Clarabel）

# Install mathematical solvers
mamba activate ./env
mamba install -c conda-forge osqp clarabel scs -y

MCP问题

问题： 在Claude代码中找不到服务器

# Check MCP registration
claude mcp list

# Re-add if needed
claude mcp remove pepflow-tools
claude mcp add pepflow-tools -- $(pwd)/env/bin/python $(pwd)/src/server.py

问题： 工具不工作

# Test server directly
mamba run -p ./env python -c "
from src.server import mcp
print(list(mcp.list_tools().keys()))
print('Available tools:', len(list(mcp.list_tools().keys())))
"

问题： 服务器中的导入错误

# Verify all dependencies
mamba run -p ./env python -c "
import pepflow, sympy, numpy, matplotlib
print('All dependencies available')
"

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/

# Check if job manager is working
mamba run -p ./env python -c "
from src.jobs.manager import job_manager
print('Jobs directory:', job_manager.jobs_dir)
"

问题： 任务失败

Use get_job_log with job_id "abc12345" and tail 100 to see error details in the execution logs

问题： 分析失败，存在收敛误差

• 尝试减少迭代或证明步骤
• 检查Lipschitz常数是否合适（尝试L=1.0）
• 验证求解器是否正常工作： mamba run -p ./env python -c "import cvxpy; print(cvxpy.installed_solvers())"

算法特定问题

问题： Theta序列计算失败（AGM）

• 减少验证步骤（尝试2-5）
• 检查数值精度设置
• 验证SymPy是否适用于符号计算

问题： 双变量提取错误

• 这在高迭代次数时很常见
• 脚本包括用于优雅降级的错误处理
• 即使无法提取双变量，结果仍然有效

______________________________________________________________________

发展

运行测试

# Activate environment
mamba activate ./env

# Test basic functionality
mamba run -p ./env python test_simple.py

# Test MCP server startup
mamba run -p ./env python test_server_startup.py

# Test individual scripts
mamba run -p ./env python scripts/gradient_descent_analysis.py --help

正在启动开发服务器

# Run MCP server in development mode
mamba run -p ./env fastmcp dev src/server.py

# Or production mode
mamba run -p ./env python src/server.py

______________________________________________________________________

数学背景

政治公众人物框架

性能估计问题（PEP）通过将分析公式化为半定程序，提供了一种系统的方法来分析优化算法的最坏情况收敛性。

支持的算法

收敛边界

• 梯度下降: f(xₖ) - f\*≤L/（4k+2）·R²
• 加速坡度: f(xₖ) - f\*≤L/（2θₖ²）·R²

其中L是Lipschitz常数，R是初始距离界限。

______________________________________________________________________

许可证

MIT许可证-基于PEPFlow框架

积分

基于 PEPFlow CVX研究小组