README.mdā¢4.48 kB
## Guardian News MCP Server
High-performance MCP (Model Context Protocol) server for advanced news analysis using The Guardian API.
This project provides advanced features such as detailed news searches, trend analysis over time, related topic discovery, and full article text extraction. It's designed for speed and efficiency through strategic caching.
### ⨠Key Features
- **Detailed News Search**: Perform sophisticated news searches by combining keywords, specific sections, and date ranges.
- **News Trend Analysis**: Track the volume of news coverage for any topic over time with time-series data.
- **Related Topic Analysis**: Discover related keywords and context by analyzing the most frequent tags in search results.
- **Full Article Text Extraction**: Scrape the full text content from any article URL.
- **High-Performance Caching**: Minimizes API calls and improves response speed with data-specific caches.
### š ļø Tech Stack
- **MCP Framework**: FastMCP
- **Data Validation**: Pydantic
- **HTTP Client**: Requests
- **Web Scraping**: BeautifulSoup4, lxml
- **Caching**: cachetools
- **Date Utilities**: python-dateutil
- **Environment**: Python-dotenv
### š Installation & Setup
1) Install Dependencies
```bash
pip install -r requirements.txt
```
> Note: If you use uv, you can install dependencies with `uv sync`.
2) Set Up Environment Variables
Create a `.env` file in the project's root directory and set your Guardian API key.
```env
GUARDIAN_API_KEY=your_guardian_api_key_here
```
You can get a free API key from The Guardian Open Platform.
3) Run the Server
```bash
python -m src.main
```
### š³ Docker
Build image:
```bash
docker build -t guardian-news-mcp:latest .
```
Run container (pass your API key via env):
```bash
docker run --rm \
-e GUARDIAN_API_KEY=your_guardian_api_key_here \
guardian-news-mcp:latest
```
Compose (optional): see `docker-compose.yml` example.
### š§° Available Tools (API Reference)
#### health
- **Description**: Checks the current status of the service and API key configuration.
- **Parameters**: None
- **Returns**: Service status object
#### search_news_tool
- **Description**: Searches for news articles using various conditions.
- **Parameters**:
- `query` (string, required): The keyword to search for.
- `page_size` (integer, optional): Number of articles (Default: 5, Max: 50).
- `section` (string, optional): Section to search within (e.g., `technology`).
- `from_date` (string, optional): Start date (YYYY-MM-DD).
- `to_date` (string, optional): End date (YYYY-MM-DD).
- **Returns**: Array of article objects
#### get_sections_tool
- **Description**: Retrieves a list of all available news sections for searching.
- **Parameters**: None
- **Returns**: Array of section objects
#### get_full_article_text_tool
- **Description**: Extracts the full body text from a given article URL.
- **Parameters**:
- `url` (string, required): Full URL of the article to scrape.
- **Returns**: Object containing the article URL and its full text
#### get_news_trend_tool
- **Description**: Analyzes the monthly news coverage trend for a specific keyword.
- **Parameters**:
- `query` (string, required): Keyword to analyze.
- `start_date` (string, required): Start date (YYYY-MM-DD).
- `end_date` (string, required): End date (YYYY-MM-DD).
- **Returns**: Array of objects `{ period: YYYY-MM, article_count: number }`
#### get_related_topics_tool
- **Description**: Analyzes and returns the most frequent related topics (tags) for a given keyword.
- **Parameters**:
- `query` (string, required): Keyword to analyze.
- `page_size` (integer, optional): Number of recent articles to analyze (Default: 20).
- **Returns**: Array of `{ topic, count }`
#### get_tool_definitions
- **Description**: Provides the JSON definitions for all tools currently available on the server.
- **Parameters**: None
### š Project Structure
```text
mcp-guardian-news/
āāā src/
ā āāā __init__.py
ā āāā main.py # Main MCP server file
ā āāā tools.py # Tools for calling the Guardian API
āāā .env # Environment variables file (API Key, etc.)
āāā requirements.txt # Python dependencies
āāā pyproject.toml # Project configuration
āāā .gitignore # Git ignore file
āāā README.md # Project documentation
```
### š License
This project is licensed under the MIT License.