Ap MCP Server

🚀 美联社媒体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	✅
AP_BASE_URL	🚫
AP_TIMEOUT	🚫
AP_RETRIES	🚫
AP_ENFORCE_PLAN	🚫
AP_DEBUG	🚫
AP_LOG_LEVEL	🚫
AP_VERBOSE_LOGGING	🚫
AP_CACHE_ENABLED	🚫
AP_CACHE_TTL_TRENDS	🚫
AP_CACHE_TTL_SEARCH	🚫

💻 使用示例

基本的使用法

{
    "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工具可以高效地处理大量新闻内容：

1. 发现热门话题：使用get_trending_subjects识别当前的热门话题
2. 全面搜索：使用search_content_all获取热门话题的广泛结果（最多2000项）
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分钟（更新频率适中）

缓存配置

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

性能提示

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

🔧 技术细节

错误处理

服务器实现了全面的对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条建议

🛠️ 故障排除

常见问题

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. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如有必要，添加测试
5. 提交拉取请求

📞 支持

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

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