Fetch Jsonpath Mcp

Fetch JSONPath MCP

URL から JSON データやウェブコンテンツを取得するツールを提供する Model Context Protocol（MCP）サーバーです。インテリジェントなコンテンツ抽出、複数の HTTP メソッド、信頼性の高いウェブスクレイピングを実現するブラウザーのようなヘッダーが特長です。

🎯 これを使う理由

LLM のトークン使用量とハルシネーションを削減 — JSON レスポンス全体を取得してトークンを無駄にする代わりに、必要なデータだけを抽出できます。

従来の取得方法と JSONPath による抽出

❌ 従来の取得方法（非効率）：

// API returns 2000+ tokens
{
  "data": [
    {
      "id": 1,
      "name": "Alice",
      "email": "[email protected]", 
      "avatar": "https://...",
      "profile": {
        "bio": "Long bio text...",
        "settings": {...},
        "preferences": {...},
        "metadata": {...}
      },
      "posts": [...],
      "followers": [...],
      "created_at": "2023-01-01",
      "updated_at": "2024-01-01"
    },
    // ... 50 more users
  ],
  "pagination": {...},
  "meta": {...}
}

✅ JSONPath による抽出（効率的）：

// Only 10 tokens - exactly what you need!
["Alice", "Bob", "Charlie"]

パターン data[*].name を使うと、トークンを 99% 節約でき、無関係なデータに起因するモデルのハルシネーションをなくせます。

インストール

ほとんどの IDE では、uvx ツールを使ってサーバーを実行します。

{
  "mcpServers": {
    "fetch-jsonpath-mcp": {
      "command": "uvx",
      "args": [
        "fetch-jsonpath-mcp"
      ]
    }
  }
}

claude mcp add fetch-jsonpath-mcp -- uvx fetch-jsonpath-mcp

{
  "mcpServers": {
    "fetch-jsonpath-mcp": {
      "command": "uvx",
      "args": ["fetch-jsonpath-mcp"]
    }
  }
}

{
  "mcpServers": {
    "fetch-jsonpath-mcp": {
      "command": "uvx",
      "args": ["fetch-jsonpath-mcp"]
    }
  }
}

"mcp": {
  "servers": {
    "fetch-jsonpath-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fetch-jsonpath-mcp"]
    }
  }
}

開発環境のセットアップ

1. 依存関係をインストールする

# Installs the project plus dev tools (pytest, ruff) and demo server deps
uv sync

2. デモサーバーを起動する（任意）

# Start demo server on port 8080
uv run demo/demo_server.py

3. MCP サーバーを実行する

uv run fetch-jsonpath-mcp

デモサーバーのデータ

http://localhost:8080 のデモサーバーは次のデータを返します。

{
  "foo": [{"baz": 1, "qux": "a"}, {"baz": 2, "qux": "b"}],
  "bar": {
    "items": [10, 20, 30], 
    "config": {"enabled": true, "name": "example"}
  },
  "metadata": {"version": "1.0.0"}
}

利用可能なツール

fetch-json

すべての HTTP メソッドに対応し、JSONPath パターンを使って JSON データを抽出します。

{
  "name": "fetch-json",
  "arguments": {
    "url": "http://localhost:8080",
    "pattern": "foo[*].baz",
    "method": "GET"
  }
}

戻り値：[1, 2]

パラメーター：

• url（必須）：対象 URL
• pattern（任意）：データ抽出に使う JSONPath パターン
• method（任意）：HTTP メソッド（GET、POST、PUT、DELETE など）— デフォルト：「GET」
• data（任意）：POST/PUT リクエストのリクエストボディ
• headers（任意）：追加の HTTP ヘッダー

fetch-text

インテリジェントなテキスト抽出機能を使ってウェブコンテンツを取得します。読みやすさを高めるため、デフォルトで Markdown 形式になります。

{
  "name": "fetch-text",
  "arguments": {
    "url": "http://localhost:8080",
    "output_format": "clean_text"
  }
}

戻り値：JSON データを読みやすいテキスト形式で表したもの

出力形式：

• "markdown"（デフォルト）：HTML を読みやすい Markdown 形式に変換します
• "clean_text"：HTML タグを取り除いたプレーンテキスト
• "raw_html"：元の HTML コンテンツ

パラメーター：

• url（必須）：対象 URL
• method（任意）：HTTP メソッド — デフォルト：「GET」
• data（任意）：POST/PUT リクエストのリクエストボディ
• headers（任意）：追加の HTTP ヘッダー
• output_format（任意）：出力形式 — デフォルト：「markdown」

batch-fetch-json

異なる JSONPath パターンを使って複数の URL を並行して処理します。

{
  "name": "batch-fetch-json",
  "arguments": {
    "requests": [
      {"url": "http://localhost:8080", "pattern": "foo[*].baz"},
      {"url": "http://localhost:8080", "pattern": "bar.items[*]"}
    ]
  }
}

戻り値：[{"url": "http://localhost:8080", "pattern": "foo[*].baz", "success": true, "content": [1, 2]}, {"url": "http://localhost:8080", "pattern": "bar.items[*]", "success": true, "content": [10, 20, 30]}]

リクエストオブジェクトのパラメーター：

• url（必須）：対象 URL
• pattern（任意）：JSONPath パターン
• method（任意）：HTTP メソッド — デフォルト：「GET」
• data（任意）：リクエストボディ
• headers（任意）：追加の HTTP ヘッダー

batch-fetch-text

インテリジェントなテキスト抽出機能を使って複数の URL からコンテンツを取得します。

{
  "name": "batch-fetch-text",
  "arguments": {
    "requests": [
      "http://localhost:8080",
      {"url": "http://localhost:8080", "output_format": "raw_html"}
    ],
    "output_format": "markdown"
  }
}

戻り値：[{"url": "http://localhost:8080", "success": true, "content": "# Demo Server Data\n\n..."}, {"url": "http://localhost:8080", "success": true, "content": "{\"foo\": [{\"baz\": 1, \"qux\": \"a\"}, {\"baz\": 2, \"qux\": \"b\"}]..."}]

対応内容：

• URL 文字列のみ
• カスタムメソッドとヘッダーを指定した完全なリクエストオブジェクト
• 同一バッチ内での入力形式の混在

JSONPath の例

このプロジェクトでは、JSONPath の実装に jsonpath-ng を使用しています。

JSONPath の構文について詳しくは、jsonpath-ng のドキュメントをご覧ください。

🚀 パフォーマンス上のメリット

• トークン効率：JSON レスポンス全体ではなく、必要なデータだけを抽出します
• 処理の高速化：ペイロードが小さいほど、LLM の応答が速くなります
• ハルシネーションの低減：無関係なデータが少ないほど、出力の精度が高まります
• コスト削減：トークン数が少ないほど、API コストが低くなります
• より的確な処理：データを整理することで、モデルがタスクに集中しやすくなります
• スマートヘッダー：デフォルトのブラウザーヘッダーによってブロックを防ぎ、アクセス性を向上させます
• Markdown 変換：構造を保持した、読みやすく整理された形式です

設定

環境変数を設定して動作をカスタマイズします：

# Request timeout in seconds (default: 10.0)
export JSONRPC_MCP_TIMEOUT=30

# SSL verification (default: true)
export JSONRPC_MCP_VERIFY=false

# Follow redirects (default: true)
export JSONRPC_MCP_FOLLOW_REDIRECTS=true

# Custom headers (will be merged with default browser headers)
export JSONRPC_MCP_HEADERS='{"Authorization": "Bearer token"}'

# HTTP proxy configuration
export JSONRPC_MCP_PROXY="http://proxy.example.com:8080"

デフォルトのブラウザーヘッダー：ブロックを防ぐため、サーバーは自動的に実際のブラウザーを模したヘッダーを追加します：

• User-Agent：Chrome ブラウザーのシミュレーション
• Accept：標準的なブラウザーのコンテンツタイプ
• Accept-Language、Accept-Encoding：ブラウザーのデフォルト設定
• セキュリティヘッダー：最新のブラウザー向けの Sec-Fetch-* ヘッダー

JSONRPC_MCP_HEADERS のカスタムヘッダーは、競合する場合にデフォルト設定を上書きします。

開発

# Run tests
uv run pytest

# Check code quality
uv run ruff check --fix

# Build and test locally
uv build

リリース

リリースは Trusted Publishing を通じて PyPI に公開されます。API トークンは不要です。pyproject.toml の version を更新してから、一致するタグをプッシュします：

git tag v1.2.0 && git push origin v1.2.0

.github/workflows/release.yml は、タグがプロジェクトのバージョンと一致することを確認し、lint とテストを実行して、配布パッケージをビルドし、PyPI に公開した後、成果物を添付して GitHub リリースを作成します。

v1.1.0 の新機能

• ✨ 複数の HTTP メソッドに対応：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS
• 🔄 ツール名の変更：get-json → fetch-json、get-text → fetch-text
• 📄 Markdown 変換：markdownify によるデフォルトの HTML から Markdown への変換
• 🌐 スマートブラウザーヘッダー：ブラウザーを自動的に模したヘッダー
• 🎛️ 形式の制御：テキストコンテンツ向けの 3 種類の出力形式（markdown、clean_text、raw_html）
• 🚀 バッチ処理の強化：バッチ操作で異なるメソッドに対応