# Research Agent

A practical Python research agent that searches the web with Tavily, organizes results through LangGraph, and uses OpenAI to produce a structured Markdown research report. An MCP server exposes the web-search capability for MCP clients and the MCP Inspector.

## Features

- Real web search with Tavily
- LangGraph workflow: research -> summarize
- OpenAI-based report generation
- Structured findings, analysis, and sources
- Automatic Markdown report saving in `reports/`
- MCP tools: `hello` and `web_search`
- Basic automated tests with pytest
- Secrets excluded from Git with `.gitignore`

## Architecture

```text
User question
     |
     v
LangGraph
     |
     v
Tavily web search
     |
     v
Source normalization
     |
     v
OpenAI synthesis
     |
     v
Markdown report
```

## Requirements

- Python 3.11+
- A Tavily API key
- An OpenAI API key

## Setup on Windows

From the project folder:

```bat
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
```

Create `.env` from `.env.example` and add your own API keys. Never commit `.env`.

## Run

```bat
python -m app.main
```

Enter a research question. The report is printed in the terminal and saved under `reports/`.

## MCP Inspector

Start the MCP Inspector from the project root:

```bat
mcp dev mcp_server\server.py
```

The server exposes:

- `hello(name)`
- `web_search(query)`

## Tests

Run the test suite with:

```bat
pytest -q
```

The tests are designed to validate parsing, report saving, and state structure without requiring a live API request.

## Project structure

```text
research-agent-final/
|-- app/
|   |-- agent.py
|   |-- config.py
|   |-- graph.py
|   |-- main.py
|   `-- state.py
|-- mcp_server/
|   |-- server.py
|   `-- tools.py
|-- tests/
|-- .env.example
|-- .gitignore
|-- README.md
`-- requirements.txt
```

## GitHub checklist

Before pushing to GitHub:

1. Confirm `.env` is not tracked.
2. Confirm `.venv/`, `__pycache__/`, `.pytest_cache/`, and `reports/` are ignored.
3. Run `pytest -q`.
4. Add the project files to Git and make the first commit.

Example:

```bat
git init
git status
git add .
git commit -m "Initial research agent"
```

Do not run `git add .env`.

## Security

API keys belong only in `.env` or another secret manager. Keep `.env` out of GitHub and do not paste API keys into chat or source files.