内容
# 新闻聚合 API (MCP Server)
一个基于 MCP Server 规范和 TypeScript 构建的模块化、可扩展的新闻聚合后端。该 API 提供了一个统一的接口，用于通过 TheNewsAPI 检索当前和历史新闻文章，并具备高级过滤功能。专为 AI 代理消费而设计，该 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. **集成测试**
- 测试完整的请求-响应周期
- 使用 supertest 验证 API 端点
- 模拟外部 API 调用以确保可靠性
### 测试最佳实践
该项目遵循以下测试最佳实践：
- **隔离** - 测试之间不依赖于彼此或外部服务
- **可重复** - 测试在任何环境中产生相同的结果
- **快速** - 模拟外部依赖使测试高效
- **全面** - 核心功能具有高测试覆盖率
- **可维护** - 测试遵循一致的模式和结构
### 运行测试
```bash
# 运行所有测试
npm test
# 运行带覆盖率的测试
npm run test:coverage
# 运行特定测试文件
npx jest path/to/test.ts
```
## 安装
```bash
# 克隆仓库
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。
## 开发
```bash
# 在开发模式下运行并支持热重载
npm run dev
# 运行代码检查
npm run lint
# 运行测试
npm test
```
## 测试基础设施
该项目包含一个全面的测试套件，使用 Jest 和 Supertest 构建，涵盖 API 端点、数据库集成和服务器连接检查。
### 运行测试
```bash
# 运行所有测试
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：基础改进
- [x] **缓存系统**
- 实现内存缓存
- 缓存频繁访问的数据，如头条新闻和来源
- 添加缓存失效策略
- 为不同内容类型配置 TTL（生存时间）
- 添加缓存管理端点
- [x] **数据持久层**
- 添加数据库集成（使用 Prisma 的 SQLite）
- 创建存储增强文章元数据的模式
- 实现数据访问的仓库模式
- 添加模式变更的迁移系统
- [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 服务器架构感兴趣的人提供一个友好、文档齐全的代码库，特别是考虑到 AI 消费。
### 如何贡献
1. Fork 仓库
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. 打开一个 Pull Request
### 代码风格
请遵循项目中现有的代码风格和模式。该项目使用 ESLint 进行代码质量和格式检查。
### 安全考虑
在贡献时，请确保：
- 不要硬编码 API 密钥或凭据
- 使用环境变量进行配置
- 不记录敏感数据
- 正确实现输入验证
### 测试
所有新功能应包含适当的测试。请遵循项目中现有的测试模式。
- [ ] **搜索历史与书签**
- 添加保存搜索功能
- 实现文章书签功能
- 创建阅读历史跟踪
- 添加用户收藏功能
## 贡献
1. Fork 仓库
2. 创建您的功能分支：`git checkout -b feature/my-new-feature`
3. 提交更改：`git commit -am 'Add some feature'`
4. 推送到分支：`git push origin feature/my-new-feature`
5. 提交一个 Pull Request
## 许可证
ISC
MCP 市场
