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協議：參閱模型上下文協議文檔