MCP CLI 架构解析构建企业级模型上下文协议命令行工具【免费下载链接】mcp-cli项目地址: https://gitcode.com/gh_mirrors/mc/mcp-cliMCP CLI 是一个基于 Model Context ProtocolMCP构建的企业级命令行界面工具专为与大型语言模型进行高效、安全的交互而设计。该项目通过集成 CHUK-MCP 协议库实现了与多种 LLM 提供商的无缝通信支持工具调用、会话管理和多种操作模式。作为现代 AI 应用开发的关键基础设施MCP CLI 解决了传统 LLM 集成中工具发现、协议兼容性和执行安全性的核心痛点。技术概览与架构设计核心架构原则与设计哲学MCP CLI 遵循严格的架构设计原则确保系统的可维护性和扩展性。项目采用Pydantic Native设计理念所有公共 API 的输入输出都基于 Pydantic 模型而非原始字典提供编译时验证和清晰的字段文档。系统采用Async Native架构所有执行 I/O 的公共 API 均为异步设计避免阻塞事件循环支持高并发工具调用。项目的核心模块分离遵循Core/UI Separation原则核心模块chat/, config/, tools/, model_management/仅使用 logging 进行日志记录而 UI 模块display/, interactive/, commands/可以引用终端 UI 组件。这种分离使得核心逻辑可在无终端环境下进行单元测试同时保持 UI 的独立演进。分层架构与协议驱动MCP CLI 采用分层架构设计从底层到上层依次为协议层基于 CHUK-MCP 协议库实现标准化通信工具管理层支持自动发现、协议适配和生产级执行会话管理层提供对话上下文管理和虚拟内存系统命令系统层统一命令接口支持 CLI、聊天和交互模式UI 展示层终端界面和浏览器仪表板系统采用Protocol-Based Interfaces设计模式使用运行时检查协议而非 ABC 继承实现松耦合的组件边界。这种设计使得测试无需模拟整个类层次结构只需实现实际调用的方法即可。核心功能深度解析多模式操作与统一命令系统MCP CLI 提供三种主要操作模式共享统一的命令实现聊天模式提供自然的对话界面支持流式响应和自动工具调用。系统默认使用 Ollama 的 gpt-oss 推理模型无需 API 密钥即可本地运行。聊天模式支持推理模型可见性用户可以观察 AI 的思考过程这在调试复杂任务时尤为有用。交互模式为直接服务器操作提供命令驱动的 shell 接口适合系统管理员和开发者进行精细控制。该模式支持完整的工具管理和服务器配置功能。命令模式提供类 Unix 的接口适用于脚本自动化和管道集成。开发者可以将 MCP CLI 集成到现有工作流中实现批处理和自动化任务。虚拟内存系统与上下文管理MCP CLI 引入实验性的AI 虚拟内存系统通过--vm标志启用。该系统采用操作系统风格的分页机制管理对话上下文Memory Context Management ├── Page Table Structure │ ├── Working Set: 当前活动页面 │ ├── Eviction Policy: LRU 淘汰策略 │ └── TLB Statistics: 转换后备缓冲器统计 ├── Token Budget Control │ ├── --vm-budget: 控制对话事件令牌预算 │ ├── System Prompt: 不受限制的顶层预算 │ └── Early Eviction: 强制早期淘汰和页面创建 └── Multimodal Support ├── Image Pages: 多块内容返回文本 图像URL └── Page Export: 支持本地文件导出虚拟内存系统支持三种操作模式passive运行时管理默认、relaxedVM 感知对话和strict模型驱动的分页工具。通过/memory命令用户可以可视化 VM 状态、页面表、工作集利用率和淘汰指标。执行计划与自动化编排MCP CLI 集成chuk-ai-planner实现基于图的执行计划系统。当启用--plan-tools标志时LLM 可以自主创建和执行多步骤计划Plan Execution Flow ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Plan Creation │───▶│ DAG Execution │───▶│ Variable Binding│ │ (LLM-based) │ │ (Parallel) │ │ Resolution │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Tool Call Graph │ │ Topological Sort│ │ Template String │ │ Generation │ │ (Kahns BFS) │ │ Interpolation │ └─────────────────┘ └─────────────────┘ └─────────────────┘执行计划系统支持并行批处理执行、变量解析${var}、${var.field}、检查点和恢复、防护集成以及 DAG 可视化。计划以 JSON 格式持久化存储在~/.mcp-cli/plans/目录中支持中断后恢复执行。MCP Apps 与交互式 UI 系统MCP CLI 实现SEP-1865规范支持 MCP 服务器提供交互式 HTML UI。当工具包含_meta.ui注解时系统会自动启动本地 Web 服务器并在浏览器中打开应用Browser Security Architecture ┌─────────────────┐ ┌──────────────────┐ ┌──────────────┐ │ Host Page (JS) │──WS──│ AppBridge │──MCP──│ Tool Server │ │ ┌─────────────┐ │ │ (bridge.py) │ │ │ │ │ App iframe │ │ └──────────────────┘ └──────────────┘ │ │ (sandboxed) │ │ │ │ └─────────────┘ │ ┌──────────────────┐ │ postMessage ↕ │ │ AppHostServer │ └─────────────────┘ │ (host.py) │ └──────────────────┘安全模型包括 iframe 沙箱allow-scripts allow-forms allow-same-origin allow-popups allow-popups-to-escape-sandbox、XSS 预防、CSP 域清理和 URL 方案验证。系统实现消息队列、指数退避重连和延迟工具结果交付确保会话可靠性。部署与配置指南系统架构部署策略MCP CLI 支持多种部署模式从单机开发环境到企业级生产部署本地开发部署使用 Ollama 作为默认推理引擎无需外部 API 密钥。系统通过 llama.cpp 集成自动发现和重用 Ollama 下载的模型实现 1.53 倍的速度提升311 vs 204 tokens/sec。企业云部署支持 OpenAI、Anthropic、Azure OpenAI、Google Gemini、Groq 等云提供商通过安全令牌管理系统集成企业身份验证。系统支持 HashiCorp Vault 等企业密钥管理系统。混合架构部署允许同时连接本地和远程 MCP 服务器通过统一的工具管理层进行协议适配和执行协调。安全配置与令牌管理MCP CLI 实现多层安全机制秘密重定向所有日志输出自动重定向 Bearer 令牌、API 密钥、OAuth 令牌和 Authorization 头部结构化文件日志可选--log-file标志启用轮转 JSON 日志文件10MB3个备份令牌存储后端支持 macOS Keychain、Windows Credential Manager、Linux Secret Service、加密文件和 HashiCorp Vault线程安全 OAuth使用asyncio.Lock和写时复制头部变异的并发 OAuth 流序列化系统支持${TOKEN:namespace:name}语法在配置文件中进行安全令牌替换确保敏感信息不硬编码在配置中。服务器健康监控MCP CLI 实现全面的服务器健康监控系统健康检查/health命令提供服务器状态诊断故障时健康检查工具执行失败时自动触发诊断可选后台轮询--health-interval参数控制健康检查频率每服务器超时服务器配置支持tool_timeout和init_timeout覆盖集成开发实践工具开发与协议适配MCP CLI 的工具系统基于CHUK Tool Processor v0.22提供生产级执行能力# 工具执行中间件架构 Tool Execution Pipeline ├── Pre-execution │ ├── 工具名称清理提供商兼容性 │ ├── 参数验证JSON Schema 验证 │ └── 权限检查基于作用域 ├── Execution Strategies │ ├── 进程内执行快速 │ ├── 隔离子进程安全 │ └── 远程 MCP 执行分布式 ├── Middleware Layers │ ├── 重试与指数退避 │ ├── 断路器模式 │ └── 速率限制通过 CTP └── Post-execution ├── 结果格式化 ├── 值绑定提取 └── 历史记录系统支持O(1) 工具查找取代 O(n) 线性扫描通过索引工具名称实现快速发现。每个提供商的 LLM 工具元数据被缓存并在工具集更改时自动失效。多模态附件系统MCP CLI 实现完整的多模态附件系统支持图像、文本/代码和音频文件Attachment Processing Pipeline ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ File Staging │───▶│ Format Detection│───▶│ Content Analysis│ │ (/attach cmd) │ │ (Magic Bytes) │ │ (LLM Vision) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Inline Refs │ │ Auto-detection │ │ Dashboard │ │ (file:path) │ │ (Image URLs) │ │ Rendering │ └─────────────────┘ └─────────────────┘ └─────────────────┘系统支持 25 文本/代码扩展格式包括 PNG、JPEG、GIF、WebP、HEIC图像和 MP3、WAV音频。仪表板渲染包括图像缩略图、可扩展文本预览和音频播放器。实时浏览器仪表板通过--dashboard标志MCP CLI 启动实时浏览器仪表板提供多窗格监控界面代理终端实时对话视图支持消息气泡、流式令牌和附件渲染活动流工具调用/结果对、推理步骤和用户附件事件计划查看器可视化执行计划进度和 DAG 渲染工具注册表浏览发现的工具从浏览器触发执行配置面板查看和切换提供商、模型和系统提示仪表板支持浏览器文件上传、拖放和剪贴板粘贴通过 WebSocket 实现实时双向通信。性能优化与监控内存管理与优化策略MCP CLI 实现多层内存优化策略工具结果截断大型工具结果自动截断为 100,000 字符约 25K 令牌保留头部和尾部内容旧推理内容剥离仅保留最近的推理内容避免历史推理重复发送对话历史滑动窗口默认保留最后 200 条消息超出时自动总结和压缩无限上下文模式可配置的令牌阈值和每段最大轮次利用 SessionManager 的内置上下文打包系统实现脏标志再生模式昂贵的计算状态系统提示、工具列表使用脏标志避免不必要的重新计算。系统提示生成仅在工具集更改时触发而不是每轮对话。执行性能优化MCP CLI 采用多种执行优化策略并发工具执行多个工具可以同时运行通过适当的协调保持对话顺序工具批处理超时并行批处理中的单个工具挂起不会阻塞整个批次缓存 LLM 工具元数据每个提供商的工具元数据被缓存减少重复发现开销启动进度指示初始化期间显示实时进度消息性能指标包括响应时间、词/秒和执行统计通过/usage命令别名/tokens、/cost提供每轮和累计的 API 令牌使用跟踪。生产强化特性MCP CLI 包含企业级生产强化特性结构化错误处理自定义异常层次结构CommandError、InvalidParameterError、CommandExecutionError携带上下文信息边界验证在系统边界CLI 参数、API 响应、配置文件验证输入核心内部信任类型系统运输恢复检测故障 → 尝试恢复 → 记录结果 → 如果恢复失败返回结构化错误狭窄异常处理程序捕获特定异常APIError、TimeoutError、ValueError避免广泛的except Exception系统实现全面的测试套件包含 4,300 测试分支覆盖率达到 60% 最低阈值确保代码质量和可靠性。社区生态与扩展插件系统与自定义集成MCP CLI 设计支持模块化扩展开发者可以通过以下方式集成自定义功能自定义 MCP 服务器实现 MCP 协议规范的工具服务器提供商适配器通过chuk_llm库集成新的 LLM 提供商命令扩展实现UnifiedCommand基类添加新的 CLI 命令UI 主题创建自定义主题文件扩展显示系统系统支持自定义 OpenAI 兼容提供商允许集成 LocalAI、自定义代理等第三方服务# 添加自定义提供商跨会话持久化 mcp-cli provider add localai http://localhost:8080/v1 gpt-4 gpt-3.5-turbo # 运行时提供商仅限会话 mcp-cli --provider temp-ai --api-base https://api.temp.com/v1 --api-key test-key开发工作流与贡献指南项目遵循严格的代码质量标准和架构原则代码规范所有代码必须通过make checkruff lint ruff format mypy pytest测试覆盖率新代码要求 90% 文件覆盖率项目最低 60% 分支覆盖率架构审查15 条架构原则在 PR 中强制执行文档要求所有公共 API 需要完整的类型注解和文档字符串开发工作流包括核心/UI 分离、协议驱动接口、显式依赖注入和无魔法字符串比较等最佳实践。项目维护完整的路线图文档涵盖已完成层级1-6和计划层级7-12跟踪、内存作用域、技能、调度、多代理。企业级集成模式MCP CLI 支持多种企业集成场景CI/CD 流水线集成通过命令模式实现自动化测试和质量检查数据流水线处理集成 SQLite、文件系统和自定义数据处理工具监控和可观测性结构化日志输出和健康检查端点多租户部署通过令牌管理和作用域隔离支持团队协作系统支持会话持久性每 10 轮自动保存对话会话支持手动保存/加载。对话可以导出为 Markdown 或 JSON 格式包含元数据和令牌使用信息。MCP CLI 作为现代 AI 应用开发的基础设施通过标准化协议、生产级工具执行和可扩展架构为开发者提供了构建下一代 AI 应用的强大平台。其模块化设计和严格的质量标准使其成为企业级 AI 集成的理想选择。【免费下载链接】mcp-cli项目地址: https://gitcode.com/gh_mirrors/mc/mcp-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考