在itBuilder中使用MCP

对MCP服务器感到困惑？

MCP（模型上下文协议）服务器充当桥梁，为itBuilder提供对更广泛工具和外部服务（如数据库、API或自定义脚本）的访问。它使用标准通信方法，允许Roo利用这些外部功能。

要深入了解，请查看什么是MCP？。

模型上下文协议（MCP）通过连接到外部工具和服务来扩展itBuilder的功能。本指南涵盖了在itBuilder中使用MCP所需了解的所有内容。

配置MCP服务器

MCP服务器配置可以在两个级别管理：

全局配置：存储在mcp_settings.json文件中，可通过VS Code设置访问（见下文）。这些设置适用于所有工作区，除非被项目级配置覆盖。
项目级配置：在项目根目录的.roo/mcp.json文件中定义。这允许您设置项目特定的服务器，并通过将文件提交到版本控制与团队共享配置。如果文件存在，itBuilder会自动检测并加载此文件。

优先级：如果服务器名称同时存在于全局和项目配置中，项目级配置优先。

编辑MCP设置文件

您可以直接从itBuilder MCP设置视图编辑全局和项目级MCP配置文件：

点击itBuilder窗格顶部导航中的图标。

滚动到MCP设置视图的底部。
点击相应的按钮：
- 编辑全局MCP：打开全局mcp_settings.json文件。
- 编辑项目MCP：打开项目特定的.roo/mcp.json文件。如果此文件不存在，itBuilder将为您创建它。

两个文件都使用JSON格式，包含命名服务器配置的mcpServers对象：

{
  "mcpServers": {
    "server1": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}

itBuilder中MCP服务器配置示例（STDIO传输）

理解传输类型

MCP支持三种传输类型用于服务器通信：用于本地服务器的STDIO、Streamable HTTP（推荐用于新远程服务器）和SSE（用于传统远程服务器）。

STDIO传输

用于在您的机器上运行的本地服务器：

通过标准输入/输出流通信
较低延迟（无网络开销）
更好的安全性（无网络暴露）
更简单的设置（不需要HTTP服务器）
作为您机器上的子进程运行

有关STDIO传输工作原理的深入信息，请参阅STDIO传输。

STDIO配置参数：

command（必需）：要运行的可执行文件（例如，node、python、npx或绝对路径）。
args（可选）：传递给命令的字符串参数数组。您可以使用${env:VARIABLE_NAME}语法引用系统环境变量。
cwd（可选）：启动服务器进程的工作目录。如果省略，默认为第一个工作区文件夹路径或主进程的工作目录。如果服务器脚本依赖相对路径，这很有用。
env（可选）：包含要为服务器进程设置的环境变量的对象。
alwaysAllow（可选）：来自此服务器的工具名称数组，自动批准。
disabled（可选）：设置为true以禁用此服务器配置。

STDIO配置示例：

{
  "mcpServers": {
    "local-server": {
      "command": "node",
      "args": ["server.js"],
      "cwd": "/path/to/project/root", // 可选：指定工作目录
      "env": {
        "API_KEY": "your_api_key"
      },
      "alwaysAllow": ["tool1", "tool2"],
      "disabled": false
    }
  }
}

在参数中使用系统环境变量

您可以使用${env:VARIABLE_NAME}语法在args数组中引用系统级环境变量。这允许您从系统环境传递敏感信息（如API密钥或令牌），而无需在配置中硬编码：

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN=${env:GITHUB_PERSONAL_ACCESS_TOKEN}",
        "ghcr.io/github/github-mcp-server"
      ],
      "alwaysAllow": [
        "get_pull_request"
      ]
    }
  }
}

在此示例中，${env:GITHUB_PERSONAL_ACCESS_TOKEN}将被替换为您系统中GITHUB_PERSONAL_ACCESS_TOKEN环境变量的值。这在以下情况下特别有用：

使用需要通过环境变量的Docker容器
将敏感凭据排除在配置文件之外
在不同环境使用相同配置但使用不同凭据

注意： 环境变量必须存在于您的系统环境中才能工作。您可以通过操作系统的设置或shell配置文件（例如，.bashrc、.zshrc或Windows环境变量）设置系统环境变量。

Streamable HTTP传输

这是通过HTTP/HTTPS访问远程服务器的现代标准，为新的实现提供更多灵活性并替代传统SSE传输。

通过HTTP POST/GET到单个MCP端点进行通信
可选地使用服务器发送事件（SSE）进行流式传输
可以托管在不同的机器上
支持多个客户端连接
需要网络访问
允许集中部署和管理

有关Streamable HTTP传输工作原理的深入信息，请参阅Streamable HTTP传输。

Streamable HTTP配置参数：

type（必需）：必须设置为"streamable-http"。
url（必需）：远程MCP服务器单个端点的完整URL（例如，https://your-server.com/mcp）。
headers（可选）：包含随请求发送的自定义HTTP头的对象（例如，用于身份验证令牌）。
alwaysAllow（可选）：来自此服务器的工具名称数组，自动批准。
disabled（可选）：设置为true以禁用此服务器配置。

Streamable HTTP配置示例：

{
  "mcpServers": {
    "modern-remote-server": {
      "type": "streamable-http",
      "url": "https://your-modern-server.com/api/mcp-endpoint",
      "headers": {
        "X-API-Key": "your-secure-api-key"
      },
      "alwaysAllow": ["newToolA", "newToolB"],
      "disabled": false
    }
  }
}

SSE传输（传统）

用于通过HTTP/HTTPS访问的旧远程服务器。对于新的远程服务器实现，推荐使用Streamable HTTP传输。

通过服务器发送事件协议通信（通常需要单独的端点用于客户端到服务器和服务器到客户端通信）
可以托管在不同的机器上
支持多个客户端连接
需要网络访问
允许集中部署和管理

有关传统SSE传输工作原理的深入信息，请参阅SSE传输（传统）。

SSE（传统）配置参数：

type（可选，但建议为了清晰）：如果为SSE服务器提供url，应设置为"sse"，以区别于Streamable HTTP。如果存在url但省略type，itBuilder可能会尝试推断，但明确声明更安全。
url（必需）：远程MCP服务器的基础URL。对于传统SSE，这通常意味着服务器将派生或期望单独的路径，如/events（用于SSE流）和/message（用于POST请求）。
headers（可选）：包含随请求发送的自定义HTTP头的对象（例如，用于身份验证令牌）。
alwaysAllow（可选）：来自此服务器的工具名称数组，自动批准。
disabled（可选）：设置为true以禁用此服务器配置。

SSE（传统）配置示例：

{
  "mcpServers": {
    "legacy-remote-server": {
      "type": "sse", // 明确定义为SSE
      "url": "https://your-legacy-server-url.com/mcp-base", // 基础URL
      "headers": {
        "Authorization": "Bearer your-legacy-token"
      },
      "alwaysAllow": ["oldToolX"],
      "disabled": false
    }
  }
}

启用或禁用MCP服务器

在此禁用您的MCP服务器将从系统提示中移除所有MCP相关逻辑和定义，减少您的令牌使用量。这将阻止itBuilder连接到任何MCP服务器，并且use_mcp_tool和access_mcp_resource工具将不可用。如果您不打算使用MCP服务器，请勾选此项。默认情况下此选项是开启的。

点击itBuilder窗格顶部导航中的图标
勾选/取消勾选启用MCP服务器

启用或禁用MCP服务器创建

在此禁用MCP服务器创建将仅从系统提示中移除itBuilder用于编写MCP服务器的指令，而不移除与操作它们相关的上下文。这减少了令牌使用量。默认情况下此选项是开启的。

点击itBuilder窗格顶部导航中的图标
勾选/取消勾选启用MCP服务器创建

如何使用Roo创建MCP服务器

如果您需要通过现有MCP服务器无法获得的特定工具或功能，您可以要求itBuilder为您构建一个新的。

先决条件： 确保MCP设置面板中的**启用MCP服务器创建**设置已勾选开启。如果此选项被禁用，Roo将没有构建服务器所需的指令。

如何启动：

提出请求： 明确要求Roo提供新工具或功能。例如：
- "创建一个获取比特币当前价格的MCP工具。"
- "我需要一个通过其API连接到我们公司内部用户数据库的工具。"
- "构建一个与GitHub Gist API交互的MCP服务器。"
Roo的流程（简化）： 一旦您提出请求（并且设置已启用），Roo将：
- 获取服务器创建的内部指令。
- 在默认MCP目录（例如，macOS上的~/Documents/Cline/MCP）中搭建基本服务器项目（通常是TypeScript），除非您另有指定。
- 编写实现请求工具的代码，包括处理必要的API调用。
- 处理密钥： 如果工具需要API密钥或其他凭据，Roo将使用ask_followup_question工具询问您，确保它们作为环境变量为服务器安全配置。
- 配置： 自动将新服务器的配置添加到您的全局mcp_settings.json或项目.roo/mcp.json文件。
- 激活： 尝试连接到新配置的服务器，以便其工具立即可用。
结果： 如果成功，Roo将确认创建，新服务器及其工具将出现在您的MCP服务器列表中，准备使用。

此功能允许您通过让Roo直接从您的请求构建特定集成来定制Roo的功能。要深入了解内部机制，请参阅工具调用机制。

管理单个MCP服务器

每个MCP服务器都有自己的配置面板，您可以在其中修改设置、管理工具并控制其操作。要访问这些设置：

点击itBuilder窗格顶部导航中的图标
在列表中找到您要管理的MCP服务器

删除服务器

按您要删除的MCP服务器旁边的
按确认框上的删除按钮

重启服务器

按您要重启的MCP服务器旁边的按钮

启用或禁用服务器

按MCP服务器旁边的开关来启用/禁用它

网络超时

要设置MCP服务器工具调用后等待响应的最长时间：

点击单个MCP服务器配置框底部的网络超时下拉菜单并更改时间。默认为1分钟，但可以设置在30秒到5分钟之间。

自动批准工具

MCP工具自动批准按工具逐个工作，默认情况下禁用。要配置自动批准：

首先在自动批准操作中启用全局"使用MCP服务器"自动批准选项
在MCP服务器设置中，找到您要自动批准的特定工具
勾选工具名称旁边的始终允许复选框

启用后，itBuilder将自动批准此特定工具而无需提示。请注意，全局"使用MCP服务器"设置优先 - 如果它被禁用，则不会自动批准任何MCP工具。

查找和安装MCP服务器

itBuilder不附带任何预安装的MCP服务器。您需要单独查找和安装它们。

社区仓库： 在GitHub上查看社区维护的MCP服务器列表
询问Roo： 您可以要求itBuilder帮助您查找甚至创建MCP服务器（当"启用MCP服务器创建"启用时）
构建您自己的： 使用SDK创建自定义MCP服务器以使用您自己的工具扩展itBuilder

有关完整SDK文档，请访问MCP GitHub仓库。

在工作流中使用MCP工具

配置MCP服务器后，Roo会自动检测其可用工具和资源。有效利用这些工具涉及理解核心交互步骤，以及Roo如何解释您提供的工具。

核心工作流步骤

您与MCP工具的交互通常遵循以下序列：

1. 启动任务

通过在itBuilder聊天界面中输入您的请求开始。

2. Roo的工具识别

Roo分析您的请求以确定可用的MCP工具是否可以协助。此阶段高度依赖于您的MCP工具定义的质量。

描述的关键作用

Roo的能力：

识别工作的正确工具，
理解如何构建必要参数，以及
避免误解工具的功能，都取决于工具本身及其参数的清晰、简洁和信息丰富的描述。模糊或缺失的信息，特别是参数信息，可能显著阻碍Roo选择或有效使用工具的能力。

例如，"分析我的API性能"的请求可能导致Roo考虑为API端点测试设计的MCP工具。Roo是否成功识别并按照预期使用此工具直接受到其描述质量的影响。

定义MCP工具的最佳实践

为了确保Roo能够有效利用您的MCP工具，在服务器中定义它们时请考虑以下内容：

工具名称： 选择描述性和明确的名称，清楚指示工具的主要功能。
工具描述： 提供工具做什么、其目的以及使用它的任何重要上下文或先决条件的全面摘要。解释使用工具的结果或成果。
参数描述： 这很关键。对于每个参数：
- 清楚说明其目的和期望的数据类型（例如，"用于查找的用户ID"、"要处理的文件路径"、"搜索查询字符串"）。
- 指定任何格式要求、约束或有效值的示例（如果适用）。
- 如果参数是可选的或必需的，请指出（虽然MCP模式通常处理这个，但注释可能很有帮助）。
为AI的清晰性： 就像向另一个开发人员（或AI）解释工具一样编写描述。Roo拥有的上下文越多，它就越能将该工具集成到其问题解决工作流中。如果工具旨在在特定序列中使用或与其他工具结合使用，提及这一点也可能有益。
用自定义指令增强： 除了嵌入在MCP服务器中的描述之外，您还可以通过提供自定义指令进一步指导Roo对特定MCP工具的使用。这允许您定义首选方法、概述涉及多个工具的复杂工作流，或指定何时应优先考虑或避免特定MCP工具。

3. 工具调用

如果Roo在工具描述的指导下识别出合适的工具，它将建议使用它。然后您批准这个（除非为受信任的工具配置了自动批准）。

与MCP服务器最大化协同

通过投入精力制作详细描述并可能用自定义指令增强它们，您显著改善了itBuilder与您的MCP服务器之间的协同。这解锁了它们更可靠和高效任务完成的全部潜力。

故障排除MCP服务器

常见问题和解决方案：

服务器无响应： 检查服务器进程是否正在运行并验证网络连接
权限错误： 确保在您的mcp_settings.json（用于全局设置）或.roo/mcp.json（用于项目设置）中正确配置了API密钥和凭据。
工具不可用： 确认服务器正确实现了工具且未在设置中禁用
性能缓慢： 尝试调整特定MCP服务器的网络超时值

平台特定的MCP配置示例

Windows配置示例

在Windows上设置MCP服务器时，您需要使用Windows命令提示符（cmd）来执行命令。以下是在Windows上配置Puppeteer MCP服务器的示例：

{
  "mcpServers": {
    "puppeteer": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

此Windows特定配置：

使用cmd命令访问Windows命令提示符
使用/c告诉cmd执行命令然后终止
使用npx运行包而不永久安装它
-y标志在安装过程中自动回答"是"到任何提示
运行提供浏览器自动化功能的@modelcontextprotocol/server-puppeteer包

macOS和Linux配置示例

在macOS或Linux上设置MCP服务器时，您可以使用更简单的配置，因为您不需要Windows命令提示符。以下是在macOS或Linux上配置Puppeteer MCP服务器的示例：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-puppeteer"
      ]
    }
  }
}

此配置：

直接使用npx而不需要shell包装器
使用-y标志在安装过程中自动回答"是"到任何提示
运行提供浏览器自动化功能的@modelcontextprotocol/server-puppeteer包

相同的方法可用于Windows上的其他MCP服务器，根据需要调整包名称以用于不同的服务器类型。

运行时版本管理器配置

在使用多种编程语言或运行时版本时，您可能使用版本管理器如asdf或mise（前身为rtx）。这些工具帮助在单个系统上管理多个运行时版本。以下是如何配置MCP服务器以与这些版本管理器一起工作：

mise配置示例

mise是一个快速、现代的运行时版本管理器，可用于指定为MCP服务器使用哪个版本的Node.js、Python或其他运行时：

{
  "mcpServers": {
    "mcp-batchit": {
      "command": "mise",
      "args": [
        "x",
        "--",
        "node",
        "/Users/myself/workspace/mcp-batchit/build/index.js"
      ],
      "disabled": false,
      "alwaysAllow": [
        "search",
        "batch_execute"
      ]
    }
  }
}

此配置：

使用mise命令管理运行时版本
x子命令使用配置的运行时版本执行命令
--分隔mise参数与要运行的命令
使用mise设置中配置的特定版本运行node
指向MCP服务器JavaScript文件
自动允许"search"和"batch_execute"工具

asdf配置示例

asdf是管理多个运行时版本的流行工具。以下是如何配置MCP服务器以使用asdf管理的特定Node.js版本：

{
  "mcpServers": {
    "appsignal": {
      "command": "/Users/myself/.asdf/installs/nodejs/22.2.0/bin/node",
      "args": [
        "/Users/myself/Code/Personal/my-mcp/build/index.js"
      ],
      "env": {
        "ASDF_NODE_VERSION": "22.2.0"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

此配置：

直接引用asdf安装目录中的Node.js可执行文件
设置ASDF_NODE_VERSION环境变量以确保一致的版本使用
指向MCP服务器JavaScript文件

使用版本管理器确保您的MCP服务器使用正确的运行时版本运行，无论系统的默认版本如何，在不同环境中提供一致性并防止版本冲突。

配置MCP服务器​

编辑MCP设置文件​

理解传输类型​

STDIO传输​

在参数中使用系统环境变量​

Streamable HTTP传输​

SSE传输（传统）​

启用或禁用MCP服务器​

启用或禁用MCP服务器创建​

如何使用Roo创建MCP服务器​

管理单个MCP服务器​

删除服务器​

重启服务器​

启用或禁用服务器​

网络超时​

自动批准工具​

查找和安装MCP服务器​

在工作流中使用MCP工具​

核心工作流步骤​

1. 启动任务​

2. Roo的工具识别​

描述的关键作用​

定义MCP工具的最佳实践​

3. 工具调用​

与MCP服务器最大化协同​

故障排除MCP服务器​

平台特定的MCP配置示例​

Windows配置示例​

macOS和Linux配置示例​

运行时版本管理器配置​

mise配置示例​

asdf配置示例​

配置MCP服务器

编辑MCP设置文件

理解传输类型

STDIO传输

在参数中使用系统环境变量

Streamable HTTP传输

SSE传输（传统）

启用或禁用MCP服务器

启用或禁用MCP服务器创建

如何使用Roo创建MCP服务器

管理单个MCP服务器

删除服务器

重启服务器

启用或禁用服务器

网络超时

自动批准工具

查找和安装MCP服务器

在工作流中使用MCP工具

核心工作流步骤

1. 启动任务

2. Roo的工具识别

描述的关键作用

定义MCP工具的最佳实践

3. 工具调用

与MCP服务器最大化协同

故障排除MCP服务器

平台特定的MCP配置示例

Windows配置示例

macOS和Linux配置示例

运行时版本管理器配置

mise配置示例

asdf配置示例