using-heavy-mcps

MCPorter を使ったトークン効率の高い MCP の利用

Sanity のドキュメント全文を含むクエリや、ファイル全体の内容を含む Brain Vault 検索など、大きなペイロードを返す MCP を使う場合は、チャットの外で mcporter 経由で呼び出し、jq で出力を絞り込んで、コンパクトな結果だけをモデルに渡せます。これにより、レスポンス全体をコンテキストに読み込むことで発生する 20～40k トークンの膨張を防げます。

このパターンを使う場面

次のような場合は、mcporter と jq を使います。

• 大きなレスポンス：ドキュメント全体を返す Sanity クエリ、ファイル内容を含む Brain Vault 検索
• クエリの繰り返し：同じデータを複数回必要とし、特定のフィールドだけが必要な場合
• フィールドの絞り込み：MCP が 50 個のフィールドを返すものの、必要なのは 3 個だけの場合
• 連鎖する操作：各操作でコンテキストが膨らむ複数の MCP 呼び出し
• リスト操作：100 件を取得するものの、タイトルと ID だけが必要な場合

次のような場合は、このパターンを使わないでください。

• 慣れていないデータを調べる場合（Cursor から MCP を直接呼び出して、全体の構造を確認します）
• レスポンスがすでに小さい場合（< 1000 トークン）
• 分析にレスポンス全体が必要な場合

基本パターン

基本的なワークフローは次のとおりです。

1. bunx mcporter call を使って、チャットの外で MCP を実行します
2. jq にパイプして、必要なフィールドだけを抽出します
3. コンパクトな結果をチャットに戻します
4. 再利用できるように、1 行のコマンドとして保存します

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'

2 つの方法：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 を使いましょう。mcporter だけでなく、あらゆる JSON 出力で使え、より柔軟だからです。

使用例

このパターンを Sanity と Brain Vault MCP で使う具体例については、EXAMPLES.md を参照してください。

統合パターン

パターン 1：チャットで使う 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：シェルエイリアスとして保存

頻繁に使うクエリを .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 のパターンは再現性とトークン効率のためのものであり、すべての MCP 操作に使うものではありません。

失敗した呼び出しによるトークンの浪費を防ぐ

タイムアウトを設定して、すぐに失敗させます。

# 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 '.'

実際のトークン削減量

変更前（チャットで MCP を直接呼び出す場合）：

• 10 件のプロジェクトをコンテンツ全体とともに取得する Sanity クエリ：約 25,000 トークン
• Brain vault の検索で 5 件のノートを取得：約 15,000 トークン

変更後（mcporter + jq）：

• 同じ Sanity クエリでタイトルと ID のみを取得：約 500 トークン
• 同じ vault 検索でメタデータのみを取得：約 300 トークン

**削減量：**一般的なフィルター済みクエリで 95％以上削減できます。

追加リソース

**mcporter の公式ドキュメント：**Context7 から /steipete/mcporter を参照できます

参考となる主なドキュメント：

• 呼び出し構文と例：mcporter/docs/call-syntax.md
• ツール呼び出しガイド：mcporter/docs/tool-calling.md
• 設定：mcporter/docs/config.md