MCP 工具参考

蜀农 API 的 MCP 端点当前提供 4 个工具，覆盖天气、知识库、图像识别与时间四类农业场景。客户端通过 tools/list 获取定义，通过 tools/call 调用。

工具清单

四个工具均为同步返回，无副作用，可安全重试。工具结果是字符串化的 JSON，需要二次解析，详见 MCP 接入。

weather_search

查询中国城市的天气。数据源为中国天气网，支持实时天气和未来 7 日预报两种模式。

参数

实时天气

传入 {"location": "成都", "date": "now"}，返回：

{
  "city": "101270101",
  "weather": "阴",
  "temperature": "19.8℃",
  "humidity": "",
  "wind": "北风 1级",
  "updateTime": "20:50"
}

7 日预报

传入 {"location": "成都", "date": "2026-10-26"}（当天），返回（节选首日）：

{
  "city": "成都",
  "forecast": [
    {
      "date": "2026-10-26",
      "weather": "阴",
      "high": "20℃",
      "low": "13℃",
      "wind": "微风",
      "humidity": "23%",
      "week": "一"
    }
  ]
}

forecast 固定为 7 个元素，从当天开始排列，传入的 date 只用于触发预报模式，不影响起始日期。week 为星期的中文单字表示。

预报模式下 city 回显你传入的名称，实时模式下 city 返回内部城市编码。两个模式的字段不一致，解析时请分别处理。

使用建议

• 优先传 9 位城市编码。城市名存在重名（如多个城市有同名区县）时，编码更准确。
• 农事决策类问题建议同时取实时天气与 7 日预报，病虫害预警通常需要连续多日的温湿度趋势。
• 预报数据用于趋势判断，不宜作为精确到某小时的作业依据。

knowledge_search

检索平台内置的农技知识库，采用向量 + 全文 + RRF 融合的混合检索策略，返回原文片段与分数，便于在回答中标注知识来源。

参数

返回示例（命中）

{
  "kb_code": "TEA_MANAGER_001,Strip_Intercropping,RICE_001,CORN_001,SOYBEAN_001",
  "kb_name": "茶树管理,玉米大豆带状复合种植技术,水稻,玉米,大豆",
  "query": "茶树修剪技术要点",
  "mode": "hybrid",
  "score_type": "rrf(≈1/(60+rank), 仅用于排序)",
  "total": 2,
  "counts": {"vector": 32, "fulltext": 2, "hybrid": 2, "rerank": 0},
  "sources": [
    {
      "doc_name": "茶树农事操作.docx",
      "chunk_index": 1,
      "content": "7月底驻芽期时，提示对茶树进行浅修，同步施基肥或者复合肥……",
      "score": 0.0164
    }
  ],
  "warnings": ["Rerank 精排已手动关闭"]
}

score 不是统一的相似度。hybrid 模式下 score_type 为 rrf(≈1/(60+rank), 仅用于排序)，分数量级很小（常见 0.01~0.03），只能用于排序，不能按 0.7 之类的主观阈值理解；vector 模式下 score_type 为 cosine_similarity(0~1)，才是 0~1 的余弦相似度。判断相关性时先看 score_type，不要跨模式比较数值大小。

未命中行为

检索的候选片段被 scoreThreshold 全部过滤时，服务端按工具调用失败返回：isError 为 true，text 是一段纯文本（不是 JSON），内容包含各阶段候选数与真实原因：

Error invoking method: knowledgeSearch
知识库未命中相关片段(候选: 向量 32 条 / 全文 0 条); score_threshold=0.7 过滤掉全部 32 条候选(最高分 0.6385), 可降低阈值或传 0 关闭过滤。可改用更具体的关键词或同义词重试, 或适当降低 score_threshold; 在获得命中内容前不要编造引用

不存在 total 为 0 且 isError 为 false 的"正常空结果"。收到这种失败时，应告知用户知识库暂无相关资料，或改用更具体的关键词重试，不要让模型编造引用。

知识库范围

账号可检索的知识库取决于开通情况，kb_code 会随检索结果返回，可以直接从中取用。常见编码示例：

问题超出已开通知识库覆盖范围时，默认阈值（0.7）会把候选全部过滤掉，从而走到上面的"未命中"分支。只有在显式传 scoreThreshold: 0 时，才会返回与问题无关的低分片段。

使用建议

• 明确作物和生育期后再提问，query 写全"作物 + 生育期 + 农事环节"三段，召回质量明显更好。
• 已知知识库范围时传 kbCode，避免跨库召回噪声。
• 需要标注引用来源时，用 doc_name 与 chunk_index 定位原文，score 可作为排序置信度参考（注意 score_type）。
• useRerank 适合跨库检索或 topK 较大的场景，单库小范围检索收益有限。
• scoreThreshold 调得过低会放进大量噪声片段，只有在确知知识库有覆盖、但默认阈值下被滤空时才下探，不建议长期传 0。

crop_growth_recognize

作物生长周期图像识别。传入图片地址或 base64，返回识别结果。支持小麦生育期判断、茶芽计数、茶树生育期三种识别类型。

参数

返回示例（茶芽计数）

{
  "status": "success",
  "data": {
    "task_type": "detect",
    "detections": [
      {
        "class_id": 0,
        "confidence": 0.9231,
        "bbox": [128, 96, 176, 148],
        "class_name": "tea"
      }
    ],
    "count": 1,
    "inference_time": 0.1187,
    "input_size": [640, 640],
    "model_id": "tea_count",
    "model_name": "茶叶数量检测",
    "recognized_result": 1,
    "original_image": "http://si-device.oss-cn-chengdu.aliyuncs.com/detections%2F20261026_134828_169552.jpg?OSSAccessKeyId=LTAI5t********&Expires=1792997308&Signature=***",
    "original_compressed": false
  },
  "message": "检测成功",
  "error": null
}

返回示例（小麦生育期）

{
  "status": "success",
  "data": {
    "task_type": "detect",
    "detections": [],
    "count": 0,
    "model_id": "wheat_stage",
    "model_name": "小麦生育时期",
    "recognized_result": null
  },
  "message": "检测成功",
  "error": null
}

recognized_result 为 null 表示模型未能在图中识别出明确的生育期，常见于拍摄距离过远、叶片遮挡严重或图片本身不是作物。此时不应向用户输出具体生育期结论。

图片要求

imageUrl 必须是服务端能直接下载到的地址：公网可访问、无重定向跳转、返回的 Content-Type 为图片类型。返回 302 跳转的 CDN 链接、需要登录态鉴权的链接、境外站点链接都可能下载失败。遇到这种情况，请先在你的环境下载图片，转成 base64 后传入。

使用 base64 时，直接传编码后的字符串，不需要 data:image/jpeg;base64, 前缀；使用 data URI 则需带完整前缀。建议单张图片不超过 4 MB。

拍摄建议：

• 相机垂直俯拍，目标占据画面主要区域，避免强烈逆光。
• 茶芽计数需要能分辨单芽轮廓，建议拍摄距离小于 50 厘米。
• 生育期判断建议整株入镜，保留茎叶与穗部形态。

失败返回

图片下载失败时按工具调用失败返回：isError 为 true，text 是纯文本（不是 JSON），首行是方法名，第二行起是原因：

Error invoking method: cropGrowthRecognize
图片下载失败: HTTP 404 https://example.com/a.jpg

可能的错误内容：图片下载失败: HTTP 404（地址不可访问）、图片下载失败: HTTP 302（存在重定向）、HTTP connect timed out（服务端无法访问该域名）。

这行文本不能按 JSON 解析，客户端应读取 isError 或匹配文本前缀判断失败，不要把整段返回当作识别结果。

使用建议

• 始终显式传 recognitionType。不传时服务端默认落到 wheat_stage，即使图片是茶树也不会自动切换。
• 对 confidence 低于 0.5 的检测结果，建议提示用户重新拍摄，不要直接采信。
• original_image 链接约 1 小时后失效，需要长期留存图片请自行下载转存。

get_current_time

获取当前日期时间，附带农历节气信息。适合处理"现在几点"“今天星期几”"还有几天到下一个节气"这类时间相关问题，避免模型凭训练数据推算日期出错。

参数

返回示例

{
  "timezone": "Asia/Shanghai",
  "datetime": "2026-10-25 21:06:13",
  "date": "2026-10-25",
  "time": "21:06:13",
  "weekday": "星期日",
  "unix": 1792933573,
  "solar_term": "霜降",
  "solar_term_date": "2026-10-23",
  "next_solar_term": "立冬",
  "next_solar_term_date": "2026-11-07",
  "days_to_next_solar_term": 13,
  "solar_term_year": 2026,
  "solar_terms": [
    {"name": "小寒", "date": "2026-01-05"},
    {"name": "大寒", "date": "2026-01-20"}
  ]
}

使用建议

• 农事建议涉及"播种适期"“越冬前”"追肥窗口"等时间判断时，先调用该工具取当前日期与节气，再结合当地气候给建议。
• 需要跨节气排农事计划时，传 withSolarTerms 一次性取全年节气表，减少调用次数。
• format 只影响 datetime 字段，date、time 等字段保持固定格式。

常见问题

工具列表里只有 4 个工具，能自己扩展吗？

不能。MCP 端点的工具集由平台统一维护，不支持在端点侧注册自定义工具。如果业务需要专有函数，请在自有应用里使用 REST 接口的 tools 参数（参见 工具调用），由你的代码执行自定义函数。

调用工具需要消耗模型 Token 吗？

MCP 端点只执行工具本身，不调用大模型，因此不会产生对话类 Token 消耗。工具使用量如何计费，以控制台展示为准，参见 计费说明。

为什么工具调用成功了，返回内容却是空的？

先看 isError。工具执行失败时服务端会返回 isError: true，text 是 Error invoking method: <方法名> 开头的纯文本，不是 JSON，不要按 JSON 解析。isError 为 false 但没有内容，通常是业务侧"确实没结果"：knowledge_search 的 sources 可能为空数组、crop_growth_recognize 的 detections 可能为空、生育期类的 recognized_result 可能为 null，这些不是故障。

一次会话能调用多少次工具？

单次会话没有工具调用次数上限，但端点存在频率限制。被限流时按指数退避重试，不要密集轮询。