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