OpenAI代理SDK MCP工具
一个模型上下文协议（MCP）服务器，通过从官方文档网站提取和索引内容，为OpenAI代理SDK提供文档：https://openai.github.io/openai-agents-python/
此包可以作为Python库安装，并与任何兼容MCP的LLM客户端（Claude Desktop、VS Code、Cursor等）一起使用。
安装
来自PyPI（推荐）
pip install openai-agents-sdk-mcp来自源头
git clone https://github.com/gavinz0228/openai-agents-sdk-mcp.git
cd openai-agents-sdk-mcp
pip install -e .看 安装.md 了解详细的安装说明。
概述
该项目提供了一个独立的CLI工具和一个MCP服务器，允许LLM智能地访问和查询OpenAI代理SDK文档。
快速入门（MCP服务器）
- 安装软件包:
pip install openai-agents-sdk-mcp- 设置API密钥:
export OPENAI_API_KEY="sk-your-api-key-here"- 配置您的MCP客户端 （例如，克劳德桌面）：
{
"mcpServers": {
"openai-agents-sdk-docs": {
"command": "openai-agents-sdk-mcp",
"env": {
"OPENAI_API_KEY": "sk-your-api-key-here"
}
}
}
}- 开始使用它 -问你的法学硕士：
- “列出所有OpenAI代理SDK文档主题” - “获取交接文件” - “我如何在OpenAI代理中使用流媒体？”
看 安装.md 和 MCP_CONFIGURATION.md 有关详细的设置说明。
特性
1. MCP服务器 （主界面）
为LLM提供两个工具：
list_documentation_topics：获取所有可用文档主题及其URL的完整列表get_documentation：使用自然语言查询搜索和检索文档
2. 自动文档索引
- 获取并解析OpenAI代理SDK文档网站
- 提取所有导航链接和主题
- 创建主题到URL的结构化JSON映射
- 保存到
docs_index.json用于快速访问
2. 智能指数管理
该工具通过智能缓存自动管理文档索引：
- 缺失索引检测：如果满足以下条件，则自动获取新索引
docs_index.json不存在 - 稳定性检查：如果超过1天，则刷新索引（可配置）
- 链接验证：验证所有文档链接是否正常工作
- 断链恢复：如果任何链接断开，则自动重新获取索引
3. AI驱动的功能搜索
使用OpenAI的GPT-4o-mini智能地将用户查询与文档相匹配：
- 接受自然语言查询（例如，“如何跟踪我的代理”）
- 查找最匹配的文档主题
- 获取并显示相关文档内容
- 适用于模糊匹配和会话查询
安装
- 克隆存储库:
git clone https://github.com/gavinz0228/openai-agents-sdk-mcp.git
cd openai-agents-sdk-mcp- 安装软件包:
pip install -e .- 配置API密钥:
创建 .env 工作目录中的文件：
OPENAI_API_KEY=sk-your-api-key-here或者设置为环境变量：
export OPENAI_API_KEY="sk-your-api-key-here"看 安装.md 更多安装选项。
用法
MCP服务器（推荐）
MCP服务器允许LLM通过标准化的工具调用访问文档。
启动服务器
openai-agents-sdk-mcp或者，如果从源代码运行：
python -m openai_agents_sdk_mcp.server配置MCP客户端
添加到您的MCP客户端配置中（例如，Claude Desktop的配置）：
{
"mcpServers": {
"openai-agents-sdk-docs": {
"command": "openai-agents-sdk-mcp"
}
}
}或者，如果安装在虚拟环境中，请使用绝对路径：
{
"mcpServers": {
"openai-agents-sdk-docs": {
"command": "/path/to/.venv/bin/openai-agents-sdk-mcp"
}
}
}可用的MCP工具
list_documentation_topics
- 列出所有可用的文档主题
- 可选参数：
force_refresh（boolean）-强制刷新索引
例子：
{
"name": "list_documentation_topics",
"arguments": {
"force_refresh": false
}
}get_documentation
- 搜索和检索特定功能的文档
- 参数：
- query （字符串，必填）-特征名称或自然语言问题 - include_content （布尔值，可选）-是否包含完整内容（默认值：true）
例子：
{
"name": "get_documentation",
"arguments": {
"query": "handoffs",
"include_content": true
}
}测试服务器
python test_mcp.py命令行接口
使用CLI工具快速查询文档：
# List all documentation topics
openai-agents-docs
# Search for specific documentation
openai-agents-docs "handoffs"
openai-agents-docs "streaming"
openai-agents-docs "how to use guardrails"作为Python库
from openai_agents_sdk_mcp import (
load_or_refresh_index,
get_documentation_for_feature
)
# Load documentation index
doc_map = load_or_refresh_index()
print(f"Found {len(doc_map)} topics")
# Find documentation for a feature
topic, url = get_documentation_for_feature("handoffs")
if topic:
print(f"Topic: {topic}")
print(f"URL: {url}")独立CLI工具（旧版）
如果从源代码运行而不安装：
生成/刷新文档索引
python openai_agents_sdk_mcp.py这将：
- 获取最新的文档结构
- 提取所有主题和链接
- 保存到
docs_index.json - 显示所有可用主题
搜索文档
python openai_agents_sdk_mcp.py "feature name or query"例子:
# Simple feature name
python openai_agents_sdk_mcp.py "handoffs"
# Natural language query
python openai_agents_sdk_mcp.py "how do I stream responses"
# Topic search
python openai_agents_sdk_mcp.py "tracing and debugging"
# Multiple words
python openai_agents_sdk_mcp.py "realtime voice"该工具将：
- 加载或刷新文档索引（如果过时）
- 使用AI找到最匹配的主题
- 显示匹配的主题和URL
- 获取并显示文档内容的预览
运作原理
索引管理
# The index is automatically managed:
# 1. Checks if docs_index.json exists
if not exists:
fetch_fresh_index()
# 2. Checks if index is older than 1 day
if age > 1_day:
fetch_fresh_index()
# 3. Validates all links are working
if broken_links_found:
fetch_fresh_index()AI驱动的匹配
该工具使用OpenAI的GPT-4o-mini将用户查询与文档主题相匹配：
- 从索引中加载所有可用主题
- 将用户查询+主题列表发送到LLM
- LLM确定了最相关的主题
- 返回匹配的主题和URL
这甚至为以下情况提供了智能匹配：
- 拼写错误和拼写错误
- 自然语言问题
- 部分或模糊匹配
- 相关概念
配置
常数（in openai_agents_sdk_mcp.py)
DOCS_INDEX_FILE = "docs_index.json" # Index file name
INDEX_MAX_AGE_DAYS = 1 # Maximum age before refresh环境变量
OPENAI_API_KEY-需要AI驱动的搜索功能
文件
server.py-MCP服务器实现openai_agents_sdk_mcp.py-核心功能和CLI工具test_mcp.py-MCP服务器的测试脚本mcp_config.json-MCP客户端配置示例docs_index.json-缓存文档索引（自动生成）requirements.txt-Python依赖关系.env-环境变量（创建此变量）.gitignore-Git忽略规则（保护API密钥）
依赖项
requests-获取网页的HTTP请求beautifulsoup4-HTML解析lxml-XML/HTML解析器openai-用于AI驱动搜索的OpenAI API客户端python-dotenv-环境变量管理mcp-模型上下文协议SDK
输出示例
索引生成
Fetching OpenAI Agents SDK documentation index...
Fetching fresh documentation index...
Index refreshed with 80 topics and saved to 'docs_index.json'.
Found 80 documentation topics/features:
...特征搜索
Searching for documentation on: handoffs
Loaded existing index with 80 topics.
Verifying documentation links...
✓ All links are valid
✓ Found matching topic: Handoffs
URL: https://openai.github.io/openai-agents-python/handoffs/
Fetching documentation content...
================================================================================
Handoffs - OpenAI Agents SDK
...许可证
该项目旨在与OpenAI代理SDK文档配合使用。有关API的使用，请参阅OpenAI的服务条款。