Mcptool Sh

MCP工具文档

概述

MCP工具是一个用于管理模型上下文协议（MCP）服务器的命令行实用程序。它为使用Claude和Cursor等工具运行、配置和集成各种MCP服务器提供了一个统一的界面。

主要特点

核心功能

• 列出可用的MCP服务器和服务器组
• 单独或成组运行MCP服务器
• 显示有关服务器的详细信息
• 为所有服务器生成全面的文档
• JSON格式的输出服务器定义

高级功能

• 克劳德集成：轻松将服务器定义添加到Claude MCP
• 光标集成：将服务器定义添加到Cursor MCP配置中
• .zshrc的自动加载器：通过自动补全功能与您的shell环境集成
• 交互模式：通过用户友好的菜单选择和管理服务器
• 配置向导：设置服务器所需的环境变量
• 改进了错误处理：出现问题时提供更好的反馈
• 增强的帮助系统：每个命令的详细使用信息

安装

1. 将脚本文件克隆或下载到您的首选位置：

   git clone https://github.com/your-username/mcptool.git
   cd mcptool

1. 使主脚本可执行：

   chmod +x mcptool.sh

1. 确保您具有所需的依赖关系：

- jq：JSON处理器（解析服务器配置所需） - dialog：可选，用于交互模式

1. （可选）创建别名以便于访问：

   alias mcpt='/path/to/mcptool.sh'

用法

主脚本(mcptool.sh)作为所有功能的统一指挥中心。

基本命令

MCP Tool v1.2.0 - Manage MCP Servers

Usage: ./bin/mcptool.sh  [target] [options]

Commands:
  list                   List servers and groups
  run  [--bg]    Run a server or group. Groups run in separate terminals.
                         Use --background or --bg to run in detached background mode.
  add      Add server definition to a required backend/file.
                         Target Options (required): --claude | --cursor [--global] | --json  | 
  info  [-v]     Show info for a server or group (use -v for group details)
  json           Output server/group JSON definition
  docs                   Show documentation for all servers
  interactive            Launch interactive TUI menu (requires 'dialog')
  autoloader             Generate shell autocompletion script
  help              Show detailed help for a command

Common Options:
  --servers-file=
  Specify servers file (default: /Users/estiens/code/mcptool/config/servers.json)
  --groups-file=
   Specify groups file (default: /Users/estiens/code/mcptool/config/groups.json)
  -v, --verbose          Show detailed output (used with 'info group')
  --background, --bg     Run server/group in background (used with 'run')

Note: The tool supports both JSON and YAML formats for configuration files

Run './bin/mcptool.sh help ' for more details on a specific command.

常用选项

• -v, --verbose：显示详细的输出（尤其适用于 info 命令）
• --project：使用项目级范围进行Claude/Cursor集成（默认）
• --global：使用全局/用户级范围进行Claude/Cursor集成
• `--json-file=

`：指定自定义JSON文件位置

环境变量

• MCP_CONFIG_FILE：JSON配置文件的替代路径

壳牌与Autoloader的集成

自动加载器功能创建了一个脚本，可以在您的 .zshrc 文件，为MCP服务器命令提供方便的shell函数和选项卡完成。

1. 生成自动加载器文件：

   ./mcptool.sh autoloader

1. 将以下行添加到您的 .zshrc 文件：

   source ~/.mcp_autoloader.zsh

1. 重新加载shell后，您可以使用这些带有制表符的命令：

- mcpt list：列出所有可用的服务器和组 - mcpt run ：运行特定的服务器或组 - mcpt info ：获取有关服务器或组的信息 - mcpt json ：获取服务器或组的JSON定义 - mcpt add --claude|--cursor [--global]|--json |：添加服务器定义 - mcpt docs：生成全面的文档 - mcpt interactive：启动交互模式

交互模式

交互模式为管理MCP服务器提供了一个用户友好的菜单界面。使用以下方式启动它：

./mcptool.sh interactive

菜单允许您：

• 运行服务器
• 获取服务器信息
• 运行服务器组
• 获取组信息
• 查看文档
• 使用“Add”命令添加服务器定义（在交互模式之外）
• 退出应用程序

Claude和Cursor集成

MCP工具使向Claude和Cursor MCP添加服务器定义变得容易：

克劳德集成

# Add a server definition to Claude MCP (project scope)
./mcptool.sh add server_name --claude

# Add a server definition to Claude MCP (global/user scope)
./mcptool.sh add server_name --claude --global

# Add a server definition, overwriting existing Claude config
./mcptool.sh add server_name --claude --overwrite

# Note: Adding entire groups directly is not supported via 'add'. Add servers individually.

光标集成

# Add a server definition to Cursor MCP (project scope - ./.cursor/mcp.json)
./mcptool.sh add server_name --cursor

# Add a server definition to Cursor MCP (global scope - ~/.cursor/mcp.json)
./mcptool.sh add server_name --cursor --global

# Add a server definition, overwriting existing Cursor config
./mcptool.sh add server_name --cursor --overwrite

# Note: Adding entire groups directly is not supported via 'add'. Add servers individually.

添加到JSON/YAML文件

# Add a server definition to a specific JSON file
./mcptool.sh add server_name --json path/to/your/config.json

# Add a server definition, overwriting the target JSON file
./mcptool.sh add server_name --json path/to/your/config.json --overwrite

# Add a server definition to a specific YAML file (or any text file)
./mcptool.sh add server_name path/to/your/config.yaml

# Add a server definition, overwriting the target YAML file
./mcptool.sh add server_name path/to/your/config.yaml --overwrite

配置文件

MCP服务器在JSON配置文件中定义，其结构如下：

{
  "servers": {
    "server_name": {
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      },
      "required_env": ["ENV_VAR1", "ENV_VAR2"],
      "description": "Server description"
    }
  },
  "groups": {
    "group_name": ["server1", "server2"]
  }
}

故障排除

常见问题

1. 未找到JSON文件

- 确保使用指定了正确的路径 --json-file=path/to/file - 检查是否 MCP_CONFIG_FILE 环境变量设置正确 - 默认位置与脚本位于同一目录中： mcp_servers.json

1. 缺少的依赖

- 安装jq： brew install jq （macOS）或 sudo apt-get install -y jq （Ubuntu/Debian） - 安装对话框（用于交互模式）： brew install dialog （macOS）或 sudo apt-get install -y dialog （Ubuntu/Debian）

1. 缺少环境变量

- 某些服务器需要环境变量。检查服务器的文档（通过 mcptool docs 或 mcptool info )对于所需变量。 - 将它们设置在您的环境中或 .env 文件（例如。， .env.mcp)并获取它(source .env.mcp).

1. “add”命令失败

- 确保您提供了一个有效的目标： --claude, --cursor [--global], --json ，或文件名 `. - 对于 --claude：确保Claude CLI已安装并位于PATH中。 - 对于 --cursor` 或文件目标：检查目标目录/文件是否可写。

1. JSON错误无效

- 使用验证JSON文件 jq empty your_file.json - 常见问题包括缺少逗号、多余的逗号或引号不正确的字符串

平台特定问题

• macOS：The sed -i 命令在macOS上的工作方式不同。脚本会自动处理此问题。
• Linux：没有已知的平台特定问题。
• 视窗：不直接支持。考虑使用WSL（Linux的Windows子系统）。

贡献

要将新的MCP服务器添加到库中，请执行以下操作：

1. 编辑JSON配置文件以添加新的服务器定义
2. 使用MCP工具测试服务器
3. 记录服务器的用途、要求和使用情况
4. 如果您正在为主存储库做出贡献，请提交拉取请求

许可证

此工具未经DWTFYouWant许可而提供