lizTheDeveloper/bluesky_bluereport

Blue Report MCP Server

A simple, fast MCP server that provides access to top news stories from The Blue Report - the top links on Bluesky, updated hourly.

Features

• Three Time Periods: Get news for hourly, daily, or weekly periods
• Structured Output: Clean, structured data with headlines, summaries, and URLs
• Fast Performance: Minimal overhead with response times under 2 seconds
• Real-time Data: Fetches live data from The Blue Report website
• Error Handling: Graceful fallbacks when the website is unavailable

Prerequisites

• Python 3.11 or higher
• uv package manager

Installation

1. Clone the repository:

   git clone <repository-url>
   cd bluesky_bluereport
   

2. Install dependencies with uv:

   uv sync
   

Usage

Development Mode

Test the server with MCP Inspector:

uv run mcp dev server.py

This will start the MCP Inspector at http://127.0.0.1:6274 where you can test the tools.

Claude Desktop Integration

Install the server in Claude Desktop:

uv run mcp install server.py

Direct Execution

Run the server directly:

uv run python server.py

Testing

Run the test script to verify functionality:

uv run python test_server.py

Available Tools

1. get_hourly_news()

Get the top news stories from The Blue Report for the past hour.

2. get_daily_news()

Get the top news stories from The Blue Report for the past 24 hours.

3. get_weekly_news()

Get the top news stories from The Blue Report for the past 7 days.

Data Structure

Each tool returns a NewsResponse with:

{
    "stories": [
        {
            "headline": "Story headline",
            "summary": "Story summary with source and engagement",
            "published_at": "2025-01-27T10:00:00",
            "source": "The Blue Report",
            "url": "https://example.com/story",
            "category": "Bluesky Trending"
        }
    ],
    "count": 10,
    "time_period": "daily",
    "retrieved_at": "2025-01-27T10:00:00"
}

Architecture

• FastMCP Server: Main server implementation using FastMCP
• Blue Report Client: HTTP client for website scraping
• Data Models: Pydantic models for structured output
• HTML Parser: BeautifulSoup for parsing The Blue Report website
• Error Handling: Graceful fallbacks and logging

Performance

• Server startup: < 5 seconds
• Tool response: < 2 seconds
• Memory usage: < 50MB
• Dependencies: 5 packages

Dependencies

Managed by uv in pyproject.toml:

• mcp[cli]>=1.12.3 - MCP SDK
• httpx>=0.28.1 - HTTP client
• pydantic>=2.11.7 - Data validation
• beautifulsoup4>=4.13.4 - HTML parsing
• requests>=2.31.0 - HTTP requests

Development

Project Structure

bluesky_bluereport/
├── plans/
│   ├── requirements.md
│   └── plan.md
├── devlog/
│   └── mcp_server_development.md
├── src/
│   ├── __init__.py
│   ├── server.py
│   ├── blue_report.py
│   └── models.py
├── pyproject.toml
├── server.py
├── test_server.py
└── README.md

Development Commands

# Install dependencies
uv sync

# Run tests
uv run python test_server.py

# Start MCP Inspector
uv run mcp dev server.py

# Install in Claude Desktop
uv run mcp install server.py

# Add new dependency
uv add package-name

# Add dev dependency
uv add --dev package-name

Adding New Features

1. Update requirements in plans/requirements.md
2. Implement changes in src/ modules
3. Test with uv run python test_server.py
4. Update development log in devlog/
5. Test with MCP Inspector

License

MIT License - see LICENSE file for details.