afpnews-mcp-server

关键词

模型上下文协议AFP 新闻 API工具与资源注册AI 助手上下文服务安全会话与令牌

使用说明（Markdown 格式）

项目简介

  • 这是一个基于 Model Context Protocol（MCP）的服务器端实现，专门将 AFP 新闻内容通过工具、资源、Prompts 等形式暴露给 AI 助手或 LLM 客户端，支持通过标准的 MCP 请求/响应进行交互。

主要功能点

  • MCP核心能力：实现资源（Resources）、工具（Tools）和提示模板（Prompts）的注册、解析与渲染，统一通过 MCP 服务对外暴露。
  • 多传输协议：内置两种传输方式，标准输出/输入的 STDIO 传输和基于 HTTP 的 Web传输，方便本地调试和远程部署。
  • 安全与会话管理：通过 JWT 加密/解密实现 token 认证与会话管理，内置 OAuth/DCR 风格的简易认证流，支持令牌刷新和会话清除。
  • AFP 数据接入：使用 afpnews-api 客户端对 AFP 内容进行查询、获取全文和相似文章检索等操作，工具返回格式化的多文档输出。
  • 服务器内聚性：所有工具、资源和 Prompts 通过集中注册实现 MCP 服务的统一能力声明，支持通过客户端发起的 JSON-RPC 请求进行调用。
  • 库化使用：核心定义可作为库在其他运行时直接使用，导出 AFP 定义的工具、Prompts、资源，便于在自有运行时中组装 MCP 服务。

安装与运行

  • 安装与构建

    1. 将仓库克隆到本地并进入目录
    2. 安装依赖并构建：使用你偏好的包管理器执行安装并构建
    3. 运行构建后的服务器文件

  • 运行模式

    • STDIO 传输（本地客户端，如 Claude 桌面端/Code 端）
    • HTTP 传输（多用户远程部署，需额外的鉴权和会话管理）

服务器配置（MCP客户端所需的最小配置，JSON 格式） 请注意，以下是针对 STDIO 传输的典型配置示例，描述了 server 的名称、启动命令、工作目录以及必须的环境变量。MCP 客户端通过该信息启动并与服务器建立连接。 { "mcpServers": { "afpnews": { "name": "afpnews", "command": "node", "args": ["build/index.js"], "cwd": "/absolute/path/to/afpnews-mcp-server", "env": { "APICORE_API_KEY": "your-api-key", "APICORE_USERNAME": "your-username", "APICORE_PASSWORD": "your-password", "APICORE_BASE_URL": "https://api.afp.example" // 如有必要，可选 } // 说明：APICORE_API_KEY 为 AFP API 的访问密钥，APICORE_USERNAME/APICORE_PASSWORD 为 AFP 账户凭证，用于认证并获取访问令牌。 // baseUrl 仅在需要时提供（若 AFP API 不在默认地址）。 } } } 服务器启动后，客户端可通过 MCP 的标准调用向 afp_search_articles、afp_get_article、afp_find_similar、afp_list_facets 等工具发起请求，并可访问 topics 资源和 prompts。

基本使用方法

  • 启动服务器
    • 使用上方的 STDIO 配置在命令行中启动服务器进程，确保 AFP 的凭证已正确设置在环境变量中。
  • 使用 MCP 客户端调用工具与资源
    • 调用 afp_search_articles 进行文章检索，获取摘要输出或 JSON/CSV 结果，支持分页和全文本开关。
    • 调用 afp_get_article 获取指定 UNO 的完整文章文本与元数据。
    • 调用 afp_find_similar 查找与指定 UNO 相似的文章。
    • 调用 afp_list_facets 获取分类或主题的值及其计数，支持预设（如 trending-topics）。
    • 读取 topics 资源，获取 AFP 主题目录。
    • 使用 prompts（daily-briefing、country-news、comprehensive-analysis、factcheck 等）来引导对话，内部会自动引入上述工具。

运行与配置要点

  • 服务器需要 AFP API 的访问密钥，以及一个 AFP 用户名/密码进行初始认证。
  • 生产环境建议使用 HTTPS 以保障传输安全。
  • HTTP 传输模式下，客户端会为每个会话分配独立的会话信息，服务器端会进行会话清理以避免资源泄露。

相关参考

  • 项目实现了完整的 MCP 服务端入口、服务器创建、工具/资源/Prompts 的注册、两种传输模式的实现，以及与 AFP API 的对接逻辑。
  • 测试用例覆盖了核心工具的输出结构、错误处理、JSON/CSV/Markdown 等多种输出格式，以及 HTTP/WS 传输下的行为，确保功能实现的鲁棒性。

常见问题与注意

  • 若要在生产环境中暴露给外部客户端，务必开启 HTTPS，并妥善管理 JWT_SECRET/密钥轮换。
  • HTTP 传输模式需要正确配置 MCP_SERVER_URL、JWT 加解密密钥等，以确保授权和会话的安全性。
  • 当输出内容超过字符限制时，系统会进行截断并附带提示信息，确保长文本不会导致响应异常。

联系与更新

  • 本实现提供了完整的服务器端功能，若后续需要扩展新工具、Prompts 或资源，可在 src 下添加相应的定义并通过注册器暴露到 MCP 服务。

服务器信息

访问项目