json_query_search_keys
Search for specific keys within a JSON file without knowing their exact path. Ideal for navigating large JSON data to locate relevant information quickly and efficiently.
Instructions
Search for keys in a JSON file. Use when you do not know the path to a key in a large JSON file, but have some idea what the key is.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Absolute path to the JSON file. | |
| limit | No | Maximum number of results to return (default: 5) | |
| query | Yes | Search term for finding matching keys |
Implementation Reference
- src/jsonUtils.ts:37-65 (handler)Core handler function that implements the logic for searching JSON keys: recursively traverses the JSON structure to collect all key paths, computes string similarity scores with the query, sorts by similarity descending, and returns top results up to the limit.static async searchKeys(query: string, jsonFile: string, limit = 5): Promise<SearchResult[]> { const data = await this.readJsonFile(jsonFile); const keyPaths: { path: string; key: string }[] = []; const collectKeys = (obj: unknown, path = '$'): void => { if (obj && typeof obj === 'object') { if (Array.isArray(obj)) { obj.forEach((item, index) => { collectKeys(item, `${path}[${index.toString()}]`); }); } else { Object.entries(obj).forEach(([key, value]) => { const newPath = path === '$' ? `$.${key}` : `${path}.${key}`; keyPaths.push({ path: newPath, key }); collectKeys(value, newPath); }); } } }; collectKeys(data); const matches = keyPaths.map((item) => ({ path: item.path, similarity: stringSimilarity.compareTwoStrings(query.toLowerCase(), item.key.toLowerCase()), })); return matches.sort((a, b) => b.similarity - a.similarity).slice(0, limit); }
- src/server.ts:63-96 (registration)Registers the 'json_query_search_keys' tool on the MCP server, providing description, input schema with Zod validation, and a thin async handler that resolves the file path, calls the core searchKeys implementation, formats output as JSON text, and handles errors.server.tool( 'json_query_search_keys', 'Search for keys in a JSON file. Use when you do not know the path to a key in a large JSON file, but have some idea what the key is.', { file_path: z.string().describe(PATH_ARG_DESCRIPTION), query: z.string().min(1).describe('Search term for finding matching keys'), limit: z .number() .int() .min(1) .max(100) .optional() .default(5) .describe('Maximum number of results to return (default: 5)'), }, async ({ file_path, query, limit }) => { try { const resolvedPath = path.resolve(file_path); const results = await JsonUtils.searchKeys(query, resolvedPath, limit); return { content: [ { type: 'text', text: JSON.stringify(results, null, 2), }, ], }; } catch (error) { return getErrorResponse(error); } }, );
- src/server.ts:66-77 (schema)Zod schema defining input parameters for the tool: file_path (string), query (non-empty string), limit (optional integer 1-100, default 5).{ file_path: z.string().describe(PATH_ARG_DESCRIPTION), query: z.string().min(1).describe('Search term for finding matching keys'), limit: z .number() .int() .min(1) .max(100) .optional() .default(5) .describe('Maximum number of results to return (default: 5)'), },
- src/types.ts:6-10 (schema)TypeScript interface defining the structure of search results returned by the tool, used by the handler.export interface SearchResult { path: string; similarity: number; value?: unknown; }
- src/jsonUtils.ts:8-19 (helper)Helper utility method to read and parse a JSON file from disk, used by the search functions.private static async readJsonFile(filePath: string): Promise<unknown> { try { const content = await fs.readFile(filePath, 'utf-8'); return JSON.parse(content); } catch (error) { if (error instanceof Error) { throw new Error(`Failed to read or parse JSON file: ${error}`); } else { throw new Error('Failed to read or parse JSON file'); } } }