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

Related MCP server: AI Makerspace MCP Demo Server

Architecture

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:

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

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:

mcp dev mcp_server\server.py

The server exposes:

• hello(name)

• web_search(query)

Tests

Run the test suite with:

pytest -q

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

Project structure

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:

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.