JSON Query MCP

Instructions

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');
      }
    }
  }