guardian-mcp-server

---

概述

《卫报》1999 年至今的新闻档案。可进行全文搜索、按栏目或标签浏览，并获取单篇文章。

工具

工具	描述
guardian_search_articles	在《卫报》档案中进行全文搜索，可选按栏目、标签、撰稿人和日期筛选
guardian_get_article	按 ID 获取单篇《卫报》文章及其正文文本和元数据
guardian_browse_content	按栏目或标签浏览，或查看可用栏目和标签；支持四种模式

---

功能参考

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 返回的路径 slug id
• 返回剥除 HTML 后的正文文本、元数据、贡献者、支柱／版块分类以及 truncated
• 失败时返回 not_found

---

guardian_browse_content _工具

• 四种 mode 值：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 相同的布尔表达式。

这三个工具也可能因不同状态而返回 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），以便在搜索前发现筛选条件
• 免费套餐：每天 5,000 次请求，每秒 12 次调用——服务不会额外限流

便于 Agent 使用的输出：

• 搜索和返回文章的浏览模式会将预览限制为 2,000 个词，并设置 truncated；如需全文，请调用 guardian_get_article
• 三个工具均提供带类型的错误原因，每个原因都附有恢复提示
• 每个分页响应都包含 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 提供支持。