STARWARCLOUD STARWAR.AI
返回市场
获取-jsonpath-mcp

获取-jsonpath-mcp

作者：ackness2 星标更新：2025-08-21
安装使用来源：spider==github.com

项目介绍

Fetch JSONPath MCP

PyPI 下载量 简体中文

一个提供从URL获取JSON数据和网页内容工具的Model Context Protocol (MCP)服务器。具有智能内容提取、多种HTTP方法以及类似浏览器的头部信息，以实现可靠的网络抓取。

🎯 为什么使用这个？

减少LLM令牌使用及幻觉 - 不需要获取整个JSON响应并浪费令牌，只需提取所需的数据。

传统获取与JSONPath提取对比

❌ 传统获取（浪费）：

// API返回2000多个令牌
{
  "data": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com", 
      "avatar": "https://...",
      "profile": {
        "bio": "长简介文本...",
        "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"
      ]
    }
  }
}
<details> <summary><b>在Claude Code中安装</b></summary> 
claude mcp add fetch-jsonpath-mcp -- uvx fetch-jsonpath-mcp
</details> <details> <summary><b>在Cursor中安装</b></summary> 
{
  "mcpServers": {
    "fetch-jsonpath-mcp": {
      "command": "uvx",
      "args": ["fetch-jsonpath-mcp"]
    }
  }
}
</details> <details> <summary><b>在Windsurf中安装</b></summary>

添加到你的Windsurf MCP配置文件中。更多信息参见Windsurf MCP文档。

Windsurf本地服务器连接

{
  "mcpServers": {
    "fetch-jsonpath-mcp": {
      "command": "uvx",
      "args": ["fetch-jsonpath-mcp"]
    }
  }
}
</details> <details> <summary><b>在VS Code中安装</b></summary> 
"mcp": {
  "servers": {
    "fetch-jsonpath-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fetch-jsonpath-mcp"]
    }
  }
}
</details>

开发环境设置

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

可用工具

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": "# 示例服务器数据\n\n..."}, {"url": "http://localhost:8080", "success": true, "content": "{\"foo\": [{\"baz\": 1, \"qux\": \"a\"}, {\"baz\": 2, \"qux\": \"b\"}]..."}]

支持：

  • 简单的URL字符串
  • 带有自定义方法和头部的完整请求对象
  • 同一批次中的混合输入类型

JSONPath示例

此项目使用jsonpath-ng实现JSONPath。

模式结果描述
foo[*].baz[1, 2]获取所有baz值
bar.items[*][10, 20, 30]获取所有items
metadata.version["1.0.0"]获取版本

完整的JSONPath语法参考，请参阅jsonpath-ng文档。

🚀 性能优势

  • 令牌效率：仅提取所需数据，而非整个JSON响应
  • 更快处理：较小的有效负载 = 更快的LLM响应
  • 减少幻觉：较少的无关数据 = 更准确的输出
  • 成本节约：更少的令牌 = 较低的API成本
  • 更好聚焦：干净的数据帮助模型保持任务专注
  • 智能头部：默认浏览器头部防止被阻止并提高访问
  • Markdown转换：干净、易读的格式保留结构

配置

设置环境变量来自定义行为：

# 请求超时时间（秒，默认：10.0）
export JSONRPC_MCP_TIMEOUT=30

# SSL验证（默认：true）
export JSONRPC_MCP_VERIFY=false

# 跟随重定向（默认：true）
export JSONRPC_MCP_FOLLOW_REDIRECTS=true

# 自定义头部（将与默认浏览器头部合并）
export JSONRPC_MCP_HEADERS='{"Authorization": "Bearer token"}'

# HTTP代理配置
export JSONRPC_MCP_PROXY="http://proxy.example.com:8080"

默认浏览器头部：服务器自动包含模拟真实浏览器的头部，以防止被阻止：

  • User-Agent：Chrome浏览器模拟
  • Accept：标准浏览器内容类型
  • Accept-Language, Accept-Encoding：浏览器默认
  • 安全头部：现代浏览器的Sec-Fetch-*头部

JSONRPC_MCP_HEADERS中的自定义头部在冲突时会覆盖默认值。

开发

# 运行测试
pytest

# 检查代码质量
ruff check --fix

# 本地构建和测试
uv build

v1.1.0 新特性

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