JSON MCP Server

Instructions

Implementation Reference

• src/index.ts:272-323 (handler)

  Core handler function that ingests JSON content via strategy pattern and generates TypeScript schema using quicktype library.

  async function processJsonSchema(input: JsonSchemaInput): Promise<JsonSchemaResult> {
    try {
      // Use strategy pattern to ingest JSON content
      const ingestionResult = await jsonIngestionContext.ingest(input.filePath);
      
      if (!ingestionResult.success) {
        // Map strategy errors to existing error format for backward compatibility
        return {
          success: false,
          error: ingestionResult.error
        };
      }
  
      const jsonContent = ingestionResult.content;
  
      // Calculate file size in bytes
      const fileSizeBytes = new TextEncoder().encode(jsonContent).length;
  
      // Generate schema using quicktype with fixed parameters
      try {
        const result = await quicktypeJSON(
          "typescript", 
          "GeneratedType", 
          jsonContent
        );
        
        return {
          success: true,
          schema: result.lines.join('\n'),
          fileSizeBytes
        };
      } catch (error) {
        return {
          success: false,
          error: {
            type: 'quicktype_error',
            message: 'Failed to generate schema',
            details: error
          }
        };
      }
    } catch (error) {
      return {
        success: false,
        error: {
          type: 'validation_error',
          message: 'Unexpected error during processing',
          details: error
        }
      };
    }
  }

• src/index.ts:19-24 (schema)

  Zod input schema for validating the filePath parameter supporting local files and HTTP/HTTPS URLs.

  const JsonSchemaInputSchema = z.object({
    filePath: z.string().min(1, "File path or HTTP/HTTPS URL is required").refine(
      (val) => val.length > 0 && (val.startsWith('./') || val.startsWith('/') || val.startsWith('http://') || val.startsWith('https://') || !val.includes('/')),
      "Must be a valid file path or HTTP/HTTPS URL"
    )
  });

• src/index.ts:507-561 (registration)

  MCP server tool registration for 'json_schema', including input schema, description, and handler that validates input and calls processJsonSchema.

  server.tool(
      "json_schema",
      "Generate TypeScript schema for a JSON file or remote JSON URL. Provide the file path or HTTP/HTTPS URL as the only parameter.",
      {
          filePath: z.string().describe("JSON file path (local) or HTTP/HTTPS URL to generate schema from")
      },
      async ({ filePath }) => {
          try {
              const validatedInput = JsonSchemaInputSchema.parse({
                  filePath: filePath
              });
              const result = await processJsonSchema(validatedInput);
              
              if (result.success) {
                  // Format file size for display
                  const formatFileSize = (bytes: number): string => {
                      if (bytes < 1024) return `${bytes} bytes`;
                      if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
                      return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
                  };
  
                  const fileSizeInfo = `// File size: ${formatFileSize(result.fileSizeBytes)} (${result.fileSizeBytes} bytes)\n\n`;
                  
                  return {
                      content: [
                          {
                              type: "text",
                              text: fileSizeInfo + result.schema
                          }
                      ]
                  };
              } else {
                  return {
                      content: [
                          {
                              type: "text",
                              text: `Error: ${result.error.message}`
                          }
                      ],
                      isError: true
                  };
              }
          } catch (error) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Validation error: ${error instanceof Error ? error.message : String(error)}`
                      }
                  ],
                  isError: true
              };
          }
      }
  );

• src/index.ts:43-63 (schema)

  Type definitions for input, error, and result of json_schema tool.

  type JsonSchemaInput = z.infer<typeof JsonSchemaInputSchema>;
  type JsonFilterInput = z.infer<typeof JsonFilterInputSchema>;
  type JsonDryRunInput = z.infer<typeof JsonDryRunInputSchema>;
  type Shape = { [key: string]: true | Shape };
  
  // Define error types (extended to support new ingestion strategies and edge cases)
  interface JsonSchemaError {
    readonly type: 'file_not_found' | 'invalid_json' | 'network_error' | 'invalid_url' | 'unsupported_content_type' | 'rate_limit_exceeded' | 'validation_error' | 'authentication_required' | 'server_error' | 'content_too_large' | 'quicktype_error';
    readonly message: string;
    readonly details?: unknown;
  }
  
  // Result type for better type safety
  type JsonSchemaResult = {
    readonly success: true;
    readonly schema: string;
    readonly fileSizeBytes: number;
  } | {
    readonly success: false;
    readonly error: JsonSchemaError;
  };