AI导哈

新闻聚合API

一个模块化、可扩展的新闻聚合后端服务，提供统一接口访问TheNewsAPI，支持高级过滤功能，专为AI代理消费设计。

  • by Malachi-devel
  • HTML
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 malachi-devel/the-news-api-mcp-server

使用说明

新闻聚合器API（MCP服务器）

使用MCP服务器约定和TypeScript构建的模块化、可扩展的新闻聚合后端。此API为TheNewsAPI提供了一个统一的接口，用于检索具有高级过滤功能的当前和历史新闻文章。此API专为人工智能代理消费而设计，优先考虑结构化数据和一致的模式。

特性

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

端点

新闻终点

端点 描述 示例
/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.json OpenAPI规范
/examples 使用示例

测试

该项目实施了一项全面的测试策略，包括多层测试，以确保可靠性和正确性。

测试类型

  1. 单元测试

    • 单个组件的隔离测试
    • 模拟依赖关系，实现真正的单元隔离
    • 专注于业务逻辑验证

  2. 控制器测试

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

  3. 集成测试

    • 测试完整的请求响应周期
    • 使用超级测试验证API端点
    • 模仿外部API对可靠性的要求

测试最佳实践

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

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

运行测试

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run a specific test file
npx jest path/to/test.ts

安装

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env file with your own API key and database URL

# Generate Prisma client
npx prisma generate

# Build the project
npm run build

# Start the server
npm start

配置

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

# News Aggregator API Environment Variables

# API Configuration
NEWS_API_TOKEN=your_api_token_here

# Server Configuration
PORT=3000
NODE_ENV=development

# Database Configuration
DATABASE_URL="file:./dev.db"

数据库配置

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

发展

# Run in development mode with hot reload
npm run dev

# Run linting
npm run lint

# Run tests
npm test

测试基础设施

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

运行测试

# Run all tests
npm test

# Run only API endpoint tests
npm run test:api

# Run only database integration tests
npm run test:db

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode (for development)
npm run test:watch

# Check server connectivity
npm run check-server

测试结构

  • API端点测试：位于 src/__tests__/api/，这些测试验证所有API端点是否返回预期响应、正确处理错误并应用适当的筛选。

  • 数据库集成测试：位于 src/__tests__/database.test.ts，这些测试验证数据库连接、查询执行和事务支持。

  • 服务器连接脚本：位于 scripts/check-server.ts，此脚本测试与正在运行的服务器实例的连接，验证关键端点是否正常运行。

测试环境

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

  • 自动建立和断开数据库连接
  • 在测试之间清除缓存以确保隔离
  • 服务器启动和关闭以进行端点测试

未来增强功能待办事项列表

优先事项1：基础改进

  • [x] 缓存系统

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

  • [x] 数据持久层

    • 添加数据库集成（SQLite与Prisma）
    • 创建用于存储增强文章元数据的架构
    • 实现数据访问的存储库模式
    • 为架构更改添加迁移系统

  • [x] 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：增强功能

  • [ ] 内容处理

    • 添加文本摘要功能
    • 实现实体提取
    • 添加情绪分析
    • 创建源类别之外的主题分类
    • 实现重复检测和分组

  • [ ] 个性化

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

  • [ ] Webhooks和实时更新

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

贡献

欢迎对新闻聚合器API项目做出贡献！该项目旨在为那些对MCP服务器架构感兴趣的人提供一个友好、记录良好的代码库，特别是考虑到人工智能的消费。

如何做出贡献

  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
  5. 提交拉取请求

许可证

国际协调委员会

相关 MCP