使用说明

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支持全局和特定于项目的配置，并具有自动发现功能：

优先顺序 （从高到低）：

--配置标志: mcp --config ./custom.json servers list
MCP_CONFIG环境变量: MCP_CONFIG=./custom.json mcp servers list
本地配置: .mcp-cli.json 在当前目录中
家长搜索：在目录树中查找 .mcp-cli.json
全局配置: ~/.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 <path>] [--force] -初始化配置文件
mcp servers list [--names-only] [--full] -列出服务器
mcp servers add <name> --type <stdio|sse|http> -添加服务器
mcp servers remove <name> -删除服务器
mcp servers test <name> -测试连接
mcp servers info <name> -获取详细信息
mcp inspect <name> -获取功能摘要

工具操作

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

资源操作

mcp resources list <server> [--names-only] -列出资源
mcp resources read <server> <uri> -读取资源
mcp resources schema <server> <uri> -获取资源元数据
mcp resources search <server> <pattern> -搜索资源

快速操作

mcp prompts list <server> [--names-only] -列表提示
mcp prompts schema <server> <prompt> -获取提示架构
mcp prompts get <server> <prompt> [--args <json>] -获取提示

发现

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

使用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个工具的多步开发任务

方法	加载代币	使用代币	浪费	质量
预先加载	18000	1650	83%	降级
MCP-CLI	1650	1650	0%	最佳

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

贡献

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

许可证

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

文档

指南

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

例子

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

资源

支持

问题: GitHub问题
讨论: GitHub讨论

内置德诺 |发布到 JSR公司