News

CI PyPI version Python 3.12+ License: MIT

GHCR

Agentic NewsAPI.org MCP server with semantic search, article versioning, ChromaDB retrieval, and Supabase persistence

Built with FastMCP and mcp-refcache for efficient handling of large data in AI agent tools.

Features

• ✅ Reference-Based Caching - Return references instead of large data, reducing context window usage

• ✅ Preview Generation - Automatic previews for large results (sample, truncate, paginate strategies)

• ✅ Pagination - Navigate large datasets without loading everything at once

• ✅ Access Control - Separate user and agent permissions for sensitive data

• ✅ Private Computation - Let agents compute with values they cannot see

• ✅ Docker Ready - Production-ready containers with Python slim base image

• ✅ GitHub Actions - CI/CD with PyPI publishing and GHCR containers

• ✅ Langfuse Tracing - Built-in observability integration

• ✅ Type-Safe - Full type hints with Pydantic models

• ✅ Testing Ready - pytest with 73% coverage requirement

• ✅ Pre-commit Hooks - Ruff formatting and linting

Quick Start

Prerequisites

• Python 3.12+
• uv (recommended) or pip

Installation

# Clone the repository
git clone https://github.com/l4b4r4b4b4/news-mcp
cd news-mcp

# Install dependencies
uv sync

# Run the server (stdio mode for Claude Desktop)
uv run news-mcp

# Run the server (SSE/HTTP mode for deployment)
uv run news-mcp --transport sse --port 8000

Install from PyPI

# Run directly with uvx (no install needed)
uvx news-mcp stdio

# Or install globally
uv tool install news-mcp
news-mcp --help

Docker Deployment

# Pull and run from GHCR
docker pull ghcr.io/l4b4r4b4b4/news-mcp:latest
docker run -p 8000:8000 ghcr.io/l4b4r4b4b4/news-mcp:latest

# Or build locally with Docker Compose
docker compose up

# Build images manually
docker compose --profile build build base
docker compose build

Using with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "news-mcp": {
      "command": "uv",
      "args": ["run", "news-mcp"],
      "cwd": "/path/to/news-mcp"
    }
  }
}

Using with Zed

The project includes .zed/settings.json pre-configured for MCP context servers.

Project Structure

news-mcp/
├── app/                     # Application code
│   ├── __init__.py          # Version export
│   ├── server.py            # Main server with tools
│   ├── tools/               # Tool modules
│   └── __main__.py          # CLI entry point
├── tests/                   # Test suite
│   ├── conftest.py          # Pytest fixtures
│   └── test_server.py       # Server tests
├── docker/
│   ├── Dockerfile.base      # Python slim base image with dependencies
│   ├── Dockerfile           # Production image (extends base)
│   └── Dockerfile.dev       # Development with hot reload
├── .github/
│   └── workflows/
│       ├── ci.yml           # CI pipeline (lint, test, security)
│       ├── publish.yml      # PyPI trusted publisher
│       └── release.yml      # Docker build & publish to GHCR
├── .agent/                  # AI assistant workspace
│   └── goals/
│       └── 00-Template-Goal/  # Goal tracking template
├── pyproject.toml           # Project config
├── docker-compose.yml       # Local development & production
├── flake.nix                # Nix dev shell
└── .rules                   # AI assistant guidelines

Development

Setup

# Install dependencies
uv sync

# Install pre-commit and pre-push hooks
uv run pre-commit install --install-hooks
uv run pre-commit install --hook-type pre-push

Running Tests

uv run pytest
uv run pytest --cov  # With coverage

Linting and Formatting

uv run ruff check . --fix
uv run ruff format .

Type Checking

uv run mypy app/

Docker Development

# Run development container with hot reload
docker compose --profile dev up

# Build base image (for publishing)
docker compose --profile build build base

# Build all images
docker compose build

Using Nix (Optional)

nix develop  # Enter dev shell with all tools

Configuration

Environment Variables

Variable	Description	Default
LANGFUSE_PUBLIC_KEY	Langfuse public key	-
LANGFUSE_SECRET_KEY	Langfuse secret key	-
LANGFUSE_HOST	Langfuse host URL	https://cloud.langfuse.com

CLI Commands

uvx news-mcp --help

Commands:
  stdio             Start server in stdio mode (for Claude Desktop and local CLI)
  sse               Start server in SSE mode (Server-Sent Events)
  streamable-http   Start server in streamable HTTP mode (recommended for remote/Docker)

# Examples:
uvx news-mcp stdio                          # Local CLI mode
uvx news-mcp sse --port 8000                # SSE on port 8000
uvx news-mcp streamable-http --host 0.0.0.0 # Docker/remote mode

CI/CD Workflow

This project uses a CI-gated workflow to ensure code quality and safe releases:

┌─────────────────────────────────────────────────────────────┐
│  Feature Branch → Open PR                                   │
│         ↓                                                    │
│  CI Runs (lint, test, security)                            │
│         ↓                                                    │
│  ✅ CI Must Pass (enforced by branch protection)           │
│         ↓                                                    │
│  Merge to main                                              │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  CI Re-runs on main                                         │
│         ↓                                                    │
│  Release Workflow waits for CI Success                      │
│         ↓                                                    │
│  Docker Images Built & Pushed to GHCR                       │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  Manually Create GitHub Release                             │
│         ↓                                                    │
│  Publish Workflow verifies Release succeeded                │
│         ↓                                                    │
│  Package Published to PyPI                                  │
└─────────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────────┐
│  CD Workflow deploys (staging/production)                   │
└─────────────────────────────────────────────────────────────┘

Key Safeguards:

• ✅ Branch protection ensures CI passes before merge
• ✅ Tag pushes verify CI passed before building images
• ✅ Publish workflow verifies Release succeeded before PyPI upload
• ✅ CD workflow only deploys after Release completes

Manual Gates:

• 🔒 Creating GitHub Release (allows review before PyPI publish)
• 🔒 Production deployments (requires manual approval)

Publishing

PyPI

Configure trusted publisher at PyPI:

• Project name: news-mcp
• Owner: l4b4r4b4b4
• Repository: news-mcp
• Workflow: publish.yml
• Environment: pypi

Docker Images

Images are automatically published to GHCR on:

• Push to main branch → latest tag
• Version tags (v*.*.*) → latest, v0.0.1, 0.0.1, 0.0 tags

License

MIT License - see LICENSE for details.

Contributing

See CONTRIBUTING.md for development guidelines.

Related Projects

• mcp-refcache - Reference-based caching for MCP servers
• FastMCP - High-performance MCP server framework
• Model Context Protocol - The underlying protocol specification