教学 LLM 按需拉取 MCP 资源与提示词以优化上下文

## Available Resources
The following resources can be read on demand. To read one, call the
`read_resource` tool with its exact URI. Do not assume a resource's
contents until you have read it.

### Resource: SUM ABAP Test Matrix
URI: sap-btp://sum-abap-v1
Description: SUM (Software Update Manager) test matrix specification for ABAP products

from pydantic import BaseModel, Field
from langchain_core.tools import StructuredTool

class ReadResourceArgs(BaseModel):
    uri: str = Field(
        description="The exact URI of the MCP resource to read, e.g. 'sap-btp://sum-abap-v1'."
    )

read_resource_tool = StructuredTool.from_function(
    func=lambda uri: "",  # 占位 Lambda，在图的执行流中被拦截
    name="read_resource",
    description=(
        "Read the full contents of an MCP resource by its URI. "
        "Call this when the user asks to read, open, or summarize a resource, "
        "or when you need a resource's contents to answer. "
        "Only resources listed under 'Available Resources' can be read."
    ),
    args_schema=ReadResourceArgs,
)

# 注册工具并将其加入免审白名单
tools = [read_resource_tool]
allowed_tools_without_review = ["read_resource"]

# 内存资源缓存
resources_content = {}

def initialize_resource_cache(mcp_resources):
    for res in (mcp_resources or []):
        uri = getattr(res, "uri", None)
        name = getattr(res, "name", "")
        description = getattr(res, "description", "")
        content = getattr(res, "content", "")
        
        # 避坑指南：MCP 协议中的 URI 可能会以 Pydantic 的 AnyUrl 对象形式传入。
        # 必须将其显式转换为 plain string，否则在字典查询中会因为类型不匹配而静默失败。
        uri_str = str(uri) if uri is not None else ""
        if uri_str and uri_str != "unknown":
            resources_content[uri_str] = {
                "name": name,
                "description": description,
                "content": content
            }

def is_text_mime(mime: str) -> bool:
    mime = (mime or "").lower().split(";")[0].strip()
    return (
        mime.startswith("text/")
        or mime.endswith(("+json", "+xml", "+yaml"))
        or mime in {"application/json", "application/xml", "application/yaml"}
    )

def extract_resource_payload(uri_str, resource_data, mime_type):
    if isinstance(resource_data, bytes):
        if is_text_mime(mime_type):
            return resource_data.decode("utf-8")
        else:
            # 返回一个清晰的二进制描述符，而不是传输破坏上下文的原始字节
            size_kb = len(resource_data) / 1024
            return (
                f"[Binary resource: {mime_type or 'application/octet-stream'}, "
                f"{size_kb:.2f} KB. This is not text and cannot be inlined; "
                f"open it with a client that handles its media type.]"
            )
    return str(resource_data)

def handle_tool_calls(state):
    messages = state["messages"]
    last_message = messages[-1]
    new_messages = []
    
    if not last_message.tool_calls:
        return {"messages": []}
        
    for tool_call in last_message.tool_calls:
        if tool_call["name"] == "read_resource":
            uri = str(tool_call["args"].get("uri", ""))
            resource = resources_content.get(uri)
            
            if resource:
                # 根据 MIME 类型安全地解析资源内容
                raw_content = resource["content"]
                mime = resource.get("mime_type", "text/plain")
                resolved_text = extract_resource_payload(uri, raw_content, mime)
                
                new_messages.append({
                    "role": "tool",
                    "name": "read_resource",
                    "content": resolved_text,
                    "tool_call_id": tool_call["id"],
                })
            else: # 优雅处理未找到资源的情况
                available_uris = list(resources_content.keys())
                new_messages.append({
                    "role": "tool",
                    "name": "read_resource",
                    "content": f"Resource '{uri}' not found. Available URIs: {available_uris}",
                    "tool_call_id": tool_call["id"],
                })
    
    return {"messages": new_messages}

   ┌─────────────────┐
   │   用户输入消息   │
   └────────┬────────┘
            │
            ▼
   ┌──────────────────────────────────────────┐
   │ 系统提示词 = 仅包含资源目录 (Catalog)     │
   │ (仅包含 URI 与描述，不包含内容)            │
   └────────┬─────────────────────────────────┘
            │
            ▼
      ┌───────────────┐
      │   LLM 自主决策 │
      └──┬─────────┬──┘
         │         │
 需要读取│         │ 不需要读取
 资源内容│         └──────────────► 直接输出回答
         ▼
 ┌──────────────────────────┐
 │ tool_use: read_resource  │
 │        (uri)             │
 └────────────┬─────────────┘
              │
              ▼
 ┌──────────────────────────────┐
 │ 运行图 (Graph) 拦截该工具调用 │
 │ (自动批准，无需人工介入审核)   │
 └────────────┬─────────────────┘
              │
              ▼
 ┌──────────────────────────────┐
 │ 在本地缓存 Map 中检索 URI     │
 └───────┬───────────────┬──────┘
         │ 文本类型      │ 二进制类型
         ▼               ▼
 ┌────────────────┐  ┌──────────────────────┐
 │ 填充完整文本   │  │ 填充描述符：          │
 │ 作为工具消息返回│  │ MIME 类型与文件大小  │
 └───────┬────────┘  └───────────┬──────────┘
         │                       │
         └───────────┬───────────┘
                     │
                     ▼
              (返回给 LLM ──► 生成最终回答)