using-heavy-mcps

通过 MCPorter 实现高效的 Token 使用

处理返回大量内容的 MCP 时（例如包含完整文档内容的 Sanity 查询，或包含完整文件内容的 Brain 知识库搜索），可以在聊天之外通过 mcporter 执行调用，用 jq 精简输出，然后只将精简后的结果提供给模型。这样可以避免将完整响应加载到上下文时造成的 20–40k Token 膨胀。

何时使用此模式

以下情况适合使用 mcporter + jq：

• 响应内容较大：Sanity 查询返回完整文档，Brain 知识库搜索返回文件内容
• 重复查询：需要多次获取相同数据，但只关心特定字段
• 筛选字段：MCP 返回 50 个字段，但你只需要 3 个
• 链式操作：需要执行多个 MCP 调用，每个调用都会让上下文膨胀
• 列表操作：获取 100 个项目，但只需要标题和 ID

以下情况不适合使用此模式：

• 探索不熟悉的数据（让 Cursor 直接调用 MCP，以查看完整结构）
• 响应本来就很小（< 1000 个 Token）
• 需要完整响应进行分析

核心模式

基本工作流：

1. 通过 bunx mcporter call 在聊天之外运行 MCP
2. 通过管道传给 jq，只提取所需字段
3. 将精简后的结果提供给聊天
4. 保存为单行命令以便重复使用

bunx mcporter call 'MCP-Name.tool_name(param: "value")' | jq 'filter'

其他语法：

# Shorthand (infers 'call' command)
bunx mcporter 'MCP-Name.tool_name(param: "value")' | jq 'filter'

# Structured JSON output (useful for error handling)
bunx mcporter call 'MCP-Name.tool_name(param: "value")' --output json | jq 'filter'

两种方法：jq 与 CallResult 助手方法

mcporter 响应包含内置助手方法，可在简单提取时替代 jq。根据需求选择：

选项 A：内置 CallResult 助手方法（更简单）

mcporter 返回的结果封装在 CallResult 对象中，并提供助手方法：

# Extract plain text only (strips all metadata/formatting)
bunx mcporter call 'Brain.vault(action: "search", query: "portfolio")' | node -e "console.log(JSON.parse(require('fs').readFileSync(0)).result.text())"

# Get markdown format
# Similar node one-liner but calling .markdown()

# Get parsed JSON
# Similar but calling .json()

**适用情况：**简单的文本提取、需要 Markdown，或需要完整 JSON 对象。

**限制：**处理复杂筛选和转换时，不如 jq 灵活。

选项 B：使用 jq 筛选（功能更强）

jq 是命令行 JSON 筛选器。可以把它看作“用于 JSON 的 grep”。

基本模式：

# Get specific fields from each item in array
jq '[.[] | {id: ._id, title: .title}]'

# Limit to first 5 results
jq '.results[:5]'

# Extract nested field
jq '.results[] | .frontmatter.description'

# Combine: first 3 items, specific fields
jq '.results[:3] | [.[] | {path: .path, desc: .frontmatter.description}]'

# Filter by condition
jq '[.[] | select(.status == "published")]'

**适用情况：**精确选择字段、转换数据结构、按条件筛选，以及组合多个操作。

**建议：**从 jq 开始，因为它更灵活，适用于任何 JSON 输出，而不仅仅是 mcporter 的输出。

使用示例

有关将此模式用于 Sanity 和 Brain Vault MCP 的具体示例，请参阅 EXAMPLES.md。

集成模式

模式 1：在聊天中使用单行命令

在对话过程中需要精简数据时，运行命令并粘贴筛选后的输出：

User: "Can you review my portfolio projects? Here's the data:"
<paste result of mcporter + jq command>

模式 2：嵌入其他 Cursor 规则

将 mcporter 命令添加到需要特定数据的规则中：

## Portfolio Context

When discussing portfolio work, use this to fetch current project list:

<command>
bunx mcporter call 'Sanity Developer.query_documents(
  resource: {projectId: "xyz", dataset: "production"},
  query: "*[_type == \"project\"]"
)' | jq '[.[] | {title: .title, role: .role}]'
</command>

模式 3：保存为 shell 别名

对于常用查询，将其添加到 .zshrc 中：

alias portfolio-list='bunx mcporter call '"'"'Sanity Developer.query_documents(
  resource: {projectId: "xyz", dataset: "production"},
  query: "*[_type == \"project\"]"
)'"'"' | jq "[.[] | {title: .title, slug: .slug.current}]"'

然后只需运行：portfolio-list

何时直接使用 Cursor 的 MCP 调用

以下情况可让 Cursor 直接调用 MCP：

• 探索数据：你还不知道响应结构
• 响应较小：数据本来就很精简
• 交互式筛选：你想通过迭代逐步明确查找内容
• 一次性问题：不值得花时间进行设置

mcporter 模式旨在提高可重复性和 Token 使用效率，并非适用于每次 MCP 交互。

避免失败调用浪费 Token

设置超时，快速失败：

# Don't wait forever for a hung MCP call
bunx mcporter call 'Brain.vault(action: "search", query: "test")' --timeout 10000

默认超时时间为 30 秒。对于较慢的操作，请延长超时时间；对于快速检查，请缩短超时时间。

执行耗时较长的查询前检查身份验证：

# Verify authentication status
bunx mcporter config get "Sanity Developer"

# If auth is required, do it once
bunx mcporter auth "Sanity Developer"

这样可以避免身份验证失败时将庞大的错误消息加载到上下文中。

使用 --output json 以便通过程序处理错误：

bunx mcporter call 'Brain.vault(action: "search", query: "test")' --output json

结构化封装便于检测失败，而无需将完整错误跟踪加载到上下文中。

调试技巧

检查可用的 MCP：

bunx mcporter list

查看工具签名和架构：

bunx mcporter list Brain --schema
bunx mcporter list "Sanity Developer" --schema

先不使用 jq 进行测试：

bunx mcporter call 'Brain.vault(action: "search", query: "test")'

查看结构后，再添加 jq 筛选。

格式化 jq 输出，提高可读性：

... | jq '.'
# vs compact:
... | jq -c '.'

实际场景中的 Token 节省

之前（在聊天中直接调用 MCP）：

• 查询 10 个项目的 Sanity 内容，包含完整内容：约 25,000 个 Token
• Brain 知识库搜索返回 5 条笔记：约 15,000 个 Token

之后（mcporter + jq）：

• 相同的 Sanity 查询，仅返回标题/ID：约 500 个 Token
• 相同的知识库搜索，仅返回元数据：约 300 个 Token

节省： 对于典型的筛选查询，Token 用量减少 95% 以上。

其他资源

mcporter 官方文档： 可通过 Context7 在 /steipete/mcporter 获取

参考文档：

• 调用语法和示例：mcporter/docs/call-syntax.md
• 工具调用指南：mcporter/docs/tool-calling.md
• 配置：mcporter/docs/config.md