MCP JSON Navigator

MCP JSON导航器

一个模型上下文协议（MCP）服务器，为AI助手提供智能JSON导航和搜索功能。 主要设计用于在几秒钟内保存令牌和处理大于10MB的大文件。

需要 文件系统. *注意json应该注意在键中使用“.”*

能力 1. 搜索关键字和值（“电话”、“电子邮件”、“位置”） 1. “使用可选区分大小写的匹配进行精确路径查找” 1. “非常大JSON文件的结构探索 （无需将所有内容加载到模型上下文中）”

______________________________________________________________________

📦 安装

MacOS/Linux

git clone https://github.com/Adsdworld/mcp-json-navigator && cd mcp-json-navigator && npm install && npm run build

Windows（已测试）

git clone https://github.com/Adsdworld/mcp-json-navigator; cd mcp-json-navigator; npm install; npm run build

⚙️ 配置

添加到您的MCP设置文件（例如。， claude_desktop_config.json):

{
  "mcpServers": {
    "json-navigator": {
      "command": "node",
      "args": ["C:\\Users\\YOUR_USERNAME\\mcp-json-navigator\\build\\index.js"]
    }
  }
}

替换 YOUR_USERNAME 以及您实际安装位置的路径。

🔎 Json查询

{ 
  "Request": {
    "limit": 50,
    "query": "phone",
    "filepath": "C:\\Shared\\With\\Claude\\data.json",
    "caseSensitive": false
  },
  "Response": {
  "results": [
    {
      "path": "result[0]",
      "score": 2
    },
    {
      "path": "result[1]",
      "score": 2
    }
  ]
}
}

🛤️ Json-探索

{
  "Request": {
    "filepath": "C:\\Shared\\With\\Claude\\data.json",
    "jsonpath": "result[1]",
    "verbosity": 5
  },
  "Response": {
    "message": "Hello, Brannon! Your order number is: #100",
    "phoneNumber": "(268) 822-7569",
    "phoneVariation": "+90 343 871 10 66",
    "status": "disabled",
    "name": "{object: 3 keys, 49 chars}",
    "username": "Madalyn-Koss",
    "password": "_jRAnwKTcLZwdj6",
    "emails": "[list: 2 items, 54 chars]",
    "location": "{object: 6 keys, 175 chars}",
    "website": "https://sour-debris.com/",
    "domain": "wrong-leaf.org",
    "job": "{object: 5 keys, 123 chars}",
    "creditCard": "{object: 3 keys, 60 chars}",
    "uuid": "476c7b47-0c28-4dc1-b872-7c4256a95675",
    "objectId": "68fe628328b168737793b750"
  }
}

______________________________________________________________________

🎯 这是给谁的？

该工具专为需要高效导航和搜索大型JSON文件的AI助手而设计。

在处理海量JSON结构（数百MB、深度嵌套对象、数千个条目）时，AI模型面临着几个挑战：

• 令牌限制：大型JSON文件无法完全容纳在上下文窗口中
• 演出：解析和搜索大型结构很慢
• 精确度：在复杂的嵌套结构中查找特定数据很困难

MCP JSON Navigator通过以下方式解决了这些问题：

• 提供可调节的详细程度的智能探索
• 使用带有camelCase标记的模糊搜索进行自然查询
• 允许使用JSON路径进行精确导航
• 对结果进行智能分组和评分

✨ 特性

1. 智能JSON探索 (json-explore)

浏览具有可调整细节级别的JSON结构：

// Get an overview (verbosity: 0-1)
{ "users": "list", "config": "object", "version": "string" }

// See structure with counts (verbosity: 2-3)
{ "users": "[list: 150 items]", "config": "{object: 12 keys, 450 chars}" }

// Full expansion for small objects (verbosity: 4-5)
{ "users": [...], "config": {...} }

参数：

• filepath：JSON文件的路径
• jsonpath （可选）：导航到特定路径（例如。， users[0].profile)
• verbosity：0-5（默认值：4）

- 0：仅限钥匙 - 1：带类型的按键 - 2：带计数的按键 - 3：带有计数和字符大小的按键 - 4：小型物体的智能扩展 - 5：原始数据

• listDisplayLimit：阵列中显示的最大项目数（默认值：5）
• objectDisplayLimit：要在对象中显示的最大关键点（默认值：6）
• charDisplayLimit：扩展的最大字符数（默认值：200）

2. 智能搜索 (json-query)

使用模糊匹配和camelCase标记化搜索关键字和值：

// These all find "phoneNumber" and "phoneVariation"
query: "phone"     ✓
query: "number"    ✓
query: "variation" ✓

它是如何工作的：

1. 分词：拆分camelCase、snake_case、kebab case，并生成n-gram
2. 模糊匹配：使用相似性评分查找部分匹配项
3. 加权评分：密钥得分高于值
4. 智能分组：将来自同一JSON分支的相关结果分组

参数：

• filepath：JSON文件的路径
• query：搜索词（支持部分匹配）
• limit：要返回的最大结果（默认值：20，最小值：10）
• caseSensitive：启用精确匹配筛选器（默认值：false）

当 caseSensitive: true，返回额外的 exactMatch 字段中的结果包含精确的查询字符串。

🚀 使用示例

示例1：探索大型JSON文件

// First, get an overview
json-explore({
  filepath: "C:\\Shared\\With\\Claude\\data.json",
  verbosity: 1
})
// → { "users": "list", "products": "list", "config": "object" }

// Then navigate to a specific section
json-explore({
  filepath: "C:\\Shared\\With\\Claude\\data.json",
  jsonpath: "users[0]",
  verbosity: 5
})
// → Full details of the first user

示例2：搜索联系人

// Find all phone-related fields by high scores paths
json-query({
  filepath: "C:\\Shared\\With\\Claude\\contacts.json",
  query: "phone",
  limit: 20
})
// → Results with paths like "contacts[0].phoneNumber", "contacts[1].phoneVariation"

// Returning a list of exact paths found that exactly match + high scores paths
json-query({
  filepath: "C:\\Shared\\With\\Claude\\contacts.json",
  query: "qsbHBJ5sd4HBSDsdjhHBS",
  caseSensitive: true
})

示例3：复杂导航

// Navigate deep into nested structures
json-explore({
  filepath: "api-response.json",
  jsonpath: "result.data.items[3].metadata",
  verbosity: 3
})
// → Full details metadata either an object / list / primitif

🛠️ 技术细节

建筑

• 基于TypeScript：完全打字，可靠性高
• MCP协议：基于模型上下文协议标准构建
• 快速模糊搜索：用途 fast-fuzzy 高效匹配库
• 倒排索引：使用n-gram标记化构建可搜索索引
• 智能分组：按JSON结构对结果进行分组，以获得更好的相关性

搜索算法

1. 分词:

- 规范化文本（camelCase→ 骆驼箱） - 生成3-5个字符的n元语法 - 构建倒排索引：token→ \[带权重的路径\]

1. 查询阶段:

- 标记查询 - 计算模糊相似性得分 - 每条路径累积分数 - 应用键/值权重

1. 结果分组:

- 按结构相似性对路径进行分组 - 按频率×深度得分 - 返回最具代表性的路径

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

您可以自由地：

• ✓ 商业用途
• ✓ 修改
• ✓ 分发
• ✓ 私下使用

只需提及来源： https://github.com/Adsdworld/mcp-json-navigator

🤝 贡献

欢迎投稿！请随时提交问题或拉取请求。

📚 相关项目

• 模型上下文协议
• MCP服务器

🔗 链接

• GitHub: https://github.com/Adsdworld/mcp-json-navigator
• MCP文件: https://modelcontextprotocol.io/

______________________________________________________________________

内置❤️ 用于导航复杂JSON结构的AI助手。