ap-mcp-server

美联社媒体 API MCP 服务

这是一个_非官方_的模型上下文协议（MCP）服务，可将美联社媒体 API 转化为面向 AI 优化的内容智能资源。该 MCP 服务提供 26 个强大工具，使对话式 AI 应用能够通过自然语言界面无缝访问、分析和使用美联社的综合新闻内容。

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

说明

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

🔑 主要功能

🤖 对话式 AI 功能

• 自然语言查询处理：将对话式查询转换为经过优化的美联社 API 搜索
• 智能提示词模板：为常见工作流和使用场景预先配置了 17 个提示词
• 智能内容推荐：由 AI 驱动的内容发现和相关文章推荐
• 趋势分析：实时检测和分析热门话题
• 智能查询优化：自动优化查询，提升搜索结果质量
• 计划强制执行：自动将内容筛选为授权计划项目（可通过 AP_ENFORCE_PLAN 配置）
• AI 错误恢复：提供自我修复的错误提示，包括建议操作和重试指引
• 速率限制智能处理：自动检测速率限制并进行退避，同时提供重试提示
• 查询建议：针对宽泛搜索，智能建议如何细化查询

📈 性能与规模

• 批量操作：单次操作最多处理 2,000 条搜索结果和 50 个项目
• 智能缓存：基于 TTL 的缓存系统，提升性能
• 自动分页：通过自动分页无缝处理大型结果集
• 可用于生产环境：具备企业级性能和可靠性

📰 完整内容智能

• 26 个综合工具：全面支持美联社媒体 API 的各项功能
• 实时内容源：实时访问美联社突发新闻和最新动态
• 高级搜索：支持多参数搜索，并可灵活筛选和排序
• 内容监控：创建和管理自动化内容提醒与监控器

🛡️ 企业级基础

• 完整类型安全：完整的 TypeScript 实现，采用基于 OpenAPI 的类型
• 稳健的错误处理：妥善处理 API 错误、速率限制和网络问题
• 安全配置：基于环境变量的配置，并进行验证
• 全面测试：具备较高的测试覆盖率，包含单元测试和集成测试

快速开始

前提条件

• Node.js 18+
• Associated Press 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 与大模型集成

AP MCP Server 专为通过 MCP 协议供 AI 工具、聊天机器人和大模型应用直接使用而设计。AI 助手可以通过自然语言访问 AP 新闻内容：

自然语言 AI 交互

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

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

智能内容发现

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

AI 应用类型

• 新闻聊天机器人：以对话方式访问 AP 新闻的 AI 助手
• 研究助手：面向记者和研究人员的 AI 工具
• 分析系统：自动分析新闻趋势和模式
• 内容策展：由 AI 驱动的内容发现与推荐引擎

配置

环境变量

变量	必填	默认值	描述
AP_API_KEY	✅	-	您的 AP API 密钥
AP_BASE_URL	🚫	https://api.ap.org/media/v	AP 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 分钟）

🎯 MCP 提示词（17 个可用）

AP MCP Server 现已包含智能提示词模板，可简化复杂操作并优化 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 条关于 AI 和自动化的内容”

story-development

借助背景信息和上下文协助开发故事。

• 参数：story_topic、story_type、needs
• 示例：“协助开发一个关于城市农业的专题报道，并提供背景信息和专家来源”

🛠️ 可用工具（共 26 个）

🔍 核心搜索与内容工具

search_content

提供灵活筛选和排序选项的高级内容搜索。

参数：

• query（string）：搜索查询
• sort（string）：排序条件（默认值：_score:desc）
• page（number）：页码（从 1 开始）
• page_size（number）：每页项目数（最多 100）
• include/exclude（arrays）：字段筛选
• pricing（boolean）：是否包含定价信息
• in_my_plan（boolean）：是否仅返回套餐内的项目

AI 用法： 当 AI 工具收到“查找 AI 医疗保健文章”之类的请求时，会自动将其转换为合适的搜索参数，包括查询词、排序方式和字段选择。

search_content_all

用于大量结果集的自动分页搜索（最多 2,000 个项目）。

参数：

• 与 search_content 相同，但会自动处理分页
• max_items（number）：要检索的项目数上限（默认值：1000，最多 2000）

**适用于：**批量分析、趋势检测和全面研究。

get_content_item

通过 ID 检索特定内容项目。

参数：

• item_id（string，必填）：AP 项目 ID
• include/exclude（arrays）：字段筛选
• pricing（boolean）：是否包含定价信息

get_content_bulk

高效检索多个内容项目（最多 50 个）。

参数：

• item_ids（array，必填）：AP 项目 ID 数组（最多 50 个）
• include/exclude（arrays）：字段筛选
• pricing（boolean）：是否包含定价信息

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

get_content_feed

访问实时 AP 内容源，获取实时新闻。

参数：

• query（string）：筛选查询
• page_size（number）：要返回的项目数
• include/exclude（arrays）：字段筛选

get_rss_feeds & get_rss_feed

列出并访问你账户的 RSS 源。

get_rss_feed 的参数：

• rss_id（number，必填）：RSS 源 ID
• page_size（number）：每页项目数
• include/exclude（arrays）：字段筛选

get_ondemand_content

访问你所在组织的 OnDemand 队列。

参数：

• consumer_id（string）：使用者标识符
• queue（string）：队列 ID
• page_size（number）：每页项目数

🤖 AI 驱动的智能工具

optimize_search_query

使用 NLP 将自然语言查询转换为经过优化的 AP API 搜索。

参数：

• natural_query（string，必填）：自然语言查询
• context（object）：用于优化的其他上下文信息

AI 用法： 当 AI 收到“查找近期有关医疗保健领域 AI 的文章”之类的请求时，此工具会自动将其转换为经过优化的 AP API 查询，并设置合适的关键词、日期筛选条件和内容类型。

analyze_content_trends

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

参数：

• query（string）：趋势分析的基础查询
• time_range（string）：分析的时间范围（“24h”、“7d”、“30d”）
• trend_type（string）：趋势分析类型（“topics”、“entities”、“sentiment”）

**适用于：**了解新闻模式、发现新兴报道。

get_content_recommendations

根据参考项目获取 AI 驱动的内容推荐。

参数：

• reference_item_id（string）：用于生成推荐的项目 ID
• recommendation_type（string）：“related”、“similar”或“trending”
• max_results（number）：推荐结果数上限（默认值：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 服务通过智能增强，提供对 AP Media API 的完整覆盖：

内容端点

• ✅ /content/search - 内容搜索（通过自动分页和批量操作增强）
• ✅ /content/{item_id} - 单项查询（通过批量检索增强）
• ✅ /content/feed - 实时内容源
• ✅ /content/rss - RSS 源列表
• ✅ /content/rss/{rss_id} - 特定 RSS 源
• ✅ /content/ondemand - 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 与性能增强

• NLP 查询处理：将自然语言转换为 AP API 查询
• 智能缓存：基于 TTL 的缓存，提升性能
• 批量操作：单次操作最多处理 2,000 个项目
• 趋势分析：实时检测并分析热门话题
• 内容推荐：由 AI 驱动的内容发现
• 自动分页：无缝处理大型结果集

📊 性能基准

• 响应时间：缓存查询低于 200ms
• 批量处理：每个批次请求最多处理 50 个项目
• 自动分页：自动处理最多 2,000 条结果
• 缓存命中率：热门话题和常见搜索约为 85%
• 并发请求：针对高吞吐量应用进行了优化

我的套餐限制

MCP 服务包含自动套餐限制功能，以防止 AI Agent 访问超出其获准 AP 套餐范围的内容。此功能默认启用，以确保安全。

配置：

• 设置 AP_ENFORCE_PLAN=true（默认值），对所有内容请求强制执行套餐限制
• 设置 AP_ENFORCE_PLAN=false，允许不受限制地访问内容（请谨慎使用）

启用后，所有相关内容请求都会自动包含 in_my_plan=true，确保 AI Agent 仅访问获准的内容。这可以防止：

• 意外访问套餐中未包含的高级内容
• 因访问套餐外内容而产生意外 API 费用
• 内容许可方面的合规问题

💡 AI 使用模式

批量操作工作流

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

1. 发现热门话题：使用 get_trending_subjects 找出当前热门话题
2. 全面搜索：使用 search_content_all 获取热门话题的丰富结果（最多 2,000 个项目）
3. 详细分析：使用 get_content_bulk 获取最相关文章的完整内容（最多 50 个项目）

AI 驱动的内容发现

AI 助手借助多种工具智能发现内容：

1. 查询优化：optimize_search_query 将自然语言转换为精准的搜索参数
2. 趋势分析：analyze_content_trends 深入分析内容模式和新兴报道
3. 内容推荐：get_content_recommendations 根据参考内容推荐相关文章

为 AI 应用设置监控

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

1. 创建监控：为特定话题、关键词或突发新闻设置内容提醒
2. 跟踪表现：监控状态并获取历史数据，以了解内容模式
3. 自动提醒：匹配的内容发布时接收通知

缓存与性能优化

该服务通过智能缓存优化性能：

缓存类型与 TTL

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

缓存配置

# Customize cache behavior
AP_CACHE_ENABLED=true
AP_CACHE_TTL_TRENDS=300000    # 5 minutes in milliseconds
AP_CACHE_TTL_SEARCH=180000    # 3 minutes in milliseconds

性能提示

1. 使用批量操作处理多个项目
2. 启用缓存以复用重复查询
3. 利用热门话题缓存支持实时应用
4. 批量处理相关请求，尽量减少 API 调用
5. 对大型数据集使用自动分页，而非手动分页

开发

错误处理

该服务实现了全面且适用于 AI 的错误处理：

• APAPIError：AP API 特定错误，包含状态代码和恢复提示
• APConfigurationError：配置和设置错误，包含纠正措施
• APNetworkError：网络和连接问题，包含重试指导
• 速率限制：自动重试，采用指数退避策略并提供重试等待时间提示
• 验证：输入验证，提供清晰的错误消息和建议
• AI 恢复提示：所有错误都包含 suggested_action、can_retry 和 alternative_tool 属性，支持 AI 自我修复

测试

运行测试套件：

npm test

安全

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

⚠️ 限制与注意事项

AP API 约束

• 需要具有相应权限的有效 AP API 密钥
• AP API 会实施速率限制（因套餐而异，服务会通过重试逻辑自动处理）
• 下载历史记录仅限最近 365 天
• 日期范围查询最多为 60 天
• 高级监控功能可能需要 AP API 高级套餐

性能注意事项

• 批量操作遵守 AP API 速率限制（自动应用流量限制）
• 缓存 TTL 可根据数据新鲜度与性能需求进行自定义
• 大型结果集（>1000 项）可能因自动分页而耗时更长
• AI 驱动的功能在进行复杂自然语言处理时可能略有延迟

智能限制

• search_content_all：最多 2,000 项（可配置）
• get_content_bulk：每次请求最多 50 项
• 缓存系统通过 TTL 过期机制自动管理内存使用
• 为获得最佳性能，每次请求的 AI 建议最多为 50 条

故障排除

常见问题

1. “AP_API_KEY is required”

   • 确保 .env 文件包含 AP_API_KEY=your_key_here
   • 检查密钥是否有效且处于启用状态

2. “401 Unauthorized”

   • 确认 API 密钥正确
   • 检查密钥是否具有所需权限

3. “Rate limit exceeded”

   • 服务将自动采用退避策略重试
   • 可考虑降低请求频率

4. “Network timeout”

   • 在环境中增大 AP_TIMEOUT
   • 检查网络连接

调试模式

启用调试日志：

export AP_DEBUG=true
export AP_LOG_LEVEL=debug
npm start

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

贡献

1. Fork 代码仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交拉取请求

支持

以下问题的处理方式：

• 此 MCP 服务：在 GitHub 上提交 issue
• AP API：通过 api.ap.org 联系 AP 支持
• MCP 协议：参阅 Model Context Protocol 文档