新闻聚合器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 | 使用示例 |
测试
该项目实施了一项全面的测试策略，包括多层测试，以确保可靠性和正确性。
测试类型
- 单元测试
- 单个组件的隔离测试 - 模拟依赖关系，实现真正的单元隔离 - 专注于业务逻辑验证
- 控制器测试
- 使用模拟服务验证控制器行为 - 测试正确的请求处理和响应格式 - 确认错误处理模式一致
- 集成测试
- 测试完整的请求响应周期 - 使用超级测试验证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
# 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包含多种语言的代码示例
如何访问文档
- 使用启动服务器
npm run dev或npm start - 打开浏览器
http://localhost:3000/docs用于交互式Swagger UI - 浏览可用端点、请求参数和响应格式
- 参考实施示例
http://localhost:3000/examples
API文档功能
- 完整的端点描述，包括参数和响应类型
- 直接测试端点的交互式“试用”功能
- 请求/响应模式定义
- API消费的代码片段
- 与MCP服务器架构集成的示例
优先级2：安全与性能
- \[ \] 身份验证和用户管理
- 实现基于JWT的身份验证 - 创建用户注册和登录端点 - 添加基于角色的访问控制 - 实施安全密码处理
- \[ \] 速率限制
- 添加请求限制中间件 - 实施分层访问级别 - 制定公平使用政策 - 在响应中添加速率限制标头
- \[ \] 监控和分析
- 设置请求日志记录和监控 - 添加性能指标集合 - 创建使用情况仪表板 - 实施错误跟踪和警报
优先级3：增强功能
- \[ \] 内容处理
- 添加文本摘要功能 - 实现实体提取 - 添加情绪分析 - 创建源类别之外的主题分类 - 实现重复检测和分组
- \[ \] 个性化
- 添加用户偏好跟踪 - 基于阅读历史创建个性化端点 - 实现主题跟踪功能 - 添加推荐引擎
- \[ \] Webhooks和实时更新
- 实施 webhook 注册 - 创建基于事件的通知系统 - 添加SSE（服务器发送事件）以进行实时更新 - 实现主题订阅功能
贡献
欢迎对新闻聚合器API项目做出贡献！该项目旨在为那些对MCP服务器架构感兴趣的人提供一个友好、记录良好的代码库，特别是考虑到人工智能的消费。
如何做出贡献
- 分叉存储库
- 创建新功能分支(
git checkout -b feature/amazing-feature) - 进行更改
- 运行测试以确保一切正常(
npm test) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
代码的风格
请遵循项目中现有的代码样式和模式。此项目使用ESLint进行代码质量和格式设置。
安全考虑
在捐款时，请确保：
- 没有API密钥或证书是硬编码的
- 环境变量用于配置
- 未记录敏感数据
- 输入验证已正确实施
测试
所有新功能都应包括适当的测试。请遵循项目中现有的测试模式。
- \[ \] 搜索历史记录和书签
- 添加已保存的搜索功能 - 实现文章书签 - 创建阅读历史跟踪 - 添加用户收藏功能
贡献
- 分叉存储库
- 创建特征分支：
git checkout -b feature/my-new-feature - 提交您的更改：
git commit -am 'Add some feature' - 推到分支：
git push origin feature/my-new-feature - 提交拉取请求
许可证
国际协调委员会