Fetch Jsonpath MCP

🚀 Fetch JSONPath MCP

Fetch JSONPath MCP 是一個模型上下文協議（MCP）服務器，它提供了使用 JSONPath 模式從 URL 中獲取和提取 JSON 數據的工具。通過精準提取所需數據，可有效減少大語言模型（LLM）的令牌使用量，避免因無關數據導致的幻覺問題。

🚀 快速開始

本項目可幫助你從 URL 中高效提取所需的 JSON 數據。以下是使用前的安裝和開發設置步驟。

✨ 主要特性

• 減少大語言模型令牌使用和幻覺問題：無需獲取整個 JSON 響應，避免浪費令牌，僅提取所需數據。
• 性能優勢顯著：具備令牌高效利用、處理速度快、減少幻覺、節省成本和聚焦關鍵數據等優點。

傳統獲取方式與 JSONPath 提取對比

❌ 傳統獲取方式（浪費資源）：

// API 返回 2000+ 個令牌
{
  "data": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com", 
      "avatar": "https://...",
      "profile": {
        "bio": "Long bio text...",
        "settings": {...},
        "preferences": {...},
        "metadata": {...}
      },
      "posts": [...],
      "followers": [...],
      "created_at": "2023-01-01",
      "updated_at": "2024-01-01"
    },
    // ... 還有 50 多個用戶
  ],
  "pagination": {...},
  "meta": {...}
}

✅ JSONPath 提取方式（高效）：

// 僅 10 個令牌 - 正好是你需要的！
["Alice", "Bob", "Charlie"]

使用模式 data[*].name 可節省 99% 的令牌，並消除因無關數據導致的模型幻覺問題。

📦 安裝指南

大多數 IDE 通用安裝方法

使用 uvx 工具運行服務器。在配置文件中添加以下內容：

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

特定 IDE 安裝方法

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"]
    }
  }
}

💻 使用示例

基礎用法

get-json：使用 JSONPath 模式提取 JSON 數據

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

返回結果：[1, 2]

get-text：從任意 URL 獲取原始文本內容

{
  "name": "get-text",
  "arguments": {
    "url": "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"}}

高級用法

batch-get-json：使用不同的 JSONPath 模式處理多個 URL

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

返回結果：[[1, 2], [10, 20, 30]]

batch-get-text：從多個 URL 獲取文本內容

{
  "name": "batch-get-text",
  "arguments": {
    "urls": ["http://localhost:8080", "http://localhost:8080"]
  }
}

返回結果：["JSON content...", "JSON content..."]

📚 詳細文檔

開發設置

1. 安裝依賴

uv sync

2. 啟動演示服務器（可選）

# 安裝演示服務器依賴
uv add fastapi uvicorn

# 在 8080 端口啟動演示服務器
uv run demo-server

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"}
}

JSONPath 示例

本項目使用 jsonpath-ng 實現 JSONPath。以下是一些 JSONPath 模式示例：

完整的 JSONPath 語法參考，請參閱 jsonpath-ng 文檔。

性能優勢

• 令牌高效利用：僅提取所需數據，而非整個 JSON 響應。
• 處理速度快：較小的負載意味著大語言模型響應更快。
• 減少幻覺：減少無關數據可使輸出更準確。
• 節省成本：更少的令牌使用意味著更低的 API 成本。
• 聚焦關鍵數據：乾淨的數據有助於模型專注於任務。

配置

設置環境變量：

export JSONRPC_MCP_TIMEOUT=30
export JSONRPC_MCP_HEADERS='{"Authorization": "Bearer token"}'
export JSONRPC_MCP_PROXY="http://proxy.example.com:8080"

開發

# 運行測試
pytest

# 檢查代碼質量
ruff check --fix