JSON Query MCP

Instructions

Implementation Reference

• src/server.ts:35-60 (registration)

  Registers the 'json_query_jsonpath' tool using McpServer.tool, including description, input schema with Zod, and inline async handler.

  server.tool(
    'json_query_jsonpath',
    'Query a JSON file using JSONPath. Use to get values precisely from large JSON files.',
    {
      file_path: z.string().describe(PATH_ARG_DESCRIPTION),
      jsonpath: z.string().min(1).describe('JSONPath expression to evaluate'),
    },
    async ({ file_path, jsonpath }) => {
      try {
        const resolvedPath = path.resolve(file_path);
  
        const results = await JsonUtils.queryByJsonPath(jsonpath, resolvedPath);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(results, null, 2),
            },
          ],
        };
      } catch (error) {
        return getErrorResponse(error);
      }
    },
  );

• src/server.ts:42-59 (handler)

  The tool handler function that resolves the file path, delegates to JsonUtils.queryByJsonPath, formats the result as MCP content, and handles errors.

  async ({ file_path, jsonpath }) => {
    try {
      const resolvedPath = path.resolve(file_path);
  
      const results = await JsonUtils.queryByJsonPath(jsonpath, resolvedPath);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(results, null, 2),
          },
        ],
      };
    } catch (error) {
      return getErrorResponse(error);
    }
  },

• src/jsonUtils.ts:21-35 (helper)

  Core helper method that reads the JSON file, applies JSONPath query using jsonpath-plus library, and returns array of path-value results.

  static async queryByJsonPath(path: string, jsonFile: string): Promise<JsonPathResult[]> {
    const data = await this.readJsonFile(jsonFile);
  
    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
    const results = JSONPath({
      path,
      json: data as object,
      resultType: 'all',
    }) as { path: string; value: unknown }[];
  
    return results.map((result) => ({
      path: result.path,
      value: result.value,
    }));
  }

• src/server.ts:39-41 (schema)

  Zod schema defining input parameters: file_path (string) and jsonpath (non-empty string).

    file_path: z.string().describe(PATH_ARG_DESCRIPTION),
    jsonpath: z.string().min(1).describe('JSONPath expression to evaluate'),
  },

• src/types.ts:1-4 (schema)

  TypeScript interface defining the output structure for JSONPath query results.

  export interface JsonPathResult {
    path: string;
    value: unknown;
  }