STARWARCLOUD STARWAR.AI
返回市场
新闻API MCP服务器

新闻API MCP服务器

作者：Malachi-devel4 星标更新：2025-05-22
安装使用来源：spider==github.com

项目介绍

新闻聚合API（MCP服务器）

这是一个使用MCP服务器规范和TypeScript构建的模块化、可扩展的新闻聚合后端。此API提供了一个统一的接口来访问TheNewsAPI中的当前和历史新闻文章，并具有高级过滤功能。该API特别设计用于供AI代理消费，优先考虑结构化数据和一致的模式。

功能

  • 统一API：访问新闻数据的一致接口
  • TypeScript：完全类型化的可靠开发
  • MCP架构：具有关注点分离的可扩展、模块化设计
  • 多个端点：访问各种类型的新闻内容
  • 环境变量：安全配置管理
  • 错误处理：带有适当状态码的一致错误格式
  • 过滤：支持多种过滤参数
  • 缓存：智能缓存系统及管理端点
  • 交互式文档：基于Swagger的API文档
  • 机器友好响应：优化用于机器消费的结构化数据

端点

新闻端点

端点描述示例
/api/news/top获取顶级新闻头条/api/news/top?categories=business
/api/news/all获取所有新闻并进行高级搜索/api/news/all?search=technology
/api/news/similar/:uuid获取与特定文章相似的文章/api/news/similar/cc11e3ab-ced0-4a42-9146-e426505e2e67
/api/news/uuid/:uuid根据UUID获取特定文章/api/news/uuid/cc11e3ab-ced0-4a42-9146-e426505e2e67
/api/news/sources获取可用的新闻来源/api/news/sources?language=en

缓存管理端点

端点描述示例
/api/cache/stats获取缓存统计信息/api/cache/stats
/api/cache/clear清除所有缓存DELETE /api/cache/clear
/api/cache/clear/:type按类型清除缓存DELETE /api/cache/clear/top

工具端点

端点描述
/health健康检查端点
/docs交互式API文档
/docs.jsonOpenAPI规范
/examples使用示例

测试

该项目实施了多层次测试策略，以确保可靠性和正确性。

测试类型

  1. 单元测试

    • 对单个组件进行隔离测试
    • 使用模拟依赖项实现真正的单元隔离
    • 关注业务逻辑验证

  2. 控制器测试

    • 验证控制器行为，使用模拟服务
    • 测试正确的请求处理和响应格式
    • 确认错误处理模式的一致性

  3. 集成测试

    • 测试完整的请求-响应周期
    • 使用supertest验证API端点
    • 模拟外部API调用以保证可靠性

测试最佳实践

该项目遵循以下测试最佳实践：

  • 隔离 - 测试不依赖于彼此或外部服务
  • 可重复性 - 在任何环境中都能产生相同的结果
  • 快速 - 模拟外部依赖项使测试高效
  • 全面性 - 核心功能有高覆盖率
  • 可维护性 - 测试遵循一致的模式和结构

运行测试

# 运行所有测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 运行特定测试文件
npx jest path/to/test.ts

安装

# 克隆仓库
git clone <repository-url>

# 安装依赖
npm install

# 设置环境变量
cp .env.example .env
# 编辑.env文件，添加自己的API密钥和数据库URL

# 生成Prisma客户端
npx prisma generate

# 构建项目
npm run build

# 启动服务器
npm start

配置

创建一个包含以下变量的.env文件：

# 新闻聚合API环境变量

# API配置
NEWS_API_TOKEN=your_api_token_here

# 服务器配置
PORT=3000
NODE_ENV=development

# 数据库配置
DATABASE_URL="file:./dev.db"

数据库配置

应用程序默认使用Prisma ORM和SQLite。DATABASE_URL环境变量应指向您的数据库文件。对于生产环境，您可以将其配置为使用PostgreSQL或MySQL。

开发

# 在开发模式下运行，启用热重载
npm run dev

# 运行代码检查
npm run lint

# 运行测试
npm test

测试基础设施

项目包括一个使用Jest和Supertest构建的综合测试套件，覆盖API端点、数据库集成和服务器连接检查。

运行测试

# 运行所有测试
npm test

# 只运行API端点测试
npm run test:api

# 只运行数据库集成测试
npm run test:db

# 运行带覆盖率报告的测试
npm run test:coverage

# 在监视模式下运行测试（适用于开发）
npm run test:watch

# 检查服务器连接
npm run check-server

测试结构

  • API端点测试：位于src/__tests__/api/，这些测试验证所有API端点返回预期响应，正确处理错误，并应用适当的过滤。
  • 数据库集成测试：位于src/__tests__/database.test.ts，这些测试验证数据库连接、查询执行和事务支持。
  • 服务器连接脚本：位于scripts/check-server.ts，此脚本测试到正在运行的服务器实例的连接，验证关键端点是否正常工作。

测试环境

测试使用通过设置NODE_ENV=test指定的单独环境配置。这确保测试不会干扰开发或生产环境。设置包括：

  • 自动数据库连接设置和拆卸
  • 测试之间清除缓存以确保隔离
  • 启动和关闭服务器以测试端点

未来增强待办事项列表

优先级1：基础改进

  • 缓存系统

    • 实现内存缓存
    • 缓存频繁访问的数据如顶级新闻和来源
    • 添加缓存失效策略
    • 配置不同内容类型的TTL（生存时间）
    • 添加缓存管理端点

  • 数据持久层

    • 添加数据库集成（使用Prisma的SQLite）
    • 创建存储增强文章元数据的模式
    • 实现数据访问的仓库模式
    • 添加迁移系统以应对模式更改

  • API文档

    • 生成OpenAPI/Swagger规范
    • 添加交互式API文档
    • 为每个端点创建使用示例

API文档

API现在包括使用OpenAPI/Swagger的综合文档：

  • 交互式API文档：在服务器运行时可在/docs访问
  • OpenAPI规范：JSON格式在/docs.json可用
  • 使用示例：在/examples可用，附有多语言代码示例

如何访问文档

  1. 使用npm run dev或npm start启动服务器
  2. 打开浏览器至http://localhost:3000/docs查看交互式Swagger UI
  3. 浏览可用的端点、请求参数和响应格式
  4. 在http://localhost:3000/examples参考实现示例

API文档特性

  • 完整的端点描述，包括参数和响应类型
  • 交互式“尝试”功能，可以直接测试端点
  • 请求/响应模式定义
  • API消费的代码片段
  • 与MCP服务器架构集成的示例

优先级2：安全性和性能

  • 身份验证和用户管理

    • 实现基于JWT的身份验证
    • 创建用户注册和登录端点
    • 添加基于角色的访问控制
    • 实现安全密码处理

  • 速率限制

    • 添加请求节流中间件
    • 实现分层访问级别
    • 创建公平使用政策
    • 在响应中添加速率限制头

  • 监控和分析

    • 设置请求日志和监控
    • 添加性能指标收集
    • 创建使用仪表板
    • 实现错误跟踪和警报

优先级3：增强功能

  • 内容处理

    • 添加文本摘要能力
    • 实现实体提取
    • 添加情感分析
    • 创建超越来源类别的主题分类
    • 实现重复检测和分组

  • 个性化

    • 添加用户偏好跟踪
    • 根据阅读历史创建个性化端点
    • 实现主题跟随功能
    • 添加推荐引擎

  • Webhook和实时更新

    • 实现Webhook注册
    • 创建基于事件的通知系统
    • 添加SSE（服务器发送事件）以实现实时更新
    • 实现主题订阅功能

贡献

欢迎对新闻聚合API项目的贡献！该项目旨在成为对MCP服务器架构感兴趣的友好且文档齐全的代码库，特别是考虑到AI消费。

如何贡献

  1. 分叉仓库
  2. 创建新功能分支 (git checkout -b feature/amazing-feature)
  3. 进行更改
  4. 运行测试以确保一切正常 (npm test)
  5. 提交更改 (git commit -m 'Add some amazing feature')
  6. 推送到分支 (git push origin feature/amazing-feature)
  7. 打开拉取请求

代码风格

请遵循项目中的现有代码风格和模式。此项目使用ESLint进行代码质量和格式化。

安全注意事项

在贡献时，请确保：

  • 不要硬编码API密钥或凭证
  • 使用环境变量进行配置
  • 不记录敏感数据
  • 正确实现输入验证

测试

所有新功能都应包括适当的测试。请遵循项目中的现有测试模式。

  • 搜索历史和书签
    • 添加保存搜索功能
    • 实现文章书签
    • 创建阅读历史跟踪
    • 添加用户收藏夹功能

贡献

  1. 分叉仓库
  2. 创建你的功能分支：git checkout -b feature/my-new-feature
  3. 提交你的更改：git commit -am 'Add some feature'
  4. 推送到分支：[git push origin feature/my-new-feature](git push origin feature/my-new-feature)
  5. 提交拉取请求

许可

ISC