Pi Mcporter

🧳 皮特·麦克波特

🧠 理念：CLI>MCP

• pi基本上是CLI优先。
• 只要有可用的本地CLI，就更喜欢(gh, git, kubectl, aws等等）。
• 通过以下方式使用MCP mcporter 当它增加明确的价值时（例如：线性、Slack、托管身份验证密集型集成、跨工具工作流）。
• 这个包裹是故意的 薄桥，而不是pi正常的工具驱动工作流程的替代品。

✨ 为什么使用此软件包

• 保持上下文小：一个稳定的 mcporter 工具，而不是暴露许多MCP工具
• 使用MCPorter配置/运行时作为事实来源
• 支持发现(search)，架构帮助(describe)，和执行(call)
• 返回auth/offline/http/stdio失败的有用错误提示

📋 先决条件

你需要 MCPorter 安装并配置了至少一个MCP服务器：

npm install -g mcporter
npx mcporter list          # verify your servers are visible

🚀 安装

pi install npm:pi-mcporter

🚀 快速开始

1. 确认MCPorter看到您的服务器：

npx mcporter list

1. 开始pi：

pi

1. 询问您需要什么——pi会自动选择正确的MCP工具：

• What are my open Linear issues this sprint?
• Catch me up on #engineering in Slack from today.
• Find the onboarding runbook in Notion and summarize the setup steps.

🔍 三个行动

这 mcporter 该工具有三个与自然发现相对应的动作→ 执行工作流程。

search --按关键字查找工具

当您不知道确切的服务器或工具名称时使用。

{ "action": "search", "query": "linear issue", "limit": 5 }

返回带有简短描述的匹配选择器：

linear.create_issue — Create a new issue in a Linear team
linear.list_issues  — List issues matching a filter

describe --获取工具的完整模式

当您知道选择器但需要在调用前查看其必需参数时使用。

{ "action": "describe", "selector": "linear.create_issue" }

返回工具输入的完整JSON模式，包括必填字段和可选字段及其类型。

call --调用工具

一旦你知道选择器及其模式，就可以使用。

{
  "action": "call",
  "selector": "linear.create_issue",
  "args": { "title": "Fix login bug", "teamId": "TEAM-1", "priority": 2 }
}

对于难以表示为嵌套JSON的参数，您可以通过以下方式将其作为JSON字符串传递 argsJson 而不是 args.

典型工作流程

search "linear issue"          →  discover: linear.create_issue
describe linear.create_issue   →  learn required fields: title, teamId
call linear.create_issue       →  execute with those fields

在实践中，pi会自动遵循这种模式。随着 mode: "preload" 代理启动时目录已经很热了，所以pi通常可以跳过 search/describe 然后直接跳到 call.

🧰 工具输入（参考）

工具名称： mcporter

• action: "search" | "describe" | "call"
• selector?: "server.tool" （需要 describe 和 call)
• query?：自由文本查询 search
• limit?：结果限制（默认值20，最大值100）
• args?：的对象参数 call
• argsJson?：JSON对象字符串回退 call
• timeoutMs?：每次呼叫超时覆盖

⚙️ 配置

在中配置扩展 ~/.pi/agent/mcporter.json:

{
  "configPath": "/absolute/path/to/mcporter.json",
  "timeoutMs": 30000,
  "mode": "lazy",
  "mcpServers": {
    "excalidraw": {
      "env": {
        "EXCALIDRAW_API_KEY": "!security find-generic-password -s 'excalidraw-api-key' -w"
      }
    }
  }
}

• MCPORTER_CONFIG=/absolute/path/to/mcporter.json 仍然覆盖 configPath 从设置文件中。
• configPath：可选的显式MCPorter配置路径。如果省略，MCPorter将使用其正常的默认分辨率。
• mcpServers：可选的仅Pi覆盖层，由MCPorter服务器名称键入。目前支持每台服务器 env Pi在运行时注入到匹配的MCP服务器定义中的值。

- mcpServers..env：仅适用于该服务器的环境变量。默认情况下，值是文字；以开头的值 ! 以shell命令执行并使用stdout，与pi的命令支持的secret风格相匹配；值完全匹配 $env:VAR 或 ${VAR} 从当前进程环境读取。

• timeoutMs：可选的默认呼叫超时（毫秒）。工具级别 timeoutMs 仍然会覆盖每次呼叫。
• mode：可选默认MCP工具可见性模式。

- lazy：只有稳定 mcporter 代理工具可见，MCP元数据按需加载 - preload：仍然只暴露 mcporter，但在代理启动之前预加载MCP工具元数据，以便代理可以更频繁地跳过不必要的发现

例如，保持 ~/.mcporter/mcporter.json 无秘密：

{
  "mcpServers": {
    "excalidraw": {
      "baseUrl": "https://api.excalidraw.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${EXCALIDRAW_API_KEY}"
      }
    }
  }
}

然后注射 EXCALIDRAW_API_KEY 从钥匙扣到匹配 mcpServers.excalidraw.env 覆盖 ~/.pi/agent/mcporter.json 如上所示。

传统扩展标志 --mcporter-config 和 --mcporter-timeout-ms 不再支持。使用 ~/.pi/agent/mcporter.json, MCPORTER_CONFIG，每次通话 timeoutMs 相反。

🪄 输出行为

工具输出遵循pi的原生展开/折叠行为：

• 折叠视图显示简洁的摘要
• 展开视图显示完整的渲染输出
• 折叠的调用头可以预览工具参数，但敏感字段（如令牌、密码、API密钥、授权头和Cookie）会被编辑
• 使用圆周率 app.tools.expand 密钥绑定（默认 Ctrl+O)切换扩展

🧯 故障排除

• 未知服务器/工具：run npx mcporter list 和 npx mcporter list 以验证姓名。
• 身份验证问题：run npx mcporter auth .
• 通话缓慢：增加 timeoutMs 在 ~/.pi/agent/mcporter.json 或覆盖 timeoutMs 每次工具调用。
• 未找到配置：set configPath 在 ~/.pi/agent/mcporter.json 或出口 `MCPORTER_CONFIG=

`.

• 截断输出：响应包含一个带有完整输出的临时文件路径。

🧹 卸载

pi remove npm:pi-mcporter

📄 许可证

麻省理工学院