9a6ac3fd2f
- FastMCP server with deep_research and deep_research_info tools - OpenAI Responses API integration with background polling - Configurable model via DEEP_RESEARCH_MODEL env var - Default: o4-mini-deep-research (faster/cheaper) - Optional FastAPI backend for standalone use - Tested successfully: 80s query, 20 web searches, 4 citations
137 lines
3.1 KiB
Markdown
137 lines
3.1 KiB
Markdown
# MCP Deep Research
|
|
|
|
MCP Server for OpenAI Deep Research API - comprehensive web research with citations.
|
|
|
|
## Overview
|
|
|
|
This MCP server provides access to OpenAI's Deep Research models, which can:
|
|
- Perform extensive web searches
|
|
- Analyze data with code execution
|
|
- Synthesize findings into structured reports
|
|
- Provide citations for all sources
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
cd mcp-deep-research
|
|
uv sync
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Required | Default | Description |
|
|
|----------|----------|---------|-------------|
|
|
| `OPENAI_API_KEY` | Yes | - | Your OpenAI API key |
|
|
| `DEEP_RESEARCH_MODEL` | No | `o4-mini-deep-research-2025-06-26` | Research model to use |
|
|
| `DEEP_RESEARCH_POLL_INTERVAL` | No | `5.0` | Seconds between status polls |
|
|
|
|
### Available Models
|
|
|
|
- `o4-mini-deep-research-2025-06-26` - Faster, cheaper (DEFAULT)
|
|
- `o3-deep-research-2025-06-26` - More thorough, ~$1+ per query
|
|
|
|
## Usage
|
|
|
|
### As MCP Server (stdio)
|
|
|
|
```bash
|
|
OPENAI_API_KEY=your-key uv run python -m mcp_server.server
|
|
```
|
|
|
|
### Standalone FastAPI (optional)
|
|
|
|
```bash
|
|
OPENAI_API_KEY=your-key uv run python -m backend.main
|
|
```
|
|
|
|
Runs on `http://localhost:8002` by default.
|
|
|
|
## MCP Tools
|
|
|
|
### `deep_research`
|
|
|
|
Performs comprehensive web research on a query.
|
|
|
|
**Parameters:**
|
|
- `query` (required): The research question or topic
|
|
- `system_prompt` (optional): Instructions to guide research focus
|
|
- `include_code_analysis` (optional, default: true): Allow code execution for data analysis
|
|
- `max_wait_minutes` (optional, default: 15): Maximum time to wait
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"status": "completed",
|
|
"model": "o4-mini-deep-research-2025-06-26",
|
|
"report_text": "# Research Report\n\n...",
|
|
"citations": [
|
|
{"title": "Source Title", "url": "https://..."}
|
|
],
|
|
"web_searches": 12,
|
|
"code_executions": 2,
|
|
"elapsed_time": 180.5
|
|
}
|
|
```
|
|
|
|
### `deep_research_info`
|
|
|
|
Returns configuration information about the deep research setup.
|
|
|
|
## Integration with CouncilApp
|
|
|
|
The server is configured in `councilapp.backend/packages/server/src/server/session.ts`:
|
|
|
|
```typescript
|
|
"deep-research": {
|
|
command: "/bin/bash",
|
|
args: ["-c", `cd ${MCP_DEEP_RESEARCH_PATH} && uv run python -m mcp_server.server`],
|
|
env: {
|
|
OPENAI_API_KEY: process.env.OPENAI_API_KEY,
|
|
DEEP_RESEARCH_MODEL: process.env.DEEP_RESEARCH_MODEL,
|
|
},
|
|
}
|
|
```
|
|
|
|
## Docker Configuration
|
|
|
|
Set these in your Docker environment or docker-compose.yml:
|
|
|
|
```yaml
|
|
environment:
|
|
- OPENAI_API_KEY=sk-...
|
|
- DEEP_RESEARCH_MODEL=o4-mini-deep-research-2025-06-26 # or o3-deep-research-2025-06-26
|
|
```
|
|
|
|
## Pricing
|
|
|
|
Deep research costs vary based on:
|
|
- Number of web searches performed
|
|
- Code interpreter usage
|
|
- Token consumption
|
|
|
|
Approximate costs:
|
|
- `o4-mini`: Lower cost, faster responses
|
|
- `o3`: ~$1+ per complex query with many web searches
|
|
|
|
## Test Results (2024-12-30)
|
|
|
|
Successfully tested with query: "What is the current population of Tokyo in 2024?"
|
|
|
|
```
|
|
Status: completed
|
|
Model: o4-mini-deep-research-2025-06-26
|
|
Elapsed time: 80.5s
|
|
Web searches: 20
|
|
Citations: 4
|
|
|
|
Report excerpt:
|
|
# Tokyo Population (2024)
|
|
As of late 2024, the official population of Tokyo Metropolis is about 14.2 million people.
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|