Hacktoberfest 2026：维护者为十月标记出来的 issue，仍然开放、适合新手。 浏览 Hacktoberfest issue

Docs: local MCP require_approval callable form omitted from docs/mcp.md

已关闭 适合新手
  • 哪里不对？
#5,350 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
1/5
预计耗时
1-3 小时
新手友好度
87/100
Issue 类型
文档
描述清晰度
描述清楚
活跃度
活跃
技术栈
python
领域
documentation

调研方向

阅读 docs/mcp.md 中的 “Approval policies for local MCP servers” 部分，并检查 src/agents/mcp/server.py 中的 callable 类型和构造函数 docstring。记录 (run_context, agent, tool) -> bool | Awaitable[bool] 这种形式，注明 tool 是带有 annotations 的 MCP SDK Tool，以及没有可用 agent 时文档所述的行为。文档清楚说明支持的形式和 callable 行为后即为完成。

由索引模型根据 Issue 内容生成。

描述

Please read this first
  • Have you read the docs? Yes — MCP docs and Human-in-the-loop
  • Have you searched for related issues? Yes. #5315 asks to expose MCP ToolAnnotations on converted FunctionTool for hooks. This issue is separate: the callable require_approval policy that already receives the original MCP Tool (including annotations) is implemented but not documented in docs/mcp.md.
Describe the docs gap

docs/mcp.md → Approval policies for local MCP servers lists these supported forms for require_approval on MCPServerStdio / MCPServerSse / MCPServerStreamableHttp:

  • "always" / "never"
  • True / False
  • per-tool map
  • grouped {always, never} object

It omits the callable form that the public type and constructor docstring already accept.

Exact doc path
  • docs/mcp.md — section starting at “Approval policies for local MCP servers” (Supported forms list)
  • Cross-link: docs/human_in_the_loop.md mentions local MCP require_approval but does not show the callable signature either
  • Examples under examples/mcp/ only demonstrate string/dict policies (get_all_mcp_tools_example, tool_filter_example)
Evidence in source (current main)

Type alias in src/agents/mcp/server.py:

LocalMCPApprovalCallable = Callable[
    [RunContextWrapper[Any], "AgentBase", MCPTool],
    MaybeAwaitable[bool],
]

Constructor docstring on MCPServer:

Accepts "always"/"never", a dict of tool names to those values, a boolean, an object with always/never tool lists … or a sync/async callable that receives (run_context, agent, tool) and returns whether the tool call needs approval.

_normalize_needs_approval accepts callables, and _get_needs_approval_for_tool invokes policy(run_context, agent, tool) with the original MCP Tool — so callers can read tool.annotations (e.g. destructiveHint / readOnlyHint) without a parallel list_tools() cache.

Minimal illustration of the undocumented form
from mcp.types import Tool
from agents.mcp import MCPServerStreamableHttp

def approve_destructive(run_context, agent, tool: Tool) -> bool:
    hints = tool.annotations
    # Require HITL when the server marks the tool destructive (or omits read-only).
    if hints and hints.read_only_hint:
        return False
    return bool(hints is None or hints.destructive_hint is not False)

server = MCPServerStreamableHttp(
    name="crm",
    params={"url": "http://localhost:8000/mcp"},
    require_approval=approve_destructive,  # valid API; missing from docs/mcp.md Supported forms
)
Expected docs change
  1. Add the callable form to the Supported forms list in docs/mcp.md, with the signature (run_context, agent, tool) -> bool | Awaitable[bool] and a note that tool is the MCP SDK Tool (annotations available).
  2. Optionally add a short example next to the existing dict example, and/or one line in docs/human_in_the_loop.md pointing at it.
  3. Note the fail-closed behavior when a callable policy is used without an agent (documented in _get_needs_approval_for_tool).

Happy to refine wording if maintainers prefer a different example shape. Because this repo accepts issues (not external PRs) for docs, filing here rather than opening a PR.

主要语言
Python
星标
30k
派生
4.9k
平均合并
16 小时 25 分钟
30 天内合并 PR
220

环境准备

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

openai/openai-agents-python 的其他 Issue

查看 openai/openai-agents-python 的全部 Issue

相似的 Issue

更多 Python Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。