业务系统继续负责真实业务
MCP Server 负责把业务能力包装成 Agent 能发现、能调用、能审计的能力
MCP Client 负责在 Agent 侧连接并使用这些能力

run_command(command: string)

search_notes(keyword: string, limit: integer)
read_note(path: string)
create_study_task(title: string, source_note: string, due_date?: string)

final class McpToolDefinition {
    String name;                 // 工具名，必须稳定，改名等于破坏协议
    String description;          // 给模型看的用途说明，决定模型会不会选它
    JsonSchema inputSchema;      // 参数结构，服务端必须二次校验
    ToolRiskLevel riskLevel;     // READ_ONLY / WRITE / DANGEROUS
}

final class McpToolResult {
    boolean ok;                  // 是否执行成功
    String message;              // 给模型看的简短解释
    Object data;                 // 结构化结果，不要只塞自然语言
    List<String> evidencePaths;  // 如果读取资料，返回来源路径
}

{
  "name": "search_notes",                 // 稳定工具 ID，改名会破坏调用方
  "description": "Search allowed Obsidian notes by keyword.",
  "inputSchema": {
    "type": "object",                       // arguments 必须是对象，不能直接传字符串
    "required": ["keyword"],              // 必填字段越少越好，但必须明确
    "properties": {                           // 每个字段都要限定类型和边界
      "keyword": {
        "type": "string",                  // keyword 是检索文本，不允许数组或对象
        "minLength": 2,                       // 太短会产生大量噪声召回
        "maxLength": 80,                      // 太长说明用户可能传了整段 prompt
        "description": "Search keyword or phrase."
      },
      "limit": {
        "type": "integer",                 // limit 必须是整数，便于限制返回量
        "minimum": 1,                         // 至少返回一个候选
        "maximum": 20,                        // 防止一次读取过多上下文
        "default": 5
      },
      "scope": {
        "type": "string",                  // keyword 是检索文本，不允许数组或对象
        "enum": ["ai-agent", "all-allowed"],
        "default": "ai-agent"
      }
    },
    "additionalProperties": false          // 拒绝模型幻觉出来的多余字段
  }
}

final class McpError {
    String code;          // 稳定错误码，例如 ARGUMENT_INVALID
    String message;       // 给模型看的简短原因
    boolean retryable;    // 是否允许 Agent 换参数或稍后重试
    String field;         // 哪个参数出错，没有则为空
    String traceId;       // 对应服务端审计日志
}