金大哥 - ap-mcp-server MCP 详情

article

README

🚀 美联社媒体API MCP服务器

这是一个非官方的模型上下文协议（MCP）服务器，它将美联社媒体API转化为一个针对AI优化的内容智能资源。该MCP服务器拥有26个强大的工具，使对话式AI应用程序能够通过自然语言接口无缝访问、分析和与美联社的全面新闻内容进行交互。

适用场景：对话式AI助手、新闻分析应用程序、内容研究工具和自动化新闻工作流程。

⚠️ 重要提示

有关美联社媒体API的更多信息，请访问美联社开发者文档。

✨ 主要特性

🤖 对话式AI特性

自然语言查询处理：将对话式查询转换为优化的美联社API搜索
智能提示模板：为常见工作流程和用例提供17个预配置的提示
智能内容推荐：由AI驱动的内容发现和相关文章建议
趋势分析：实时检测和分析热门话题
智能查询优化：自动增强查询以获得更好的搜索结果
计划执行：自动将内容过滤到授权的计划项目（可通过AP_ENFORCE_PLAN配置）
AI错误恢复：具有建议操作和重试指导的自我修复错误提示
速率限制智能：自动检测速率限制并进行退避，同时提供重试提示
查询建议：为广泛搜索提供智能查询优化建议

📈 性能与扩展性

批量操作：单次操作可处理多达2000个搜索结果和50个项目
智能缓存：基于TTL的缓存系统，提高性能
自动分页：通过自动分页无缝处理大型结果集
生产就绪：具备企业级的性能和可靠性

📰 完整的内容智能

26个综合工具：全面覆盖美联社媒体API功能
实时内容馈送：实时访问美联社的突发新闻和更新
高级搜索：支持多参数搜索，具有灵活的过滤和排序功能
内容监控：创建和管理自动化的内容警报和监控

🛡️ 企业级基础

完全类型安全：使用基于OpenAPI的类型实现完整的TypeScript
强大的错误处理：优雅地处理API错误、速率限制和网络问题
安全配置：基于环境的配置，并进行验证
全面测试：通过单元测试和集成测试实现高测试覆盖率

🚀 快速开始

前提条件

Node.js 18+
美联社API密钥（可在api.ap.org获取）

安装

Claude Code（CLI）

将以下内容添加到你的Claude Code MCP配置中：

{
    "mcpServers": {
        "ap-media": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "ap-mcp-server@latest"],
            "env": {
                "AP_API_KEY": "your_api_key_here"
            }
        }
    }
}

Visual Studio Code等

对于VS Code、Windsurf、Cursor、Void和其他基于VS Code的编辑器，将以下服务器定义添加到你的工作区MCP设置（.vscode/mcp.json）中：

{
    "servers": {
        "ap-media": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "ap-mcp-server@latest"],
            "env": {
                "AP_API_KEY": "your_api_key_here"
            }
        }
    }
}

通用MCP客户端配置

适用于Claude Desktop、ChatGPT Desktop、OpenAI Codex等大多数与MCP兼容的AI工具，使用以下标准配置格式：

{
    "mcpServers": {
        "ap-media": {
            "command": "npx",
            "args": ["-y", "ap-mcp-server@latest"],
            "env": {
                "AP_API_KEY": "your_api_key_here"
            }
        }
    }
}

🤖 AI与大语言模型集成

美联社MCP服务器旨在通过MCP协议直接供AI工具、聊天机器人和大语言模型应用程序使用。AI助手可以使用自然语言访问美联社的新闻内容：

自然语言AI交互

“查找近期关于医疗保健领域人工智能的文章”
“展示本周科技领域的热门话题”
“获取有关气候变化的最新突发新闻”
“查找与这篇关于可再生能源的报道相关的文章”

AI工具会自动将这些请求转换为相应的MCP工具调用。

智能内容发现

趋势检测：自动识别新闻中的热门话题
内容推荐：获取AI推荐的相关文章和主题
查询增强：将模糊的查询转换为精确、优化的搜索
批量分析：处理大量内容以进行模式识别

AI应用类型

新闻聊天机器人：具有对话式访问美联社新闻功能的AI助手
研究助手：供记者和研究人员使用的AI工具
分析系统：自动进行新闻趋势和模式分析
内容策划：由AI驱动的内容发现和推荐引擎

📚 详细文档

环境变量

| 属性 | 详情 | |------|------| | 变量 | 是否必需 | 默认值 | 描述 | | AP_API_KEY | ✅ | - | 你的美联社API密钥 | | AP_BASE_URL | 🚫 | https://api.ap.org/media/v | 美联社API基本URL | | AP_TIMEOUT | 🚫 | 30000 | 请求超时时间（毫秒） | | AP_RETRIES | 🚫 | 3 | 失败请求的重试次数 | | AP_ENFORCE_PLAN | 🚫 | true | 对所有内容请求强制执行in_my_plan=true（AI安全功能） | | AP_DEBUG | 🚫 | false | 启用调试日志记录 | | AP_LOG_LEVEL | 🚫 | info | 日志级别（error、warn、info、debug） | | AP_VERBOSE_LOGGING | 🚫 | false | 启用请求/响应日志记录 | | AP_CACHE_ENABLED | 🚫 | true | 启用智能缓存系统 | | AP_CACHE_TTL_TRENDS | 🚫 | 300000 | 热门话题缓存的TTL（5分钟） | | AP_CACHE_TTL_SEARCH | 🚫 | 180000 | 搜索结果缓存的TTL（3分钟） |

💻 使用示例

基本的使用法

{
    "mcpServers": {
        "ap-media": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "ap-mcp-server@latest"],
            "env": {
                "AP_API_KEY": "your_api_key_here"
            }
        }
    }
}

高度な使用法

// 高级场景说明：在需要处理大量数据或进行复杂分析时，可以根据具体需求调整配置参数，如增加批量操作的数量、调整缓存时间等。
{
    "mcpServers": {
        "ap-media": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "ap-mcp-server@latest"],
            "env": {
                "AP_API_KEY": "your_api_key_here",
                "AP_TIMEOUT": "60000", // 增加超时时间
                "AP_RETRIES": "5", // 增加重试次数
                "AP_CACHE_TTL_TRENDS": "600000", // 增加热门话题缓存时间
                "AP_CACHE_TTL_SEARCH": "360000" // 增加搜索结果缓存时间
            }
        }
    }
}

🎯 MCP提示（共17个）

美联社MCP服务器现在包含智能提示模板，可简化复杂操作并优化API使用。这些提示抽象掉了参数的复杂性，为常见工作流程提供了自然语言接口。

🔍 搜索与发现提示

`breaking-news-search`

使用优化参数搜索最新的突发新闻。

参数：topic、hours_ago、location、max_results
示例：“获取过去2小时内关于科技的突发新闻”

`topic-deep-dive`

对特定主题进行全面研究，提供深入报道。

参数：topic、days_back、min_word_count、include_analysis、max_results
示例：“深入研究过去一周内关于气候变化的报道”

`multimedia-search`

查找照片、视频、图形和音频内容。

参数：topic、media_type、days_back、high_quality_only、max_results
示例：“查找过去7天内奥运会的高质量照片”

`regional-coverage`

获取特定地区或位置的全面新闻报道。

参数：location、include_national、include_local、days_back、max_results
示例：“获取加利福尼亚州的所有新闻，包括国家和本地报道”

`smart-search`

使用自然语言查询进行智能搜索，并自动扩展。

参数：query、search_mode、auto_expand
示例：“智能搜索可再生能源创新相关内容”

📊 分析与洞察提示

`trend-analysis`

分析新闻报道中的热门话题和模式。

参数：category、timeframe、location_filter、include_sentiment、max_topics
示例：“分析过去一天内的科技趋势”

`content-recommendations`

根据主题或过往内容获取AI推荐的内容。

参数：based_on、subjects、content_types、location_preference、max_recommendations
示例：“根据人工智能主题获取推荐内容”

`coverage-comparison`

比较不同时间段的新闻报道。

参数：topic、period1_days_ago、period2_days_ago、period_length_days、metrics
示例：“比较上周和本周的选举报道”

`quick-trending`

快速了解当前的热门话题。

参数：max_topics
示例：“展示前10个热门话题”

🔔 监控与警报提示

`create-news-monitor`

为特定新闻主题设置自动化监控。

参数：topic、monitor_name、email、alert_frequency、description
示例：“每30分钟监控一次关于气候变化的突发新闻”

`breaking-alert-setup`

快速设置紧急突发新闻警报。

参数：topics、email、sensitivity
示例：“为地震和海啸新闻设置高敏感度警报”

`list-monitors`

查看所有活动的内容监控及其状态。

参数：include_status、include_history
示例：“列出所有活动的监控及其当前状态”

`manage-monitor`

更新或删除现有的监控。

参数：monitor_id、action、new_email、new_frequency
示例：“将我的气候监控更新为每10分钟检查一次”

📰 工作流程提示

`daily-news-briefing`

生成全面的每日新闻简报。

参数：categories、location、include_breaking、include_trending、include_recommendations
示例：“创建一份专注于科技和商业的每日简报”

`research-workflow`

用于调查主题的全面研究工作流程。

参数：topic、depth、time_range_days、include_multimedia、include_analysis
示例：“对过去30天内的可再生能源进行深入研究”

`content-curation`

为特定受众或目的策划内容。

参数：audience、topics、content_mix、total_items
示例：“为商业受众策划20篇关于人工智能和自动化的内容”

`story-development`

协助撰写具有背景和上下文的报道。

参数：story_topic、story_type、needs
示例：“帮助撰写一篇关于城市农业的专题报道，提供背景信息和专家来源”

🛠️ 可用工具（共26个）

🔍 核心搜索与内容工具

`search_content`

具有灵活过滤和排序选项的高级内容搜索。参数：

query（字符串）：搜索查询
sort（字符串）：排序标准（默认：_score:desc）
page（数字）：页码（从1开始）
page_size（数字）：每页的项目数（最大100）
include/exclude（数组）：字段过滤
pricing（布尔值）：包含定价信息
in_my_plan（布尔值）：仅返回计划内的项目

AI使用场景：当AI工具收到“查找关于医疗保健领域人工智能的文章”这样的请求时，它会自动将其转换为包括查询术语、排序和字段选择在内的适当搜索参数。

`search_content_all`

用于大型结果集（最多2000项）的自动分页搜索。参数：

与search_content相同，但自动处理分页
max_items（数字）：要检索的最大项目数（默认：1000，最大：2000）

适用场景：批量分析、趋势检测、全面研究。

`get_content_item`

通过ID检索特定的内容项。参数：

item_id（字符串，必需）：美联社项目ID
include/exclude（数组）：字段过滤
pricing（布尔值）：包含定价信息

`get_content_bulk`

高效检索多个内容项（最多50项）。参数：

item_ids（数组，必需）：美联社项目ID数组（最大50）
include/exclude（数组）：字段过滤
pricing（布尔值）：包含定价信息

适用场景：批量内容检索、相关文章获取。

`get_content_feed`

访问美联社的实时内容馈送以获取实时新闻。参数：

query（字符串）：过滤查询
page_size（数字）：要返回的项目数
include/exclude（数组）：字段过滤

`get_rss_feeds` 和 `get_rss_feed`

列出并访问你的账户的RSS馈送。 get_rss_feed的参数：

rss_id（数字，必需）：RSS馈送ID
page_size（数字）：每页的项目数
include/exclude（数组）：字段过滤

`get_ondemand_content`

访问你组织的按需队列。参数：

consumer_id（字符串）：消费者标识符
queue（字符串）：队列ID
page_size（数字）：每页的项目数

🤖 AI驱动的智能工具

`optimize_search_query`

使用自然语言处理将自然语言查询转换为优化的美联社API搜索。参数：

natural_query（字符串，必需）：自然语言查询
context（对象）：用于优化的额外上下文

AI使用场景：当AI收到“查找近期关于医疗保健领域人工智能的文章”时，此工具会自动将其转换为具有适当关键字、日期过滤器和内容类型规范的优化美联社API查询。

`analyze_content_trends`

分析新闻内容中的热门话题和模式。参数：

query（字符串）：趋势分析的基础查询
time_range（字符串）：要分析的时间段（“24h”、“7d”、“30d”）
trend_type（字符串）：趋势分析的类型（“topics”、“entities”、“sentiment”）

适用场景：了解新闻模式、识别新兴报道。

`get_content_recommendations`

根据参考项目获取AI推荐的内容。参数：

reference_item_id（字符串）：作为推荐基础的项目ID
recommendation_type（字符串）：“related”、“similar”或“trending”
max_results（数字）：最大推荐数（默认：10）

适用场景：内容发现、相关文章建议。

`get_trending_subjects`

通过缓存快速发现当前的热门话题。参数：

time_window（字符串）：趋势的时间窗口（“1h”、“6h”、“24h”）
category（字符串）：可选的类别过滤器
min_mentions（数字）：最小提及阈值

适用场景：实时趋势监控、内容规划。

📊 账户管理工具

`get_account_info`

获取基本的账户信息和可用的端点。

`get_account_plans`

获取账户计划、权限和使用计量。

`get_account_downloads`

获取下载历史和使用跟踪。参数：

min_date（字符串）：开始日期（YYYY-MM-DD或ISO-8601）
max_date（字符串）：结束日期（YYYY-MM-DD或ISO-8601）
format（字符串）：响应格式（json或csv）

`get_account_quotas`

获取当前的API配额和使用限制。

`get_followed_topics`

列出你关注的主题。

🔔 高级监控工具

`create_monitor`

创建用于自动化警报的内容监控。参数：

name（字符串，必需）：监控名称
description（字符串）：描述
conditions（数组）：监控条件
notify（数组）：通知设置

`list_monitors`

列出所有现有的监控。

`get_monitor`

获取特定监控的详细信息。参数：

monitor_id（字符串，必需）：监控ID

`update_monitor`

更新现有监控的设置。参数：

monitor_id（字符串，必需）：监控ID
updates（对象）：要更新的字段

`delete_monitor`

删除一个监控。参数：

monitor_id（字符串，必需）：监控ID

`get_monitor_status`

检查一个监控的状态。参数：

monitor_id（字符串，必需）：监控ID

`get_monitor_history`

获取一个监控的历史数据。参数：

monitor_id（字符串，必需）：监控ID
start_date（字符串）：历史记录的开始日期
end_date（字符串）：历史记录的结束日期

🔧 实用工具

`build_search_query`

构建具有验证功能的结构化搜索查询。参数：

keywords（数组）：要搜索的关键字
operators（数组）：搜索运算符（AND、OR、NOT）
date_range（对象）：日期范围过滤器
content_types（数组）：内容类型过滤器

`get_content_rendition`

通过使用href URL获取版本来检索文章和媒体的完整内容。参数：

href（字符串，必需）：内容项的版本或链接中的href URL
format（字符串）：所需格式的可选Accept头
encoding（字符串）：文本内容的可选编码偏好

用例：从先前的搜索结果中获取完整的NITF文本、图像、视频、音频文件。 适用场景：访问完整的文章内容、下载媒体文件、获取全文进行分析。

📈 完整的API覆盖

此MCP服务器通过智能增强功能提供了对美联社媒体API的完整覆盖：

内容端点

✅ /content/search - 内容搜索（增强了自动分页和批量操作功能）
✅ /content/{item_id} - 单个项目查找（增强了批量检索功能）
✅ /content/feed - 实时内容馈送
✅ /content/rss - RSS馈送列表
✅ /content/rss/{rss_id} - 特定的RSS馈送
✅ /content/ondemand - 按需队列

账户端点

✅ /account - 账户信息
✅ /account/plans - 计划和权限
✅ /account/downloads - 下载历史
✅ /account/quotas - API配额和使用限制
✅ /account/followedtopics - 关注主题管理

监控端点（完整实现）

✅ /account/monitors/create - 创建内容监控
✅ /account/monitors - 列出所有监控
✅ /account/monitors/{id} - 获取特定监控的详细信息
✅ /account/monitors/{id}/update - 更新监控设置
✅ /account/monitors/{id}/delete - 删除监控
✅ /account/monitors/{id}/status - 监控状态和健康状况
✅ /account/monitors/{id}/history - 监控历史数据

🚀 AI与性能增强

自然语言处理查询处理：将自然语言转换为美联社API查询
智能缓存：基于TTL的缓存以提高性能
批量操作：单次操作可处理多达2000个项目
趋势分析：实时检测和分析热门话题
内容推荐：由AI驱动的内容发现
自动分页：无缝处理大型结果集

📊 性能基准

响应时间：缓存查询的响应时间小于200毫秒
批量处理：每个批量请求最多处理50个项目
自动分页：自动处理多达2000个结果
缓存命中率：热门话题和频繁搜索的缓存命中率约为85%
并发请求：针对高吞吐量应用程序进行了优化

我的计划执行

MCP服务器包括自动计划执行功能，以防止AI代理访问其授权的美联社计划之外的内容。此功能默认启用，以确保安全。

配置：

设置AP_ENFORCE_PLAN=true（默认）以对所有内容请求强制执行计划限制
设置AP_ENFORCE_PLAN=false以允许无限制的内容访问（谨慎使用）

启用后，所有相关的内容请求将自动包含in_my_plan=true，确保AI代理仅访问授权的内容。这可以防止：

意外访问计划外的高级内容
因计划外内容导致的意外API成本
内容许可方面的合规问题

💡 AI使用模式

批量操作工作流程

AI工具可以高效地处理大量新闻内容：

发现热门话题：使用get_trending_subjects识别当前的热门话题
全面搜索：使用search_content_all获取热门话题的广泛结果（最多2000项）
详细分析：使用get_content_bulk检索最相关文章的完整内容（最多50项）

AI驱动的内容发现

AI助手利用多个工具进行智能内容发现：

查询优化：optimize_search_query将自然语言转换为精确的搜索参数
趋势分析：analyze_content_trends提供有关内容模式和新兴报道的见解
内容推荐：get_content_recommendations根据参考内容推荐相关文章

AI应用的监控设置

AI系统可以设置自动化的内容监控：

创建监控：为特定主题、关键字或突发新闻设置内容警报
跟踪性能：监控状态并获取历史数据以了解内容模式
自动警报：当匹配的内容发布时接收通知

缓存与性能优化

服务器实现了智能缓存以优化性能：

缓存类型和TTL

热门话题：5分钟（频繁变化的数据）
搜索结果：3分钟（在新鲜度和性能之间取得平衡）
账户信息：15分钟（相对静态的数据）
监控数据：10分钟（更新频率适中）

缓存配置

# 自定义缓存行为
AP_CACHE_ENABLED=true
AP_CACHE_TTL_TRENDS=300000    # 5分钟（毫秒）
AP_CACHE_TTL_SEARCH=180000    # 3分钟（毫秒）

性能提示

使用批量操作来处理多个项目
启用缓存以处理重复查询
利用热门话题缓存用于实时应用程序
批量处理相关请求以减少API调用
使用自动分页处理大型数据集，而不是手动分页

🔧 技术细节

错误处理

服务器实现了全面的对AI友好的错误处理：

APAPIError：具有状态码和恢复提示的美联社API特定错误
APConfigurationError：具有纠正措施的配置和设置错误
APNetworkError：具有重试指导的网络和连接问题
速率限制：自动重试并进行指数退避，同时提供重试提示
验证：具有清晰错误消息和建议的输入验证
AI恢复提示：所有错误都包含suggested_action、can_retry和alternative_tool属性，以实现自我修复的AI行为

测试

运行测试套件：

npm test

🛡️ 安全

API密钥仅通过环境变量传递
不记录或存储敏感数据
所有请求都使用HTTPS
输入验证防止注入攻击
速率限制防止API滥用

⚠️ 限制与注意事项

美联社API限制

需要具有适当权限的有效美联社API密钥
美联社API实施速率限制（根据计划而异，通过重试逻辑自动处理）
下载历史记录限制为过去365天
日期范围查询最大限制为60天
高级监控功能可能需要高级的美联社API计划

性能考虑

批量操作遵守美联社API的速率限制（自动应用节流）
缓存TTL可以根据你对新鲜度与性能的需求进行自定义
大型结果集（超过1000项）由于自动分页可能需要更长时间
AI驱动的功能在进行复杂的自然语言处理时可能会有轻微延迟

智能限制

search_content_all：最大2000项（可配置）
get_content_bulk：每个请求最多50项
缓存系统通过TTL过期自动管理内存使用
为了获得最佳性能，AI推荐每个请求限制为50条建议

🛠️ 故障排除

常见问题

“AP_API_KEY is required”
- 确保你的.env文件包含AP_API_KEY=your_key_here
- 检查密钥是否有效且处于活动状态
“401 Unauthorized”
- 验证你的API密钥是否正确
- 检查密钥是否具有所需的权限
“Rate limit exceeded”
- 服务器将自动进行退避重试
- 考虑降低请求频率
“Network timeout”
- 增加环境中的AP_TIMEOUT
- 检查网络连接

调试模式

启用调试日志记录：

export AP_DEBUG=true
export AP_LOG_LEVEL=debug
npm start

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

🤝 贡献

分叉仓库
创建功能分支
进行更改
如有必要，添加测试
提交拉取请求

📞 支持

如果你遇到以下相关问题：

此MCP服务器：在GitHub上提交问题
美联社API：通过api.ap.org联系美联社支持
MCP协议：参阅模型上下文协议文档

ap-mcp-server

README

🚀 美联社媒体API MCP服务器

✨ 主要特性

🤖 对话式AI特性

📈 性能与扩展性

📰 完整的内容智能

🛡️ 企业级基础

🚀 快速开始

前提条件

安装

Claude Code（CLI）

Visual Studio Code等

通用MCP客户端配置

🤖 AI与大语言模型集成

自然语言AI交互

智能内容发现

AI应用类型

📚 详细文档

环境变量

💻 使用示例

基本的使用法

高度な使用法

🎯 MCP提示（共17个）

🔍 搜索与发现提示

breaking-news-search

topic-deep-dive

multimedia-search

regional-coverage

smart-search

📊 分析与洞察提示

trend-analysis

content-recommendations

coverage-comparison

quick-trending

🔔 监控与警报提示

create-news-monitor

breaking-alert-setup

list-monitors

manage-monitor

📰 工作流程提示

daily-news-briefing

research-workflow

content-curation

story-development

🛠️ 可用工具（共26个）

🔍 核心搜索与内容工具

search_content

search_content_all

get_content_item

get_content_bulk

get_content_feed

get_rss_feeds 和 get_rss_feed

get_ondemand_content