使用说明

GNews MCP服务器

模型上下文协议（MCP）服务器，用于使用GNews API获取新闻文章和标题。

特性

搜索新闻：使用具有各种过滤选项的关键字搜索新闻文章
头条新闻：根据谷歌新闻排名获取当前趋势头条
综合过滤：按语言、国家、日期范围、类别等筛选
架构验证：使用JSON模式进行完整的输入/输出验证
错误处理：强大的错误处理和有意义的错误消息

安装

先决条件

Python 3.11或更高版本
UV包管理器
GNews API密钥来自新闻.io

从Git安装

uvx --from git+https://github.com/yourusername/gnews-mcp-server gnews-server

地方发展

克隆存储库：

git clone https://github.com/yourusername/gnews-mcp-server.git
cd gnews-mcp-server

安装依赖项：
```
uv sync
```

设置环境变量：

# Create .env file
echo "GNEWS_KEY=your_gnews_api_key_here" > .env

运行测试：
```
uv run python test_server.py
```

配置

环境变量

GNEWS_KEY （必需）：您的GNews API密钥来自新闻.io
DEBUG （可选）：设置为 true 用于调试日志记录

获取GNews API密钥

访问新闻.io
注册一个免费帐户
从仪表板获取API密钥
将其设置为 GNEWS_KEY 环境变量

可用工具

1.搜索_新闻

使用具有各种过滤选项的关键字搜索新闻文章。

参数：

query （必填）：搜索关键字（支持逻辑运算符AND、OR、NOT）
language：2个字母的语言代码（默认值：“en”）-支持的值：ar、zh、nl、en、fr、de、el、hi、it、ja、ml、mr、no、pt、ro、ru、es、sv、ta、te、uk
country：2个字母的国家代码-支持的值：au、br、ca、cn、eg、fr、de、gr、hk、in、ie、jp、nl、no、pk、pe、ph、pt、ro、ru、sg、se、ch、tw、ua、gb、us
in：在“标题”、“描述”、“内容”中搜索（默认：“标题、描述”）
sortby：按“publishedAt”或“相关性”排序（默认：“publishedIt”）
start_date：YYYY-MM-DD格式的开始日期
end_date：YYYY-MM-DD格式的结束日期

返回10篇文章。

例子：

{
  "query": "artificial intelligence",
  "language": "en",
  "country": "us",
  "sortby": "relevance",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

2.get_top_headlines

根据谷歌新闻排名获取当前趋势头条。

参数：

category：类别（“一般”、“世界”、“国家”、“商业”、“技术”、“娱乐”、“体育”、“科学”、“健康”）-默认值：“一般”
language：2个字母的语言代码（默认值：“en”）-支持的值：ar、zh、nl、en、fr、de、el、hi、it、ja、ml、mr、no、pt、ro、ru、es、sv、ta、te、uk
country：2个字母的国家代码-支持的值：au、br、ca、cn、eg、fr、de、gr、hk、in、ie、jp、nl、no、pk、pe、ph、pt、ro、ru、sg、se、ch、tw、ua、gb、us
query：在标题中搜索关键字
start_date：YYYY-MM-DD格式的开始日期
end_date：YYYY-MM-DD格式的结束日期

返回10篇文章。

例子：

{
  "category": "technology",
  "language": "en",
  "country": "us"
}

MCP客户端配置

克劳德桌面

添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "gnews": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourusername/gnews-mcp-server",
        "gnews-server"
      ],
      "env": {
        "GNEWS_KEY": "your_gnews_api_key_here"
      }
    }
  }
}

其他MCP客户端

服务器通过stdio使用标准MCP协议进行通信。有关配置详细信息，请参阅MCP客户端的文档。

查询句法

GNews API支持 query 参数：

短语搜索

"Apple iPhone" -精确短语匹配

逻辑运算符

Apple AND iPhone -这两个术语都必须存在
Apple OR Microsoft -任一术语都必须存在
Apple NOT iPhone -第一学期没有第二学期

复杂查询

(Apple AND iPhone) OR (Google AND Pixel) -复杂的逻辑组合
"machine learning" AND NOT "deep learning" -排除短语

支持的语言

语言	代码	语言	代码
阿拉伯语	ar	意大利语	it
中文	zh	日语	ja
荷兰语	挪威语	否
英语	en	葡萄牙语	pt
法语	法语	俄语	俄语
德语	德语	西班牙语	西班牙语
希腊语	el	瑞典语	sv
印地语	嗨	乌克兰语	英国

支持的国家

国家	代码	国家	代码
澳大利亚	澳大利亚	日本	日本
巴西	br	荷兰	nl
加拿大	加拿大	挪威	否
中国	中国	巴基斯坦	pk
埃及	例如	葡萄牙	pt
法国	法国	新加坡	新加坡
德国	德	西班牙	es
印度	在	瑞典	se
意大利	it	英国	gb
美国	美国	（以及更多…）

测试

服务器包括全面的测试：

# Run all tests
uv run python test_server.py

# Test features:
# - Schema validation
# - Input/output validation  
# - Error handling
# - Tool functionality

发展

项目结构

gnews-mcp-server/
├── gnews_mcp_server/
│   ├── __init__.py
│   ├── __main__.py         # Entry point
│   ├── server.py           # MCP server implementation
│   ├── handlers.py         # Tool implementations
│   └── tools.json          # Tool schemas
├── test_cases.json         # Test definitions
├── test_server.py          # Test framework
├── pyproject.toml          # Project configuration
└── README.md

MCP架构设计规则

此项目遵循MCP JSON模式设计的特定模式：

可选参数模式

✅ 做 -对可选参数使用可为null的联合类型：

{
  "country": {
    "type": ["string", "null"],
    "description": "2-letter country code (optional)",
    "enum": ["us", "gb", "ca", ...]
  }
}

❌ do not 的常用口语形式 -使用 default: null 对于不可为null的类型：

{
  "country": {
    "type": "string",
    "default": null  // Type inconsistency!
  }
}

具有显式默认值的参数

✅ 做 -为参数保留有意义的默认值：

{
  "language": {
    "type": "string", 
    "enum": ["en", "fr", "de", ...],
    "default": "en"
  }
}

所需阵列管理

包含在 required：只有真正强制性的参数
排除 required：所有可选/可空参数
架构验证：在处理程序之前捕获无效输入

处理程序签名匹配

将处理程序函数签名与架构匹配：

async def search_news(query: str,                    # required
                     language: str = "en",           # has default
                     country: str = None,            # nullable optional
                     **kwargs) -> dict:

添加新功能

更新中的工具架构 gnews_mcp_server/tools.json
在中实现工具功能 gnews_mcp_server/handlers.py
将测试添加到 test_cases.json
运行测试： uv run python test_server.py

错误处理

服务器提供全面的错误处理：

验证错误：捕获并报告无效参数
API错误：GNews API错误格式正确
网络错误：连接问题得到妥善处理
架构验证：输入/输出验证确保数据完整性

速率限制

GNews API费率限制取决于您的订阅计划：

自由：每天100个请求
付费计划：可用更高的限制

当超过速率限制时，服务器将返回相应的错误消息。

贡献

分叉存储库
创建要素分支
进行更改
添加新功能的测试
确保所有测试通过
提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

模式验证的好处

此服务器提供增强的架构验证功能：

输入验证：处理前根据JSON模式验证参数
输出验证：验证响应以确保数据完整性
类型安全：使用联合类型正确处理可为null的类型 ["string", "null"]
错误预防：早期捕获的枚举值、日期格式和必填字段无效
一致性行为：所有工具的可预测参数处理

更新日志

v0.1.0

初始版本
搜索新闻功能
头条新闻功能
使用可为null的联合类型进行全面的模式验证
增强的错误处理和输入验证
100%覆盖的完整测试套件