io.github.cyanheads/guardian-mcp-server

---

Overview

The Guardian's journalism archive (1999–present), via the Guardian Open Platform API. Search full text, browse by section or tag, and fetch complete untruncated articles from any MCP client. Runs as a stdio process or a local Streamable HTTP server.

Tools

Tool	Description
guardian_search	Full-text search across The Guardian's archive with optional section, tag, contributor, and date filters
guardian_get_article	Fetch a single Guardian article by ID with full untruncated body text and metadata
guardian_browse	Browse by section or tag, or discover available sections and tags, across four modes

---

Capability reference

guardian_search _tool

• Boolean query syntax (AND/OR/NOT, quoted phrases) plus optional section, tag, contributor, and from_date/to_date (YYYY-MM-DD) filters
• Sort via order_by: relevance (default), newest, or oldest; paginated with page + page_size (1–50, default 10)
• Body text is HTML-stripped and truncated at 2,000 words with a truncated flag — fetch the complete text via guardian_get_article
• Typed error reasons: unauthorized, no_results, invalid_date, api_error (retryable)
• Zero-result responses carry an enrichment notice echoing the query

---

guardian_get_article _tool

• Input: article_id — the path-slug id field returned by guardian_search or guardian_browse
• Returns complete untruncated body text (HTML stripped), full metadata, contributor list, and pillar/section classification
• truncated: true means the body still exceeded 2,000 words after the full fetch
• Typed error reasons: unauthorized, not_found, api_error (retryable)

---

guardian_browse _tool

• Four modes via mode: section_latest (requires section_id), tag_latest (requires tag_id), list_sections, list_tags
• list_tags takes optional query and tag_type (keyword, contributor, blog, series, tone, type, publication, newspaper-book, newspaper-book-section) — use tag_type=contributor to discover contributor IDs
• Pagination via page + page_size (1–50, default 10) applies to every mode
• Typed error reasons: unauthorized, missing_section_id, missing_tag_id, section_not_found, tag_not_found, api_error (retryable)

---

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Guardian-specific:

• Wraps the Guardian Open Platform API with a free non-commercial developer key
• Full body text extraction — HTML stripped, not just headlines or abstracts
• Contributor ID discovery via guardian_browse mode list_tags with tag_type=contributor
• Section and tag taxonomy browsing (list_sections, list_tags) for filter discovery before searching
• Free tier: 5,000 requests/day, 12 calls/second — the server applies no additional throttling

Agent-friendly output:

• Truncation flags on every article response — signal to call guardian_get_article for the rest
• Typed error reasons across all three tools, each paired with a recovery hint
• total / page / pages on every paginated response so callers can track result scope
• Zero-result enrichment notice on guardian_search echoing the query and suggesting how to broaden

---

Getting started

Add the following to your MCP client configuration file. Register for a free Guardian Open Platform API key at open-platform.theguardian.com/access.

{
  "mcpServers": {
    "guardian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/guardian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GUARDIAN_API_KEY": "your-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "guardian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/guardian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GUARDIAN_API_KEY": "your-api-key"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "guardian-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "GUARDIAN_API_KEY=your-api-key",
        "ghcr.io/cyanheads/guardian-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 GUARDIAN_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• A free Guardian Open Platform API key — register at open-platform.theguardian.com/access. The non-commercial developer tier is free and instant.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/guardian-mcp-server.git

2. Navigate into the directory:

cd guardian-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# Edit .env and set GUARDIAN_API_KEY

---

Configuration

Variable	Description	Default
GUARDIAN_API_KEY	Required. Free developer key from open-platform.theguardian.com/access.	—
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	Port for HTTP server.	3010
MCP_SESSION_MODE	HTTP session mode: stateless, stateful, or auto (resolves to stateful). The server declares stateless; an exported value overrides it.	stateless
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (RFC 5424).	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend.	in-memory
OTEL_ENABLED	Enable OpenTelemetry instrumentation (spans, metrics, completion logs).	false

See .env.example for the full list of optional overrides.

---

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t guardian-mcp-server .
docker run --rm -e GUARDIAN_API_KEY=your-api-key -p 3010:3010 guardian-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/guardian-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

---

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools and initializes the Guardian service.
src/config	Server-specific environment variable parsing (GUARDIAN_API_KEY).
src/mcp-server/tools	Tool definitions (*.tool.ts): guardian_search, guardian_get_article, guardian_browse.
src/services/guardian	Guardian Open Platform API client, normalization, and type definitions.
tests/	Unit and integration tests.
docs/	Design document and directory tree.

---

Development guide

See CLAUDE.md / AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools in the createApp() tools array in src/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

---

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

---

License

Apache-2.0 — see LICENSE for details.

---

Powered by The Guardian.