o ik @sddlZddlmZmZmZmZmZddlmZm Z m Z m Z m Z m Z mZmZddlmZddlm Zddlm Zddlm Zddlm Zdd lm Zdd lmZdd lmZdd lmZmZmZdd lmZddlm Z ee!Z"edZ#edZ$e%e&efZ' dTde(de&de)de&e(BfddZ*de%de&de%e&e&ffddZ+Gddde Z,Gddde Z-Gdd d e Z.Gd!d"d"e Z/gd#Z0ed$eeZ1ed%eeZ2ed&e eZ3ed'e eZ4ed(e eZ5ed)eeZ6ed*e eZ7ed+e eZ8d,e%e&efde(e/fd-d.Z9Gd/d0d0ee1e3e2e4e5e6e7e8fZ:d1e'dBde'dBfd2d3Z;d1e'dBdefd4d5Z  dVd;e&de-dBde&f d?d@Z? dWdAe%e&efdBe&dBde%e&effdCdDZ@d1e%e&efde%e&effdEdFZAd1e%e&efddfdGdHZBd1e%e&efeBde%e&efeBfdIdJZCdKe/de%e&effdLdMZDd1e%e&efe(eBde%e&efe(eBfdNdOZE  dVd8s$z)format_array_parameter..,css|]}t|VqdSr%)r')r,vr.r.r/r09s:.rrzFailed to format complex array z parameter '': Nz[]'") alljoinr&dictitemsappendr' Exceptionloggerwarning maketrans translate) r!r"r#formatted_partsr- item_partskr2e param_typetranslation_table str_valuer.r.r/format_array_parameter)s0   rH param_valuecCs^t|tstd|dt|iSi}|D]\}}|d|d}t|||<q|S)a Format a dictionary parameter for deepObject style serialization. According to OpenAPI 3.0 spec, deepObject style with explode=true serializes object properties as separate query parameters with bracket notation. For example: `{"id": "123", "type": "user"}` becomes `param[id]=123¶m[type]=user`. Args: param_value: Dictionary value to format parameter_name: Name of the parameter Returns: Dictionary with bracketed parameter names as keys zdeepObject style parameter 'z' expected dict, got [])r&r9r=r>typer:r')rIr"resultkeyvalue bracketed_keyr.r.r/format_deep_object_parameter[s rQc@sreZdZUdZeed<eed<dZeed<e dddZ e ed <d Z ed Bed <d Z ed Bed <d Zed Bed <d S) ParameterInfoz>Represents a single parameter for an HTTP operation in our IR.namelocationFrequired.schema)aliasschema_N descriptionexplodestyle)__name__ __module__ __qualname____doc__r'__annotations__ParameterLocationrUr*rrX JsonSchemarYrZr[r.r.r.r/rR|s  rRc@sHeZdZUdZdZeed<eedZ ee e fed<dZ e dBed<dS)RequestBodyInfoz)rrr.r.r/_convert_to_parameter_location$sz,OpenAPIParser._convert_to_parameter_locationr-c Cst||jr|j}z|dstd||dd}|j}|D]s}|r5t|t r5|t |}nRt|t rq||j j vrGt||d}n@|jrU||jvrU|j|}n2|dkrbt|drb|j}n%t||rnt||d}nd}nt|tr|||}n td|d|d|durtd |d |dq#t||jr||WS|WStttttfy}z td |d ||d}~ww|S) z.Resolves a reference to its target definition.#//External or non-local reference not supported: /N componentszCannot traverse part 'z' in reference ''zReference part 'z' not found in path 'zFailed to resolve reference 'r5)r&rrefrrstripsplitrisdigitrtr(r __class__ model_fieldsgetattr model_extrahasattrrr9r _resolve_refAttributeErrorKeyError IndexError TypeError)rr-ref_strpartstargetpartrDr.r.r/r+sP          zOpenAPIParser._resolve_ref schema_objc Csz.||}t||jr|jdddd}nt|tr|}n tdt|di}t|WSt yS}zdt |vr=tj d|dd iWYd }~Sd }~wt yp}ztj d|dd iWYd }~Sd }~ww) z1Resolves a schema and returns it as a dictionary.jsonT)modeby_alias exclude_nonez%Expected Schema after resolving, got z. Returning empty dict.-External or non-local reference not supportedz"Failed to extract schema as dict: Fexc_infoN) rr&r model_dumpr9r=r>rL_replace_ref_with_defsrr'rr<)rrresolved_schemarMrDr.r.r/_extract_schema_as_dict_s0     z%OpenAPIParser._extract_schema_as_dictNoperation_paramspath_item_paramsc Csg}i}|pg|p g}|D]}z||}t||js)tdt|dWq|j}ddlm} t|| r:|j n|} | | } |j } |j | f} | |vrOWqd|| <i}| rw| | }|| }t||jsvt|drv|jdurv|j|d<n>t|dr|jrtt|jd}|rt|d r|jr|j}| |}||}t||jst|dr|jdur|j|d<t|d d}t|d d}t|j | |j||j||d }||Wqty}zt|d t|dd}tjd|d|ddWYd}~qd}~ww|S)zrLrenumrrOr param_schemarSrrrrrnextiterr!rrrRrUrYr;r<r)rrrextracted_params seen_params all_params param_or_ref parameterrr param_in_strparam_locationparam_schema_obj param_keyparam_schema_dictrfirst_media_type media_schemaresolved_media_schemarZr[ param_inforD param_namer.r.r/_extract_parameters|s                  z!OpenAPIParser._extract_parametersrequest_body_or_refc Cs|sdSz||}t||jstdt|dWdSt|j|jd}t |dr|j r|j D]\\}}|rt |dr|j rz | |j }||j|<Wq3tyr}zdt|vr]td|d |WYd}~q3d}~wty}ztd|d |WYd}~q3d}~wwq3|WSty}z!dt|vrt|d d }tjd |d |d dWYd}~dSd}~wty}zt|d d }tjd |d |d dWYd}~dSd}~ww)z-Extract and resolve request body information.Nz*Expected RequestBody after resolving, got z. Returning None.)rUrYrrr)Failed to extract schema for media type 'r5rrz Failed to extract request body 'Fr)rr&rr=r>rLrcrUrYrrr:rrrfrr'rr<r) rrrnrequest_body_infomedia_type_strmedia_type_obj schema_dictrDref_namer.r.r/_extract_request_bodysz      z#OpenAPIParser._extract_request_bodyoperation_responsesc Csi}|s|S|D]\}}z||}t||js*td|dt|dWq t|jd}t |dr|j r|j D]b\}}|rt |dr|j rz | |j } | |j |<Wq=ty} zdt| vrgtd|d |d | WYd } ~ q=d } ~ wty} ztd|d |d | WYd } ~ q=d } ~ wwq=||t|<Wq ty} z#dt| vrt|d d } tjd|d| d| ddWYd } ~ q d } ~ wty} zt|d d } tjd|d| d| ddWYd } ~ q d } ~ ww|S)z)Extract and resolve response information.z2Expected Response after resolving for status code z, got r)rYrrrrz' in response : Nrrz+Failed to extract response for status code z from reference 'r5Fr)r:rr&rr=r>rLrgrYrrrrrfrr'rr<r) rrextracted_responses status_code resp_or_refresponse resp_inforrrrDrr.r.r/_extract_responses!s      z OpenAPIParser._extract_responsescCsg}t|jdr |jjstdgSi}t|jdrn|jjrn|jj}t|drn|jrn|jD]=\}}zt||j rH| |}| |||<n| |||<Wq0t ym}ztd|d|WYd}~q0d}~ww|jjD]\}} t| |j std|d t| d qtt| d r| jnd} gd } | D]} t| | d} | ryt| |jry| }ze|t| d d| }|t| d d}|t| dd}i}t| dr| jrdd| jD}t||t| ddt| ddt| ddt| dgpg||||||jd }||td|d|WqtyM}z'dt|vr*t| dd}tjd|d|d|d|ddWYd}~qd}~wt yx}zt| dd}tjd|d|d|d|ddWYd}~qd}~wwqqttd t|d!|S)"z*Parse the OpenAPI schema into HTTP routes.pathsz$OpenAPI schema has no paths defined.rschemasz%Failed to extract schema definition 'r5Nz%Skipping invalid path item for path 'z ' (type: )rm)rputpostdeleteoptionsheadpatchtrace requestBodyrorcSs i|] \}}|dr||qS)zx-)rr,rCr2r.r.r/ s z'OpenAPIParser.parse.. operationIdrkrYrl) rrirjrkrYrlrmrnrorprqrrzSuccessfully extracted route:  rrzFailed to process operation z (ID: z): TrzFinished parsing. Extracted z HTTP routes.)rrrr=r>rrr:r&rrrr<rrLrmrrupperrrrrrhrrr;rrr'rlen)rroutesrprrSrVrrDpath_str path_item_objpath_level_params http_methods method_lower operation method_upperrmrrorqrouteop_errorop_idr.r.r/rks               @zOpenAPIParser.parseNN)r\r]r^r_rxrLrzryr{r|r}r~rr'rrarrrrbrrtrRrrcrr9rgrrhrr.r.r.r/rsP   4   cB  JrrVcCs|rt|ts |S|}gd}|D] }||vr||qd|vr9dd|dD|d<|ds9|dd|vrNt|d|d<|dsN|dd|vrlt|dtrct|d|d<dS|ddurn dSdSdS) zW Clean up a schema dictionary for display by removing internal/complex fields. ) allOfanyOfoneOfnotnullable discriminatorreadOnly writeOnly deprecatedxml externalDocs propertiescSi|] \}}|t|qSr.)clean_schema_for_displayrr.r.r/r sz,clean_schema_for_display..r:additionalPropertiesTN)r&r9copypopr:r)rVcleanedfields_to_removefieldr.r.r/rs6      rc Cs|rt|ts dSd|vr|dSd|vr&t|dtr&|dr&|ddSd|vr;t|dtr;|dr;|ddSd|vrC|dS|d}|dkri}|d i}t|trt|d g}t|d d }|D]}||vr{t||||<qm|D]}||vr||vrt||||<q~|r|Sd diS|dkr|d}t|trt|} | d ur| gSgSdgS|dkr|d} | dkrdS| dkrdS| dkrdS| dkrdS| dkrdSdS|dkrdS|d krd!S|d"krd#S|d$krd Sd%S)&zy Generate a simple example value from a JSON schema dictionary. Very basic implementation focusing on types. rrrrexamplesexamplerLobjectrrUNrNrOarrayr: example_itemstringformatz date-timez2024-01-01T12:00:00Zdatez 2024-01-01emailzuser@example.comuuidz$123e4567-e89b-12d3-a456-426614174000bytez ZXhhbXBsZQ==integernumberg?booleanTnull unknown_type)r&r9rtrsetkeysgenerate_example_from_schema) rV schema_typerMrrequired_propsprops_to_include prop_namereq_prop items_schema item_example format_typer.r.r/r7!s          r7dataindentcCs<ztj||d}d|dWStyd|dYSw)z8Formats Python data as a JSON string block for markdown.rBz```json z ```z!``` Could not serialize to JSON: )rdumpsr)rArBjson_strr.r.r/format_json_for_descriptionts  rFbase_descriptionrormrnc s|g}|redd|D}|r5d}|||D]}|jrdnd}d|jd|d|jp,d } || qd d|D} | red }||| D]}|jrNdnd}d|jd|d|jp\d } || qG|r|jrd } || |jrvdnd}|d |j||jrd|jvrdntt|jd} | r|j| i} t| t rd| vr|d| d D]+\}}t|t rd|vr|| dgv}|rdnd}|d|d|d|dqrd}d}hd}tfdd|Dd} }t |D]\}}|s ||d}||krdnd}|d|d|d|jp"d |jrd|jvr2dntt|jd} | r|j| } |d| dt| t r| ddkrd| vr| d}t|t rd|vr|d |d D]\}}t|t rd|vr|d!|d"|dqyn.d| vr|d#| d D]\}}t|t rd|vr|d!|d"|dq| rt | }|d$kr|dur|d%|t |d&d'qd |S)(aX Formats the base description string with response, parameter, and request body information. Args: base_description (str): The initial description to be formatted. responses (dict[str, Any]): A dictionary of response information, keyed by status code. parameters (list[ParameterInfo] | None, optional): A list of parameter information, including path and query parameters. Each parameter includes details such as name, location, whether it is required, and a description. request_body (RequestBodyInfo | None, optional): Information about the request body, including its description, whether it is required, and its content schema. Returns: str: The formatted description string with additional details about responses, parameters, and the request body. cSg|] }|jdkr|qS)rrTr,pr.r.r/ z5format_description_with_responses..z **Path Parameters:**z (Required)r6z - **z**rzNo description.cSrH)rrIrJr.r.r/rLrMz **Query Parameters:**z **Request Body:** application/jsonNrz **Request Properties:**rYrUz **Responses:**F>200201202204c3s|] }|vr|VqdSr%r.)r,sror.r/r0sz4format_description_with_responses..Tz (Success)z - Content-Type: ``rLr'r:z" - **Response Item Properties:**z - **z**: z - **Response Properties:**r4z - **Example:**r@rC)r;rUrSrYrfrrrr&r9r:sortedr7rFr8)rGrormrn desc_parts path_params param_sectionparamrequired_marker param_desc query_paramsreq_body_section media_typerVr; prop_schemarUreq_markresponse_sectionadded_response_section success_codessuccess_statusresponses_to_processrr status_markerr=r$r.rUr/!format_description_with_responses}s                       riinforYc Cs|}|d}r2t|tr1|dr$|dd}d||d<n9|ds1td|dn+|d }rPd|vrDt||d <nd d |D|d <n |d }r]t||d <d D]}t ||gD] \}} t| |||<qiq_|d|r|ds||d<|S)a Replace openapi $ref with jsonschema $defs Examples: - {"type": "object", "properties": {"$ref": "#/components/schemas/..."}} - {"$ref": "#/components/schemas/..."} - {"items": {"$ref": "#/components/schemas/..."}} - {"anyOf": [{"$ref": "#/components/schemas/..."}]} - {"allOf": [{"$ref": "#/components/schemas/..."}]} - {"oneOf": [{"$ref": "#/components/schemas/..."}]} Args: info: dict[str, Any] description: str | None Returns: dict[str, Any] $ref#/components/schemas/r#/$defs/rrz. FastMCP only supports local schema references starting with '#/'. Please include all schema definitions within the OpenAPI document.rcSrr.)r)r,r;rar.r.r/r>sz*_replace_ref_with_defs..r:)rrrrY) rrr&r'rrrrr: enumerate) rjrYrVref_path schema_namer item_schemasectionir-r.r.r/rs4      rcCsd|vs d|vs d|vr|St|dtrd|dvr|Sd|vrj|d}t|trjd|i}i}t}|dkr=hd}n|dkrEhd }|D]\}}|dkrRqI||vr[|||<qI|||<qI|ddig|d<|S|S) z Make an optional parameter schema nullable to allow None values. For optional parameters, we need to allow null values in addition to the specified type to handle cases where None is passed for optional parameters. rrrrLr3r'> r:containsmaxItemsminItems maxContains minContains prefixItems uniqueItemsunevaluatedItemsr%>rUr maxProperties minProperties propertyNamespatternPropertiesrunevaluatedProperties)r&rrtr'r5r:)rV original_typenested_non_nullable_schemanullable_schematype_specific_propertiesrNrOr.r.r/!_make_optional_parameter_nullableLs0      rcCsd|vr,|d}t|tr|dg|d<dSt|tr(d|vr*g|d|d<dSdSdSd|vr?g|dddi|d<dSd|vr[tdd|dDsY|dddidSdSd|vrnd|diddig|d<dSdS) zdAdd 'null' to the schema's type field or handle oneOf/anyOf/allOf constructs if not already present.rLr3rrcss|] }|ddkVqdS)rLr3N)rr+r.r.r/r0sz$_add_null_to_type..rN)r&r'rtranyr;)rV current_typer.r.r/_add_null_to_types$  rcCst|ts|Sd|v}|o |do d|vp d|vp d|vp d|v}d}d|vr=|dD]}t|tr {"type": ["string", "null"]}rrLrrrFrT)r&r9r!rrrr:)rVhas_root_nullable_fieldhas_root_nullable_truehas_property_nullable_fieldrarM _prop_namenullable_valuer.r.r/rusN     rur csji}g}ttttd}i}|jD] }||j|jq|jrB|jjrBtt|jj}t |jj| |jj }| di}t}| D]} || qIt|} || @} |jD]\}|j| vr|jd|j} |jrv|| t |j |j } | dd}d|jd}|r|d|| d<n|| d<| || <q^|jr||jt |j |j } | ||j<q^|jr|jjr|D]\}}|||<q|jjr|| d gd ||d }|jr|j |d <| d dur|d d |vr3tfdd|D]\}}|d kr|q r.fdd|d D|d <|S|d |S)z Combines parameter and request body schemas into a single schema. Handles parameter name collisions by adding location suffixes. Args: route: HTTPRoute object Returns: Combined schema dictionary rr__rYr6(z parameter)rrUr%)rLrrU$defsrFct|tr0d|vr#t|dtr#|d}|dr#|dd|D]}|q'dSt|tr>|D]}|q7dSdSNrkrnrrmr&r9r'raddrr!rtrOrr2r-find_refs_in_value used_refsr.r/rI      z,_combine_schemas..find_refs_in_valueci|] \}}|vr||qSr.r.r,rS def_schemarr.r/r\ z$_combine_schemas..)r5rmrTrrSrnrfrrrrrYrr!updater6rUr;rX capitalizer:extendrpr)r rrUparam_names_by_location body_propsr[ content_type body_schemaall_non_body_paramslocation_paramsbody_param_namescolliding_params suffixed_namer original_desc location_descr;rarMrNrOr.rr/_combine_schemass                       rcCst|trJd|v}d}|D] }t|ttBrd}nq|s#|s#|S|}|r0|d|d<|rH|D]\}}t|ttBrGt|||<q6|St|trVdd|DS|S)zPRecursively replace 'oneOf' with 'anyOf' in schema to handle overlapping unions.rFTrcSsg|]}t|qSr.)_adjust_union_typesr+r.r.r/rLsz'_adjust_union_types..)r&r9r!rtrrr:r)rV has_one_ofneeds_recursive_processingr2rMrCr.r.r/rgs,    rrprrcs`|sdSgd}d}|D] }||vr||}nq |dur/|D] \}}|dr.|}nq!|dus6|js8dSgd}d}|D]} | |jvrN|j| }nq@|durj|jrjtt|j} |j| }td| |rqt|tssdS| } d| vr|r| d} | dr| dd } | |vr||  } |r|d rt | } | d d krd d | id gdd}|} |rd| vri}|D]\}}|r|d rt |||<q|||<q|| d<| ddur| dd| vr#tfdd| D] \}}|dkr |qrfdd| dD| d<n| dttttft| } | S)a Extract output schema from OpenAPI responses for use as MCP tool output schema. This function finds the first successful response (200, 201, 202, 204) with a JSON-compatible content type and extracts its schema. If the schema is not an object type, it wraps it to comply with MCP requirements. Args: responses: Dictionary of ResponseInfo objects keyed by status code schema_definitions: Optional schema definitions to include in the output schema openapi_version: OpenAPI version string, used to optimize nullable field handling Returns: dict: MCP-compliant output schema with potential wrapping, or None if no suitable schema found N)rPrQrRrS2)rOzapplication/vnd.api+jsonzapplication/hal+jsonzapplication/ld+jsonz text/jsonz/Using non-JSON content type for output schema: rkrlrrmrrLr%rMT)rLrrUzx-fastmcp-wrap-resultrrFcrrrrrr.r/rrz@extract_output_schema_from_responses..find_refs_in_valuecrr.r.rrr.r/rrz8extract_output_schema_from_responses..)r:rrfrrr=rr&r9rrrurrr5rr'rr)rorprrre response_inforrjson_compatible_typesrVrfirst_content_type output_schemarprqwrapped_schemaprocessed_defsdef_namerrNrOr.rr/rvs              rv)F)r@rr%)Grtypingrrrrropenapi_pydanticrrr r r r r ropenapi_pydantic.v3.v3_0rrrrrrrrpydanticrrrfastmcp.utilities.loggingrfastmcp.utilities.typesrr\r=rsrar9r'rbrtr*rHrQrRrcrgrh__all__rxryrzr{r|r}r~rrwrrr7r(rFrirrrrurrrvr.r.r.r/s(           2  !           6i<S     "3F*8 &