o i>@stUddlmZddlZddlZddlmZddlmZddlm Z ddl m Z m Z m Z mZddlZddlmZddlmZdd lmZdd lmZddlZdd lmZmZmZmZdd lmZdd l m!Z!ddl"m#Z#ddl$m%Z%m&Z&m'Z'm(Z(e#e)Z*edddZ+de,d<d+ddZ-d+ddZ.e ddGdddZ/Gdd d e%Z0Gd!d"d"eZ1Gd#d$d$e%Z2d,d)d*Z3dS)-) annotationsN)Callable) ContextVar) dataclass) AnnotatedAnyLiteralcast)ToolAnnotations) ConfigDict)Field)BeforeValidator)ParsedFunctionTool ToolResult_convert_to_content)_convert_set_default_none)compress_schema) get_logger)FastMCPBaseModelNotSetNotSetTget_cached_typeadapter _current_tool)defaultz"ContextVar[TransformedTool | None]kwargsrreturnrcs0t}|dur td|jdi|IdHS)aGForward to parent tool with argument transformation applied. This function can only be called from within a transformed tool's custom function. It applies argument transformation (renaming, validation) before calling the parent tool. For example, if the parent tool has args `x` and `y`, but the transformed tool has args `a` and `b`, and an `transform_args` was provided that maps `x` to `a` and `y` to `b`, then `forward(a=1, b=2)` will call the parent tool with `x=1` and `y=2`. Args: **kwargs: Arguments to forward to the parent tool (using transformed names). Returns: The ToolResult from the parent tool execution. Raises: RuntimeError: If called outside a transformed tool context. TypeError: If provided arguments don't match the transformed schema. Nz6forward() can only be called within a transformed tool)rget RuntimeError forwarding_fnrtoolrrb/var/www/html/karishye-ai-python/venv/lib/python3.10/site-packages/fastmcp/tools/tool_transform.pyforward%s r$cs,t}|dur td|j|IdHS)aForward directly to parent tool without transformation. This function bypasses all argument transformation and validation, calling the parent tool directly with the provided arguments. Use this when you need to call the parent with its original parameter names and structure. For example, if the parent tool has args `x` and `y`, then `forward_raw(x=1, y=2)` will call the parent tool with `x=1` and `y=2`. Args: **kwargs: Arguments to pass directly to the parent tool (using original names). Returns: The ToolResult from the parent tool execution. Raises: RuntimeError: If called outside a transformed tool context. Nz:forward_raw() can only be called within a transformed tool)rrr parent_toolrunr!rrr# forward_rawCs r'T)kw_onlyc@szeZdZUdZeZded<eZded<eZded<eZ ded<eZ ded <d Z d ed <eZ d ed<eZ ded<ddZdS) ArgTransforma4 Configuration for transforming a parent tool's argument. This class allows fine-grained control over how individual arguments are transformed when creating a new tool from an existing one. You can rename arguments, change their descriptions, add default values, or hide them from clients while passing constants. Attributes: name: New name for the argument. Use None to keep original name, or ... for no change. description: New description for the argument. Use None to remove description, or ... for no change. default: New default value for the argument. Use ... for no change. default_factory: Callable that returns a default value. Cannot be used with default. type: New type for the argument. Use ... for no change. hide: If True, hide this argument from clients but pass a constant value to parent. required: If True, make argument required (remove default). Use ... for no change. examples: Examples for the argument. Use ... for no change. Examples: Rename argument 'old_name' to 'new_name' ```python ArgTransform(name="new_name") ``` Change description only ```python ArgTransform(description="Updated description") ``` Add a default value (makes argument optional) ```python ArgTransform(default=42) ``` Add a default factory (makes argument optional) ```python ArgTransform(default_factory=lambda: time.time()) ``` Change the type ```python ArgTransform(type=str) ``` Hide the argument entirely from clients ```python ArgTransform(hide=True) ``` Hide argument but pass a constant value to parent ```python ArgTransform(hide=True, default="constant_value") ``` Hide argument but pass a factory-generated value to parent ```python ArgTransform(hide=True, default_factory=lambda: uuid.uuid4().hex) ``` Make an optional parameter required (removes any default) ```python ArgTransform(required=True) ``` Combine multiple transformations ```python ArgTransform(name="new_name", description="New desc", default=None, type=int) ``` z str | NotSetTname descriptionz Any | NotSetTrzCallable[[], Any] | NotSetTdefault_factorytypeFboolhidezLiteral[True] | NotSetTrequiredexamplescCs~|jtu}|jtu}|r|rtd|r|jstd|jdur(|s$|r(td|jr4|jdur4td|jdur=tddS) zAValidate that only one of default or default_factory is provided.zCannot specify both 'default' and 'default_factory' in ArgTransform. Use either 'default' for a static value or 'default_factory' for a callable.zdefault_factory can only be used with hide=True. Visible parameters must use static 'default' values since JSON schema cannot represent dynamic factories.TzmCannot specify 'required=True' with 'default' or 'default_factory'. Required parameters cannot have defaults.z|Cannot specify both 'hide=True' and 'required=True'. Hidden parameters cannot be required since clients cannot provide them.Fz=Cannot specify 'required=False'. Set a default value instead.N)rrr, ValueErrorr/r0)self has_default has_factoryrrr# __post_init__s.    zArgTransform.__post_init__N)__name__ __module__ __qualname____doc__rr*__annotations__r+rr,r-r/r0r1r6rrrr#r)]s  D        r)c@seZdZUdZedddZded<edddZded<edd dZd ed <ed d dZ ded<edddZ ded<edddZ ded<dddZ dS)ArgTransformConfigz3A model for requesting a single argument transform.NzThe new name for the argument.rr+ str | Noner*z%The new description for the argument.r+z'The new default value for the argument.zstr | int | float | bool | NonerFz+Whether to hide the argument from the tool.r.r/z!Whether the argument is required.zLiteral[True] | Noner0zExamples of the argument.z Any | Noner1rr)cCstdi|jddS)z?Convert the argument transform to a FastMCP argument transform.T) exclude_unsetNr)r) model_dump)r3rrr#to_arg_transformsz#ArgTransformConfig.to_arg_transform)rr)) r7r8r9r:r r*r;r+rr/r0r1rArrrr#r<s" r<c @seZdZUdZedddZded<ded<ded <d ed <d=ddZede e ddde e e e df d>d(d)Z ed?d+d,Z e d@d5d6Z e dAd9d:Ze dBd;d<ZdS)CTransformedToolaA tool that is transformed from another tool. This class represents a tool that has been created by transforming another tool. It supports argument renaming, schema modification, custom function injection, structured output control, and provides context for the forward() and forward_raw() functions. The transformation can be purely schema-based (argument renaming, dropping, etc.) or can include a custom function that uses forward() to call the parent tool with transformed arguments. Output schemas and structured outputs are automatically inherited from the parent tool but can be overridden or disabled. Attributes: parent_tool: The original tool that this tool was transformed from. fn: The function to execute when this tool is called (either the forwarding function for pure transformations or a custom user function). forwarding_fn: Internal function that handles argument transformation and validation when forward() is called from custom functions. allowT)extraarbitrary_types_allowedrr%Callable[..., Any]fnr zdict[str, ArgTransform]transform_args argumentsdict[str, Any]rrc s|}|jdi}|D]E\}}||vrUd|vrUd}|jrM|jD]&\}}|jtur2|jn|}||krL|jturLt|jrL|||<d}nq&|sU|d||<qt |} z|j d i|IdH} t | t r|jdurt|j j} | t ur| Wt | S| Wt | S|jddkr|jdst | jdd Wt | S| Wt | St| |jd } d} |jdur|jdrd | i} n| } | durzt| } t | tsd} Wn tyYnwt | | d Wt | St | w) aRun the tool with context set for forward() functions. This method executes the tool's function while setting up the context that allows forward() and forward_raw() to work correctly within custom functions. Args: arguments: Dictionary of arguments to pass to the tool's function. Returns: ToolResult object containing content and optional structured output. propertiesrFTNr-objectzx-fastmcp-wrap-result)contentstructured_content) serializerresultr)copy parametersritemsrHr*rr,callablersetrG isinstancer output_schemainspect signaturereturn_annotationresetrMrrO pydantic_coreto_jsonable_pythondict Exception)r3rIrK param_name param_schemahas_factory_default orig_name transformtransform_nametokenrPrZunstructured_resultstructured_outputrrr#r&s         - )  $       zTransformedTool.runNr"r*r>titlestr | NotSetT | Noner+tagsset[str] | None transform_fnCallable[..., Any] | Nonedict[str, ArgTransform] | Noner ToolAnnotations | NotSetT | NonerW0dict[str, Any] | Literal[False] | NotSetT | NonerO%Callable[[Any], str] | NotSetT | Nonemetadict[str, Any] | NotSetT | Noneenabled bool | Nonec (Cs|pi}|durtj|dd} nd} t|jdi}t||}|r?tddt|d|j ddt|| ||\}}| t urn|durjt t| j }|durit|j}|turfd}n"|j }n|j }n| durtjjr~tjd td d d}nt tdB| }|dur|}|}nLt t| } |}||}t| jdi}t|di}|s||}|rtd dt|d dt||| j|}n|| j|}|r)g}|D]\}}|js|j t ur||j q||qi}|D] }||dd||<qdd|D}|r)tddt||p.|j } t|t s7|n|j!}!t|t sB|n|j"}"t| t sM| n|j#}#t|t sX|n|j$}$t| t sc| n|j%}%| durm| n|j&}&||||| |"|!|||p~|j'|$|%|#||&d}'|'S)a Create a transformed tool from a parent tool. Args: tool: The parent tool to transform. transform_fn: Optional custom function. Can use forward() and forward_raw() to call the parent tool. Functions with **kwargs receive transformed argument names. name: New name for the tool. Defaults to parent tool's name. title: New title for the tool. Defaults to parent tool's title. transform_args: Optional transformations for parent tool arguments. Only specified arguments are transformed, others pass through unchanged: - Simple rename (str) - Complex transformation (rename/description/default/drop) (ArgTransform) - Drop the argument (None) description: New description. Defaults to parent's description. tags: New tags. Defaults to parent's tags. annotations: New annotations. Defaults to parent's annotations. output_schema: Control output schema for structured outputs: - None (default): Inherit from transform_fn if available, then parent tool - dict: Use custom output schema - False: Disable output schema and structured outputs serializer: New serializer. Defaults to parent's serializer. meta: Control meta information: - NotSet (default): Inherit from parent tool - dict: Use custom meta information - None: Remove meta information Returns: TransformedTool with the specified transformations. Examples: # Transform specific arguments only ```python Tool.from_tool(parent, transform_args={"old": "new"}) # Others unchanged ``` # Custom function with partial transforms ```python async def custom(x: int, y: int) -> str: result = await forward(x=x, y=y) return f"Custom: {result}" Tool.from_tool(parent, transform_fn=custom, transform_args={"a": "x", "b": "y"}) ``` # Using **kwargs (gets all args, transformed and untransformed) ```python async def flexible(**kwargs) -> str: result = await forward(**kwargs) return f"Got: {kwargs}" Tool.from_tool(parent, transform_fn=flexible, transform_args={"a": "x"}) ``` # Control structured outputs and schemas ```python # Custom output schema Tool.from_tool(parent, output_schema={ "type": "object", "properties": {"status": {"type": "string"}} }) # Disable structured outputs Tool.from_tool(parent, output_schema=None) # Return ToolResult for full control async def custom_output(**kwargs) -> ToolResult: result = await forward(**kwargs) return ToolResult( content=[TextContent(text="Summary")], structured_content={"processed": True} ) ``` NF)validaterKz%Unknown arguments in transform_args: , z. Parent tool `z` has: zJPassing output_schema=False is deprecated. Use output_schema=None instead.) stacklevelz;Function missing parameters required after transformation: z. Function declares: rcSsg|] \}}|dkr|qS)r{r).0arg_namecountrrr# .sz-TransformedTool.from_tool..z6Multiple arguments would be mapped to the same names: )rGr r%r*rir+rRrWrkrrOrsrHru)(r from_functionrUrRrkeysr2joinsortedr*_create_forwarding_transformrr rWrXrYrZrfastmcpsettingsdeprecation_warningswarningswarnDeprecationWarningr^_function_has_kwargs input_schema_merge_schema_with_precedencerSr/appendrVrr+rirsrrOrurk)(clsr"r*rir+rkrmrHrrWrOrsru parsed_fn parent_params unknown_argsschemar final_output_schemarZfinal_fn final_schema has_kwargs fn_paramstransformed_paramsmissing_params new_namesold_namerd name_countsr} duplicates final_namefinal_description final_title final_metafinal_annotationsfinal_serializer final_enabledtransformed_toolrrr# from_toolksZ            zTransformedTool.from_tool)tuple[dict[str, Any], Callable[..., Any]]cs<jdi}jdi}tjdg}itii|D]T\}}|r5||vr5||}nt}|jrZ|jtupD|j tu} | sS||vrSt d|d| rY||<q&| |||||v} | rz| \} } } | | <|| <| rz | q&dt d}|r||d<t|dd }dfd d }||fS)aCreate schema and forwarding function that encapsulates all transformation logic. This method builds a new JSON schema for the transformed tool and creates a forwarding function that validates arguments against the new schema and maps them back to the parent tool's expected arguments. Args: parent_tool: The original tool to transform. transform_args: Dictionary defining how to transform each argument. Returns: A tuple containing: - The new JSON schema for the transformed tool as a dictionary - Async function that validates and forwards calls to the parent tool $defsrKr0zHidden parameter 'z' has no default value in parent tool and no default or default_factory provided in ArgTransform. Either provide a default or default_factory in ArgTransform or don't hide required parameters.rLr-rKr0T prune_defsrrc st}t|}||}|rtddt||}|r1tddt|i}|D]\}}||}|||<q7D]\}} | jturY| j||<qJ| j turit | j ri| ||<qJ |IdHS)Nz$Got unexpected keyword argument(s): rxzMissing required argument(s): ) rUr TypeErrorrrrSrrrr,rTr&) r valid_args provided_argsr missing_args parent_argsnew_namevaluerrdhidden_defaults new_props new_required new_to_oldr%rr#_forwards2         z>TransformedTool._create_forwarding_transform.._forwardN)rr)rRrrQrUrSr)r/rrr,r2_apply_single_transformaddlistr)rr%rH parent_defs parent_propsparent_requiredr old_schemardhas_user_defaulttransform_resultr new_schema is_requiredrrrrr#rXsX        #z,TransformedTool._create_forwarding_transformrstrrrdr)rr.'tuple[str, dict[str, Any], bool] | NonecCs|jrdS|jtur|jdur|jn|}n|}t|ts|}|}|jtur8|jdur3|ddn|j|d<|jturMt |j}|jdurM|dd|j tur^|jdur^|j |d<d}|j turot |j  }|||jtury|j|d<|||fS)apApply transformation to a single parameter. This method handles the transformation of a single argument according to the specified transformation rules. Args: old_name: Original name of the parameter. old_schema: Original JSON schema for the parameter. transform: ArgTransform object specifying how to transform the parameter. is_required: Whether the original parameter was required. Returns: Tuple of (new_name, new_schema, new_is_required) if parameter should be kept, None if parameter should be dropped. Nr+TrFr1)r/r*rrVrrQr+popr0r.rr-r json_schemaupdater1)rrrdrrr type_schemarrr#rs2               z'TransformedTool._apply_single_transform base_schemaoverride_schemacCs|di}t|dg}|di}t|dg}|D]\}}||vr:||}|||||<q"|||<q"|} |D]}||vrS| |qG||vrfd||vrf||vrf| |qG|D] \}}d|vrx| |qk|di} |di} | D]\} } | | vr| | }|| || | <q| | | <qd|t| d}| r| |d<t|dd}|S) a*Merge two schemas, with the override schema taking precedence. Args: base_schema: Base schema to start with override_schema: Schema that takes precedence for overlapping properties Returns: Merged schema with override taking precedence rKr0rrrLrTr) rrQrUrSrrdiscardrr)rr merged_propsmerged_requiredoverride_propsoverride_requiredr`ra base_paramfinal_required merged_defs override_defsdef_name def_schemabase_defrPrrr#rsN              z-TransformedTool._merge_schema_with_precedencecCs"t|}tdd|jDS)abCheck if function accepts **kwargs. This determines whether a custom function can accept arbitrary keyword arguments, which affects how schemas are merged during tool transformation. Args: fn: Function to inspect. Returns: True if the function has a **kwargs parameter, False otherwise. css|] }|jtjjkVqdS)N)kindrX Parameter VAR_KEYWORD)r|prrr# rs z7TransformedTool._function_has_kwargs..)rXrYanyrRvalues)rGsigrrr#rds z$TransformedTool._function_has_kwargs)rIrJrr)r"rr*r>rirjr+rjrkrlrmrnrHrorrprWrqrOrrrsrtrurvrrB)r%rrHrorr) rrrrJrdr)rr.rr)rrJrrJrrJ)rGrFrr.)r7r8r9r:r model_configr;r& classmethodrrr staticmethodrrrrrrr#rBs<   hm x D MrBc@seZdZUdZedddZded<edddZded<edd dZded <ee d d Z d ed<edddZ ded<edddZ ded<ee dd Zded<dddZdS) ToolTransformConfigz#Provides a way to transform a tool.NzThe new name for the tool.r=r>r*zThe new title of the tool.riz The new description of the tool.r+zThe new tags for the tool.)r,r+z?Annotated[set[str], BeforeValidator(_convert_set_default_none)]rkz&The new meta information for the tool.zdict[str, Any] | NonersTzWhether the tool is enabled.r.ruz9A dictionary of argument transforms to apply to the tool.zdict[str, ArgTransformConfig]rIr"rrrBcCs<|jddhd}tjd d|i|ddd|jDiS) zTCreate a TransformedTool from a provided tool and this transformation configuration.TrI)r?excluder"rHcSsi|] \}}||qSr)rA)r|kvrrr# sz-ToolTransformConfig.apply..Nr)r@rBrrIrS)r3r" tool_changesrrr#applyszToolTransformConfig.apply)r"rrrB)r7r8r9r:r r*r;rir+rUrkrsrur^rIrrrrr#rws8 rtoolsdict[str, Tool]transformationsdict[str, ToolTransformConfig]cCsFi}|D]\}}||}r||||jp|<q|||<q|S)z{Apply a list of transformations to a list of tools. Tools that do not have any transformations are left unchanged. )rSrrr*)rrtransformed_tools tool_namer"transformationrrr#apply_transformations_to_toolss r)rrrr)rrrrrr)4 __future__rrXrcollections.abcr contextvarsr dataclassesrtypingrrrr r\ mcp.typesr pydanticr pydantic.fieldsr pydantic.functional_validatorsr rfastmcp.tools.toolrrrrfastmcp.utilities.componentsrfastmcp.utilities.json_schemarfastmcp.utilities.loggingrfastmcp.utilities.typesrrrrr7loggerrr;r$r'r)r<rBrrrrrr#sF            r.