guardian-mcp-server

---

概要

The Guardian の報道アーカイブを、1999年から現在まで検索できます。全文検索、セクションやタグによる閲覧、個別記事の取得が可能です。

ツール

ツール	説明
guardian_search_articles	The Guardian のアーカイブを全文検索します。セクション、タグ、寄稿者、日付による絞り込みも指定できます
guardian_get_article	ID を指定して Guardian の記事を 1 件取得します。本文とメタデータが含まれます
guardian_browse_content	4 つのモードで、セクションやタグから閲覧したり、利用可能なセクションやタグを確認したりできます

---

機能リファレンス

guardian_search_articles _ツール

• ブール演算子に対応した query 構文（AND／OR／NOT、引用符で囲んだフレーズ）、任意の section／tag／contributor および from_date／to_date（YYYY-MM-DD）フィルターに対応します。order_by は relevance（デフォルト）、newest、oldest から選択できます。page と page_size（1～50、デフォルトは 10）を指定できます
• 記事にはメタデータ、HTML タグを除去した本文、truncated フラグが含まれます。結果には total、page、pages、page_size、order_by が含まれます
• 結果がない場合は no_results、日付が無効な場合は invalid_date で失敗します（日付は実在する暦日である必要があります）
• tag では、カンマ（AND）、パイプ |（OR）、ハイフン -（NOT）、かっこを使用できます。例：environment/climate-crisis|environment/flooding。contributor も指定する場合は、OR 式をかっこで囲んでください

---

guardian_get_article _ツール

• 必須の article_id：guardian_search_articles または guardian_browse_content が返すパススラッグの id
• HTML を除去した本文テキスト、メタデータ、寄稿者、ピラー／セクションの分類、および truncated を返します
• not_found で失敗します

---

guardian_browse_content _ツール

• mode の値は 4 つです：section_latest（section_id が必要）、tag_latest（tag_id が必要）、list_sections、list_tags。記事とタグには page と page_size（1～50、デフォルトは 10）を指定します
• list_tags は任意の query と tag_type（keyword、contributor、blog、series、tone、type、publication、newspaper-book、newspaper-book-section）で絞り込めます。出力には mode、total、一致する results／sections／tags 配列が含まれます
• missing_section_id、missing_tag_id、section_not_found、または tag_not_found で失敗します。tag_id には、検索の tag と同じブール式を指定できます

3 つのツールすべてで、ステータス固有の HTTP エラーも発生します。再試行できないエラーは、unauthorized（401）、access_denied（403）、request_rejected（400）、validation_failed（422）、invalid_request、request_conflict、request_not_found、api_unsupported（501）です。再試行可能なエラーは、api_timeout（408／425／504）、rate_limited（429）、api_error（その他の 5xx）です。各エラーには復旧のヒントが含まれます。

---

特長

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン式の認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログに対応しています。

Guardian 固有の機能：

• 無料の非商用開発者キーを使って Guardian Open Platform API をラップします
• 本文全体のテキストを抽出します。HTML を除去し、見出しや概要だけにとどまりません
• guardian_browse_content の list_tags モードで tag_type=contributor を指定すると、寄稿者 ID を検索できます
• セクションとタグの分類体系を参照（list_sections、list_tags）し、検索前にフィルターを確認できます
• 無料枠は 1 日あたり 5,000 リクエスト、1 秒あたり 12 回の呼び出しです。サーバー側では追加のスロットリングを行いません

エージェントに適した出力：

• 検索と記事を返すブラウズモードではプレビューを 2,000 語までに制限し、truncated を設定します。全文を取得するには guardian_get_article を呼び出してください
• 3 つのツールすべてで、型付きのエラー理由と復旧のヒントを返します
• ページ分割されたすべてのレスポンスに total／page／pages が含まれるため、呼び出し側で結果の範囲を把握できます

---

はじめに

以下を MCP クライアントの設定ファイルに追加します。open-platform.theguardian.com/access で無料の Guardian Open Platform API キーを登録してください。

{
  "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"
      }
    }
  }
}

または npx を使用する場合（Bun は不要です）：

{
  "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"
      }
    }
  }
}

または 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"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動します：

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• 無料の Guardian Open Platform API キー。open-platform.theguardian.com/access で登録してください。非商用の開発者向けプランは無料で、すぐに利用できます。

インストール

1. リポジトリをクローンします：

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

2. ディレクトリに移動します：

cd guardian-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

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

---

設定

変数	説明	デフォルト
GUARDIAN_API_KEY	必須。 open-platform.theguardian.com/access で取得できる無料の開発者キーです。	—
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto（stateful に解決されます）。サーバーは stateless を宣言しますが、エクスポートされた値が優先されます。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
LOGS_DIR	ログファイル用ディレクトリ（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツールの引数と結果をログに記録します。キー名で機密情報をマスキングし、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で上限を設定します。自由形式の値に含まれるシークレットは表示されたままになります。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。	in-memory
OTEL_ENABLED	OpenTelemetry instrumentation（スパン、メトリクス、完了ログ）を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP のベース URL です。トレースには /v1/traces、メトリクスには /v1/metrics が使用されます。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトインの OTLP ログエンドポイントです。指定された値がそのまま使用されます。	—

オプションのオーバーライドの全リストについては、.env.example を参照してください。

---

サーバーの実行

ローカル開発

• ビルドして実行：

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

• チェックとテストを実行：

  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

Dockerfile は、HTTP トランスポート、ステートレスセッションモードをデフォルトとし、/var/log/guardian-mcp-server にログを出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

---

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、Guardian サービスを初期化します。
src/config	サーバー固有の環境変数（GUARDIAN_API_KEY）を解析します。
src/mcp-server/tools	ツール定義（*.tool.ts）：guardian_search_articles、guardian_get_article、guardian_browse_content。
src/services/guardian	Guardian Open Platform API のクライアント、正規化、型定義です。
tests/	ユニットテストと統合テストです。
docs/	設計ドキュメントとディレクトリツリーです。

---

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md / AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を記述しないでください
• リクエスト単位のログ記録には ctx.log を、テナント単位のストレージには ctx.state を使用してください
• 新しいツールは、src/index.ts の createApp() 内にある tools 配列に登録してください
• 外部 API 呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマに沿って返します。不足しているフィールドを捏造しないでください

---

貢献

イシューを歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

---

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。

---

The Guardian 提供。