调用前逻辑通过 preHandler 实现，在工具进入业务执行前运行。它适合做参数校验、默认值补齐、参数归一化，以及按现场规则改写 ctx.arguments 或 ctx.tool_config。当请求不符合业务规则时，可以抛出 HandlerAbort 中断本次调用，并给 LLM 返回可操作的修改建议。

第一步：编写调用前逻辑

以 createBuffer 工具为例，在产品包目录 /cfg/gpa_mcp/v2_handlers/ 下新建 buffer_hooks.py：

import time
from mcptools.v2.handler_api import HandlerContext, HandlerAbort

async def validate_distance(ctx: HandlerContext):
"""preHandler：校验/改写参数，可中断执行"""
dist = float(ctx.arguments.get("bufferDistance", 0))
if dist > 50000:
raise HandlerAbort(
"缓冲距离过大",
suggestions=["请使用 50km 以内的缓冲距离"],
)
ctx.state["t0"] = time.time() # 可传给调用后处理

validate_distance 在业务执行之前读取 ctx.arguments。若缓冲距离超出上限，抛出 HandlerAbort 直接中断本次调用；若校验通过，则把起始时间写入 ctx.state，后续的 postHandler 可以读取该值记录耗时。

第二步：挂到工具 JSON 上

{
"name": "createBuffer",
"gpaToolId": "iobjects_vectoranalyst:createbuffer",
"preHandler": "buffer_hooks:validate_distance"
}

保存文件并按收尾：部署、验证与排错中的方法验证即可，不需要重启容器。需要在业务执行后继续记录日志或通知外部系统时，请继续阅读场景四：自定义调用后逻辑。