使用说明

MCP研究代理

用于运行模型上下文协议（MCP）研究助理的自动化脚本。该项目捆绑了两个入口点：

main_gemini.py -一个由Gemini驱动的代理，负责编排Playwright、Fetch和Files MCP服务器，自动编译Markdown报告，并附加它所触及的源代码。
main_openai.py -OpenAI代理SDK变体，将相同的MCP工具连接到OpenAI运行时，并镜像Markdown报告工作流。

这两条路径都采用自由形式的研究任务，启动所需的MCP服务器，并在本地保存代理的最终报告以供审查或版本控制。

路径	目的
`main_gemini.py`	Gemini实现，具有自定义计划/JSON强制和自动源跟踪功能。
`main_openai.py`	OpenAI代理SDK实现，将Markdown报告保存到沙箱之外。
`requirements.txt`	两个入口点共享的Python依赖关系。
`.env.example`	所需API密钥的模板。复制到 `.env` 在运行任何东西之前。
`agent_report_*.md`	Gemini代理生成的示例输出（默认情况下忽略）。
`openai_agents_sdk_guide.ipynb`	Scratch笔记本浏览OpenAI代理SDK设置。

Python 3.10或更高版本。
Node.js 18+（通过调用Playwright MCP服务器所需） npx).
这 uv 命令行工具（用于启动基于Python的MCP服务器 uvx).从以下位置安装 Astral的发布或通过 pip install uv.
API访问：
- Gemini API密钥(GEMINI_API_KEY)for main_gemini.py.
- OpenAI API密钥(OPENAI_API_KEY)具有代理SDK访问权限 main_openai.py.

创建并激活虚拟环境

python -m venv .venv
.\.venv\Scripts\Activate.ps1

source .venv/bin/activate

安装依赖项
```
pip install -r requirements.txt
```
如果您计划运行OpenAI入口点，请同时安装OpenAI代理SDK：
```
pip install --upgrade openai
```
（确保您有权访问测试版 agents 模块。)
配置环境变量
```
cp .env.example .env
```
填写 GEMINI_API_KEY 和 OPENAI_API_KEY 内部 .env该文件被git忽略；把你的钥匙保密。
验证外部工具
- node --version 应报告>=18。
- uv --version 应可用；否则，请遵循安装说明.

python main_gemini.py "Prompt"

脚本：

从加载环境变量 .env.
启动Playwright的MCP服务器(npx -y @playwright/mcp@latest)，提取(uvx mcp-server-fetch)和文件(uvx mcp-server-files).
强制模型使用JSON操作进行响应，执行请求的工具，并收集遇到的每个URL。
将最终的Markdown写入 agent_report_<slug>_<timestamp>.md 并附加a ## Sources 部分。

报告保存在项目根目录中。因为它们可能很大，并且特定于任务，所以默认情况下git会忽略它们；重命名任何您想保留用于文档的名称。

python main_openai.py "Prompt"

此脚本：

Playwright MCP服务器的第一次运行可以下载浏览器二进制文件；按照出现的任何提示进行操作。

这 .gitignore 文件保存本地工件(.env、虚拟环境、MCP沙盒、生成的报告等）不受版本控制，因此存储库可以安全发布。
如果您更喜欢确定性节点工具，请删除 package-lock 线从 .gitignore 并提交您选择的锁文件。
banoffee.md 示例代理报告展示了生成的Markdown的预期结构。将它们视为示例，或者如果你喜欢干净的历史记录，可以在首次GitHub提交之前将其删除。
openai_agents_sdk_guide.ipynb 使用MCP后端启动OpenAI代理SDK。在Jupyter中打开它(jupyter notebook openai_agents_sdk_guide.ipynb)查看带注释的步骤，或者如果你想在代码旁边发布指南，可以将其导出到Markdown/HTML。