MCP CLI Bridge

MCP CLI网桥

模型上下文协议服务器的渐进式披露CLI

一种跨平台的命令行工具，使AI助手能够通过shell访问与模型上下文协议（MCP）服务器进行交互，解决了LLM工具架构中上下文污染的根本问题。

 

为什么这很重要

传统MCP集成负载 全部 预先定义工具，用不相关的信息污染LLM的上下文：

• 令牌块：100+个工具可以消耗20-50K代币
• 注意力下降：变形金刚不能真正忽视无关的背景
• 质量下降：模型性能会因不必要的信息而降低

解决方案：渐进式披露

MCP CLI实现 延迟加载 工具模式：

# Traditional approach: Load everything (35,000 tokens)
❌ Load all 125 tools from 6 servers upfront

# MCP CLI approach: Load only what's needed (350 tokens)
✅ mcp discover "read a file"           # ~300 tokens (intelligent search)
✅ mcp tools schema filesystem read_file   # ~200 tokens (just-in-time)
✅ mcp tools exec filesystem read_file --args '{"path": "README.md"}'

# OR: Step-by-step discovery
✅ mcp servers list --names-only        # ~50 tokens
✅ mcp tools list filesystem --names-only  # ~100 tokens
✅ mcp tools schema filesystem read_file   # ~200 tokens

结果：上下文污染减少99%，推理质量明显提高。

特性

• 渐进呈现：默认为最小输出，仅在需要时升级
• 交叉平台的：适用于Windows、macOS和Linux
• AI平台不可知：适用于Claude、ChatGPT、GitHub Copilot或任何自定义代理
• 多个传输：支持stdio、SSE和HTTP MCP服务器
• JSON输出：AI助手的一致、可解析的响应
• 上下文感知：在所有回复中包括象征性估计
• 用户友好错误：自我纠正建议

快速开始

安装

Deno（推荐）:

deno install -g -A -n mcp jsr:@cosmic/mcp-cli

npm:

npx jsr:@cosmic/mcp-cli

独立二进制文件: 下载自 发布

基本用法

# Initialize MCP configuration
mcp servers init                    # Create global config at ~/.mcp-cli/config.json
mcp servers init --local            # Create local config at ./.mcp-cli.json
mcp servers init --path ./my-config.json  # Create config at custom path

# Add a server
mcp servers add filesystem --type stdio \
  --command npx \
  --args "-y" "@modelcontextprotocol/server-filesystem" "/path/to/allowed/directory"

# List servers (minimal)
mcp servers list --names-only

# List tools (minimal - default)
mcp tools list filesystem --names-only

# Get specific tool schema (just-in-time)
mcp tools schema filesystem read_file

# Execute a tool
mcp tools exec filesystem read_file --args '{"path": "README.md"}'

# Intelligent discovery (recommended for AI agents)
mcp discover                        # List all servers with capabilities
mcp discover "read and write files" # Search + recommendations + suggested batch

# Search across all servers
mcp search "file operations"

渐进式披露工作流程

CLI实现了三层披露模式：

1.仅名称（最小上下文）

# Get server names (~50 tokens)
mcp servers list --names-only
# ["filesystem", "github", "slack"]

# Get tool names (~100-200 tokens)
mcp tools list github --names-only
# ["create_issue", "get_issue", "update_issue", ...]

2.简要说明（中等语境）

# Get tool descriptions (~500-1000 tokens)
mcp tools list github --brief
# [{"name": "create_issue", "description": "Create a new GitHub issue"}, ...]

3.完整模式（高上下文-仅显式）

# Load complete schema when about to use (~200-500 tokens per tool)
mcp tools schema github create_issue
# {"name": "create_issue", "inputSchema": {...}}

配置

配置文件发现

MCP CLI支持全局和特定于项目的配置，并具有自动发现功能：

优先顺序 （从高到低）：

1. --配置标志: mcp --config ./custom.json servers list
2. MCP_CONFIG环境变量: MCP_CONFIG=./custom.json mcp servers list
3. 本地配置: .mcp-cli.json 在当前目录中
4. 家长搜索：在目录树中查找 .mcp-cli.json
5. 全局配置: ~/.mcp-cli/config.json （或平台特定位置）

默认全局配置位置:

• 视窗: %USERPROFILE%\.mcp-cli\config.json
• macOS/Linux: ~/.mcp-cli/config.json
• Linux（XDG）: $XDG_CONFIG_HOME/mcp-cli/config.json

初始化

使用默认设置创建新的配置文件：

# Create global config
mcp servers init

# Create local project config
mcp servers init --local

# Create config at custom path
mcp servers init --path ./configs/mcp.json

# Overwrite existing config
mcp servers init --force

配置示例

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "enabled": true
    },
    "github": {
      "type": "sse",
      "url": "http://localhost:3000/sse",
      "apiKey": "${GITHUB_TOKEN}",
      "enabled": true
    }
  },
  "preferences": {
    "defaultTimeout": 30000,
    "cacheSchemas": true,
    "cacheTTL": 300
  }
}

支持环境变量 ${VAR_NAME} 语法。

用例

个人工具的全局配置:

mcp servers init
mcp servers add my-tool --type stdio --command my-global-tool

项目特定配置 （致力于git）：

cd my-project
mcp servers init --local
mcp servers add project-db --type stdio --command ./scripts/db-tool.sh
git add .mcp-cli.json

临时配置覆盖:

MCP_CONFIG=./test-config.json mcp tools list test-server

命令

服务器管理

• `mcp servers init [--local] [--path

] [--force]` -初始化配置文件

• mcp servers list [--names-only] [--full] -列出服务器
• mcp servers add --type -添加服务器
• mcp servers remove -删除服务器
• mcp servers test -测试连接
• mcp servers info -获取详细信息
• mcp inspect -获取功能摘要

工具操作

• mcp tools list [--names-only] [--brief] [--full] -列出工具
• mcp tools schema -获取工具架构
• mcp tools exec --args -执行工具
• mcp tools batch --operations [--transactional] -按顺序执行多个工具
• mcp tools search -搜索工具

资源操作

• mcp resources list [--names-only] -列出资源
• mcp resources read -读取资源
• mcp resources schema -获取资源元数据
• `mcp resources search

` -搜索资源

快速操作

• mcp prompts list [--names-only] -列表提示
• `mcp prompts schema

` -获取提示架构

• `mcp prompts get

[--args ]` -获取提示

发现

• mcp discover [query] - 统一发现 -列出服务器或使用智能推荐进行搜索
• mcp search [--detailed] -在所有服务器上搜索
• mcp recommend -获取工具建议

使用AI助手

克劳德（通过bash_tool）

# Recommended: Use discover command for intelligent tool finding
discovery = bash_tool('mcp discover "read and write files"')
# Returns: servers, matches, suggested_batch

# Option 1: Execute suggested batch (if available)
if discovery.suggested_batch:
    result = bash_tool(f'mcp tools batch {server} --operations \'{operations}\'')

# Option 2: Step-by-step discovery
servers = bash_tool('mcp servers list --names-only')
tools = bash_tool('mcp tools list filesystem --names-only')
schema = bash_tool('mcp tools schema filesystem read_file')
result = bash_tool('mcp tools exec filesystem read_file --args \'{"path": "file.txt"}\'')

ChatGPT（代码解释器）

import subprocess
import json

result = subprocess.run(
    ['mcp', 'servers', 'list', '--names-only'],
    capture_output=True,
    text=True
)
servers = json.loads(result.stdout)

海关代理

const { exec } = require("child_process");
const { promisify } = require("util");
const execAsync = promisify(exec);

const { stdout } = await execAsync("mcp servers list --names-only");
const result = JSON.parse(stdout);

响应格式

所有命令输出JSON：

成功:

{
  "success": true,
  "data": { ... },
  "metadata": {
    "server": "filesystem",
    "timestamp": "2025-11-08T12:00:00Z",
    "executionTime": 145,
    "tokensEstimate": 250,
    "resultSize": "small"
  }
}

错误:

{
  "success": false,
  "error": {
    "code": "TOOL_NOT_FOUND",
    "message": "Tool 'invalid' not found on server 'filesystem'",
    "suggestion": "Try: mcp tools list filesystem --names-only",
    "similar": ["read_file", "write_file"]
  }
}

发展

# Run from source
deno task dev servers list --names-only

# Run tests
deno task test

# Lint and format
deno task lint
deno task fmt

# Type check
deno task check

# Compile binaries
deno task compile

建筑

CLI遵循干净的架构原则：

src/
├── types/          # TypeScript type definitions
├── utils/          # Cross-platform utilities
├── config/         # Configuration management
├── client/         # MCP client implementations
├── commands/       # Command handlers
├── cli.ts          # CLI entry point
└── mod.ts          # Module exports

关键设计决策：

• 默认情况下为最小值：所有列表操作默认为 --names-only
• 显式模式加载：使用 schema 需要时发出命令
• 仅JSON输出：stdout保留用于JSON，日志转到stderr
• 跨平台优先：使用Deno的std库进行路径处理
• 连接池：跨命令重用连接

令牌效率比较

场景：来自3台服务器的6个工具的多步开发任务

储蓄：工具相关环境污染减少91%

贡献

欢迎投稿！请看 贡献.md 作为指导方针。

许可证

MIT许可证-请参阅 许可证 了解详情。

文档

指南

• 代理集成指南 -AI代理与MCP CLI集成的完整指南
• 工作流程指南 -多步骤工作流模式和示例
• API 参考 -带示例的综合指挥参考

例子

• 代理示例 -TypeScript、Python和Bash代理实现
• 工作流示例 -实用的多步骤工作流脚本

资源

• MCP规范
• MCP TypeScript SDK
• 实施总结
• MCP CLI桥接规范

支持

• 问题:
• 讨论:

______________________________________________________________________

内置 德诺 |发布到 JSR公司