json_query
Extract and query JSON data using JSONPath expressions to locate values, arrays, and nested structures within specified directories and file size limits.
Instructions
Query JSON data using JSONPath expressions. Provides powerful search capabilities for selecting data within JSON structures. Supports standard JSONPath syntax for finding values, arrays, and nested structures. Requires maxBytes parameter (default 10KB). The path must be within allowed directories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxBytes | Yes | Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB. | |
| path | Yes | Path to the JSON file to query | |
| query | Yes | JSONPath expression to execute against the JSON data |
Implementation Reference
- src/handlers/json-handlers.ts:81-110 (handler)The main handler function for the 'json_query' tool. It parses arguments using JsonQueryArgsSchema, validates the file path, reads and parses the JSON file, executes a JSONPath query, and returns the result as formatted text.
export async function handleJsonQuery( args: unknown, allowedDirectories: string[], symlinksMap: Map<string, string>, noFollowSymlinks: boolean ) { const parsed = parseArgs(JsonQueryArgsSchema, args, 'json_query'); const validPath = await validatePath(parsed.path, allowedDirectories, symlinksMap, noFollowSymlinks); const jsonData = await readJsonFile(validPath, parsed.maxBytes); try { const result = JSONPath({ path: parsed.query, json: jsonData, wrap: false // Don't wrap single results in an array }); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], }; } catch (error) { if (error instanceof Error) { throw new Error(`JSONPath query failed: ${error.message}`); } throw error; } } - src/schemas/json-operations.ts:4-12 (schema)TypeBox schema definition for JsonQueryArgsSchema and corresponding TypeScript type JsonQueryArgs, defining the input parameters: path (string), query (string), maxBytes (integer).
export const JsonQueryArgsSchema = Type.Object({ path: Type.String({ description: 'Path to the JSON file to query' }), query: Type.String({ description: 'JSONPath expression to execute against the JSON data' }), maxBytes: Type.Integer({ minimum: 1, description: 'Maximum bytes to read from the file. Must be a positive integer. Handler default: 10KB.' }) }); export type JsonQueryArgs = Static<typeof JsonQueryArgsSchema>; - index.ts:279-280 (registration)Registration of the 'json_query' tool handler in the toolHandlers object, mapping the tool name to the handleJsonQuery function with necessary parameters.
json_query: (a: unknown) => handleJsonQuery(a, allowedDirectories, symlinksMap, noFollowSymlinks), - index.ts:387-396 (registration)Generic tool registration loop that adds 'json_query' (included in tools array) to the FastMCP server, using the handler from toolHandlers and schema from toolSchemas.
for (const tool of tools) { const execute = toolHandlers[tool.name as keyof typeof toolHandlers]; const schema = (toolSchemas as Record<string, any>)[tool.name]; server.addTool({ name: tool.name, description: tool.description, parameters: toZodParameters(schema as any) as any, execute: async (a) => execute(a) as any, }); } - index.ts:326-326 (registration)Inclusion of 'json_query' in the allTools array with name and description, determining if it's enabled based on permissions.
{ name: "json_query", description: "Query JSON" },