MCP Agent CLI

MCP Agent CLI 交互系统

基于 mcp-agent 框架的 AI 代理交互系统，支持流式输出、多种工作流模式和智能上下文管理

✨ 特性

• 🚀 零依赖安装 - npm install 一键安装，自动配置 Python 环境
• 🔄 流式输出 - 实时渲染 AI 响应，支持行缓冲
• 🛠️ 动态工具 - 自动从 MCP 服务器获取工具描述，无需手动维护
• 🎯 多工作流 - 支持 basic、orchestrator、parallel、router 四种模式
• 💬 CLI 界面 - 基于 Rich 的美观命令行交互
• 🧠 智能上下文 - 自动压缩对话历史，防止上下文溢出
• 🔌 动态配置 - 支持用户自定义 MCP 服务器，无需修改源码

📦 安装

前置要求

• Node.js >= 18.0（用于 MCP 服务器）

注意：Python 3.14+ 环境会在首次安装时自动配置

方式 1: 本地 npm 安装（推荐）

项目不发布到 npm registry，需要从本地 tgz 文件安装：

# 1. 克隆仓库
git clone https://github.com/WeiLaiR/mcp-agent-CLI.git
cd mcp-agent-CLI

# 2. 一键打包（自动下载 uv 并构建）
build\package.cmd

# 3. 本地全局安装
npm install -g ./mcp-agent-cli-0.1.0.tgz

# 4. 配置 LLM
set MCP_LLM_BASE_URL=your_base_url
set MCP_LLM_MODEL=your_model
set MCP_LLM_API_KEY=your_api_key

# 5. 运行
mcp-cli

安装过程自动完成：

• ✅ 检查 Node.js 环境
• ✅ 使用内置 uv 创建 Python 虚拟环境
• ✅ 自动下载 Python 3.14
• ✅ 自动安装所有 Python 依赖

全局配置位置（npm 安装后）：

• Windows: %APPDATA%\mcp-agent-cli\
• Linux/Mac: ~/.local/share/mcp-agent-cli/

方式 2: 从源码运行（开发环境）

# 克隆仓库
git clone https://github.com/WeiLaiR/mcp-agent-CLI.git
cd mcp-agent-CLI

# 使用 uv 安装依赖
uv sync

# 运行程序
.venv\Scripts\python src\mcp_demo.py

⚙️ 配置

LLM 配置

系统支持三种配置方式（按优先级从高到低）：

方式一：环境变量（推荐）

# Windows
set MCP_LLM_BASE_URL=your_base_url
set MCP_LLM_MODEL=your_model
set MCP_LLM_API_KEY=your_api_key

# 或使用 mcp-agent 标准的环境变量
set OPENAI_BASE_URL=your_base_url
set OPENAI_DEFAULT_MODEL=your_model
set OPENAI_API_KEY=your_api_key

# Linux/Mac
export MCP_LLM_BASE_URL=your_base_url
export MCP_LLM_MODEL=your_model
export MCP_LLM_API_KEY=your_api_key

环境变量优先级: MCP_LLM_* > OPENAI_*

方式二：配置文件

mcp_agent.config.yaml:

llm:
  base_url: your_base_url
  model: your_model

mcp_agent.secrets.yaml:

llm:
  api_key: "your_api_key"

工具返回长度限制

为防止工具返回内容过长导致上下文溢出，系统会自动截断过长的返回结果。

配置方式 (通过环境变量):

# Windows
set MCP_MAX_TOOL_RESULT_LENGTH=20000  # 默认 20000 字符

# Linux/Mac
export MCP_MAX_TOOL_RESULT_LENGTH=20000

建议值:

上下文管理

系统实现了智能上下文管理，自动压缩对话历史以防止上下文溢出。

配置项 (通过环境变量):

# Windows
set MCP_MAX_CONTEXT_TOKENS=150000          # 触发压缩的阈值（默认 150000）
set MCP_TOOL_COMPRESSION_THRESHOLD=500        # 工具消息压缩阈值（默认 500）
set MCP_CONTEXT_RETENTION_COUNT=2            # 保留最近N次工具返回（默认 2）

# Linux/Mac
export MCP_MAX_CONTEXT_TOKENS=150000
export MCP_TOOL_COMPRESSION_THRESHOLD=500
export MCP_CONTEXT_RETENTION_COUNT=2

上下文管理策略:

1. 新对话时: 自动清理工具调用/返回消息，只保留问答内容
2. 工具调用过多时: 压缩过长的工具参数和较早的工具返回
3. 使用 LLM 压缩: 保留关键信息，省略冗余细节

MCP 服务器

系统已预配置以下 MCP 服务器：

🚀 使用

启动程序

本地 npm 安装时：

mcp-cli

从源码运行时：

.venv\Scripts\python src\mcp_demo.py

交互命令

工作流模式

Agent 类型：

• assistant: 通用助手，处理日常对话
• researcher: 研究助理，专注于信息收集和搜索
• analyst: 数据分析师，专注于深度分析和推理
• file_operator: 文件操作员，专注于文件系统操作

📁 项目结构

mcp-agent-CLI/
├── bin/                          # npm 启动脚本
│   ├── mcp-cli                   # Unix/Linux/macOS 启动脚本
│   └── mcp-cli.cmd               # Windows 启动脚本（使用 uv）
├── build/                        # 构建脚本
│   ├── package.cmd               # 一键打包脚本
│   └── version.json              # 版本管理
├── scripts/                      # npm 钩子脚本
│   ├── postinstall.js            # 安装后检查 + Python 环境初始化
│   ├── preuninstall.js           # 卸载前清理
│   └── uv-bootstrap.js           # uv 引导脚本
├── runtime/                      # 运行时文件（打包时生成）
│   └── uv.exe                    # uv 可执行文件（约 20MB）
├── src/                          # 源代码目录
│   ├── __init__.py
│   ├── cli.py                    # CLI 交互界面（动态工具描述）
│   ├── config.py                 # 配置管理模块（支持全局配置）
│   ├── context_manager.py        # 上下文管理器（Token 压缩）
│   ├── mcp_demo.py               # 主程序
│   ├── streaming_llm.py          # 流式 LLM 实现
│   └── workflows.py              # 工作流管理
├── docs/                         # 文档目录
│   ├── CODE_REVIEW_OPTIMIZATION.md  # 代码审查与优化建议
│   └── REFACTOR_SUMMARY.md          # 重构总结
├── mcp_agent.config.yaml         # MCP 配置
├── mcp_agent.user.config.yaml    # 用户自定义配置模板
├── mcp_agent.secrets.yaml.example # 密钥配置模板
├── package.json                  # npm 包配置
├── pyproject.toml                # Python 项目配置（包含所有依赖）
├── uv.lock                       # 依赖锁文件
├── AGENTS.md                     # Agent 文档
├── CLAUDE.md                     # Claude Code 项目指南
└── README.md                     # 项目说明（本文件）

全局配置目录

npm 全局安装后，用户配置存放在：

该目录包含：

• venv/ - 全局共享的 Python 虚拟环境
• mcp_agent.user.config.yaml - 用户自定义配置
• mcp_agent.secrets.yaml - API 密钥配置

🔧 自定义配置

添加新的 MCP 服务器

方式一：编辑用户配置文件（推荐，无需重新安装）

编辑全局配置目录中的 mcp_agent.user.config.yaml：

# Windows: %APPDATA%\mcp-agent-cli\mcp_agent.user.config.yaml
# Linux/Mac: ~/.local/share/mcp-agent-cli/mcp_agent.user.config.yaml

mcp:
  servers:
    github:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-github"]

    brave-search:
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-brave-search"]

重启 mcp-cli 即可生效，工具描述会自动获取。

配置优先级

环境变量 > mcp_agent.user.config.yaml > mcp_agent.config.yaml > mcp_agent.secrets.yaml > 默认值

例如：

• 环境变量设置了 MCP_LLM_MODEL=gpt-4
• 配置文件设置了 model=gpt-4o-mini
• 最终使用 gpt-4（环境变量优先）

💡 核心功能详解

1. 动态工具描述获取

系统自动从 MCP 服务器获取工具列表和描述，无需手动维护映射表。

智能生成规则：

工具名称/描述 → 匹配关键词 → 选择 Emoji + 颜色 → 生成显示名称
     ↓
  优先级：默认映射 > 智能生成 > 降级方案

示例：

• read_file → 📄 读取文件 (blue)
• github_create_issue → 📁 create_issue (cyan)
• 中文描述 → 使用描述前15字符

优势：

2. 智能上下文管理

ContextManager 提供智能的上下文管理功能：

3. 流式输出

基于 Rich 的流式输出渲染，支持：

• 行缓冲 - 逐行显示响应
• 工具调用可视化 - Panel + Emoji 样式
• Markdown 渲染 - 支持代码高亮
• 彩色输出 - 丰富的颜色主题

🔄 更新与卸载

本地 npm 安装

# 更新（需要重新打包和安装）
git pull
build\package.cmd
npm uninstall -g mcp-agent-cli
npm install -g ./mcp-agent-cli-0.1.0.tgz

# 卸载
npm uninstall -g mcp-agent-cli

# 清理全局配置（可选）
# Windows
rmdir /s /q "%APPDATA%\mcp-agent-cli"

# Linux/Mac
rm -rf ~/.local/share/mcp-agent-cli

从源码运行

# 更新
git pull
uv sync

# 或
.venv\Scripts\pip install --upgrade mcp-agent[openai] rich pyyaml

🔍 故障排除

常见问题

1. ModuleNotFoundError: No module named 'mcp_agent'

- 确保虚拟环境已激活 - 运行 uv sync 安装依赖

1. MCP 服务器连接失败

- 检查 Node.js 是否已安装 - 确认服务器命令路径正确

1. LLM API 调用失败

- 检查 MCP_LLM_BASE_URL 是否可访问 - 确认 MCP_LLM_API_KEY 已正确设置 - 使用 /status 命令查看当前配置

1. 配置未生效

- 检查环境变量是否设置正确 - 确认 YAML 文件格式正确 - 检查 mcp_agent.secrets.yaml 是否存在

1. 上下文压缩频繁触发

- 调整 MCP_MAX_CONTEXT_TOKENS 增加阈值 - 检查 MCP_CONTEXT_RETENTION_COUNT 设置 - 确认对话是否包含大量工具调用

1. 工具返回被截断

- 调整 MCP_MAX_TOOL_RESULT_LENGTH 增加限制 - 模型会在需要时再次调用工具获取剩余内容

📄 许可

MIT License

🔗 相关链接

• mcp-agent - MCP 框架
• Model Context Protocol - 通信协议
• MCP 服务器列表 - 官方服务器集合