Fetch Jsonpath Mcp

Fetch JSONPath MCP

一个 Model Context Protocol（MCP）服务，提供用于从 URL 获取 JSON 数据和网页内容的工具。具备智能内容提取、支持多种 HTTP 方法，以及模拟浏览器的请求头，可实现可靠的网页抓取。

🎯 为什么要使用？

减少大模型的 Token 用量和幻觉——与其获取完整的 JSON 响应并浪费 Token，不如只提取所需数据。

传统获取方式与 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% 的 Token，并消除模型因无关数据而产生的幻觉。

安装

对于大多数 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

使用 JSONPath 模式提取 JSON 数据，并支持所有 HTTP 方法。

{
  "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-ng 实现 JSONPath。

如需查看完整的 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 release。

v1.1.0 新特性

• ✨ 多方法 HTTP 支持：GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS
• 🔄 工具重命名：get-json → fetch-json，get-text → fetch-text
• 📄 Markdown 转换：默认使用 markdownify 将 HTML 转换为 Markdown
• 🌐 智能浏览器标头：自动添加模拟浏览器的标头
• 🎛️ 格式控制：文本内容支持三种输出格式（markdown、clean_text、raw_html）
• 🚀 增强的批处理：支持在批量操作中使用不同的方法