# 新闻舆情邮件助手 / News Sentiment Mailer

[中文](#中文) · [English](#english)

> 从新闻检索到舆情分析，再到邮件投递的一体化 MCP 示例项目。

![工作流程 / Workflow](docs/images/workflow.svg)

## 运行效果 / Screenshots

<p align="center">
  <img src="docs/images/markdown-report-source.png" width="49%" alt="Markdown report source" />
  <img src="docs/images/email-report-preview.png" width="49%" alt="Email delivery and rendered report preview" />
</p>

<p align="center">
  <em>左：生成的 Markdown 报告源文件 / Left: generated Markdown report source · 右：邮件附件与渲染预览 / Right: delivered email attachment and rendered report</em>
</p>

---

## 中文

### 关于项目

**新闻舆情邮件助手**会根据自然语言请求检索近期新闻、生成 Markdown 舆情报告，并通过 SMTP 将报告作为附件发送给指定收件人。

项目由 MCP 客户端和服务端组成：客户端负责接收请求和编排流程；服务端负责 Google News RSS 检索、DashScope 舆情分析、报告保存及邮件发送。

### 功能

- 免费使用 Google News RSS 获取近期新闻，无需新闻搜索 API Key
- 使用 DashScope 兼容 OpenAI 接口生成舆情分析报告
- 自动保存 Markdown 报告到 `sentiment_reports/`
- 通过 SMTP 发送带附件的报告
- 支持中文自然语言请求，例如“关于小米 YU7 近期有什么热点，梳理后发送到 recipient@example.com”
- 搜索失败时停止发送，避免把错误提示当作报告发送

### 架构与流程

1. 在 `client.py` 输入自然语言请求。
2. 客户端识别明确的收件邮箱与发送意图。
3. `server.py` 通过 Google News RSS 获取前 5 条新闻。
4. DashScope 生成 Markdown 格式的舆情结论。
5. 报告保存至本地，并通过配置好的 SMTP 账户作为附件发送。

### 快速开始

#### 1. 准备环境

本项目在 `pyproject.toml` 中声明 Python `>= 3.14`。推荐使用 [uv](https://docs.astral.sh/uv/)：

```powershell
uv sync
```

或使用你自己的 Python 环境安装 `pyproject.toml` 中列出的依赖。

#### 2. 配置密钥与邮箱

复制示例配置，**不要提交真实 `.env` 文件**：

```powershell
Copy-Item .env.example .env
```

在 `.env` 中填写：

| 变量 | 用途 |
| --- | --- |
| `DASHSCOPE_API_KEY` | DashScope / 百炼 API Key，用于生成分析 |
| `BASE_URL` | DashScope OpenAI 兼容接口地址 |
| `MODEL` | 使用的模型名称 |
| `SMTP_SERVER` / `SMTP_PORT` | 发件邮箱的 SMTP 地址与端口 |
| `EMAIL_USER` | 发件人邮箱 |
| `EMAIL_PASS` | SMTP 客户端授权码，不是网页登录密码 |

Google News RSS 不需要 API Key。

#### 3. 运行

```powershell
python client.py
```

输入示例：

```text
关于小米 YU7 汽车近期有什么热点，梳理后发送到 recipient@example.com
```

成功后，终端会回显报告内容，报告会保存到 `sentiment_reports/`，并以附件形式发送。

### 输出示例

报告包含新闻原文摘要、总体情绪倾向和逐条情绪原因。请在发送或用于决策前人工核验新闻来源、模型结论与收件人地址。

### 安全说明

- `.env`、本地报告、检索结果和对话记录均被 `.gitignore` 排除，不会被提交。
- 请使用 SMTP 授权码，不要使用邮箱登录密码。
- 邮件发送是外部操作；请确认自然语言中的收件人地址无误。
- LLM 分析仅作辅助参考，不应替代人工判断。

---

## English

### About

**News Sentiment Mailer** turns a natural-language request into a recent-news search, a Markdown sentiment report, and an SMTP email with that report attached.

The project contains an MCP client and server. The client accepts requests and orchestrates the flow; the server searches Google News RSS, asks DashScope for analysis, saves the report, and sends the email.

### Features

- Searches recent news through free Google News RSS — no news-search API key required
- Generates sentiment reports through the DashScope OpenAI-compatible API
- Saves Markdown reports in `sentiment_reports/`
- Sends reports as SMTP email attachments
- Accepts Chinese natural-language requests with an explicit recipient address
- Stops before sending when the news search fails

### Flow

1. Enter a request in `client.py`.
2. The client detects an explicit email address and send intent.
3. `server.py` fetches the first five items from Google News RSS.
4. DashScope produces a Markdown sentiment analysis.
5. The report is stored locally and delivered through the configured SMTP account.

### Quick start

#### 1. Install dependencies

The project declares Python `>= 3.14` in `pyproject.toml`. Using [uv](https://docs.astral.sh/uv/) is recommended:

```powershell
uv sync
```

#### 2. Configure credentials

```powershell
Copy-Item .env.example .env
```

Replace every placeholder in `.env` with your own DashScope and SMTP credentials. Do not commit this file. Google News RSS does not need an API key.

#### 3. Run

```powershell
python client.py
```

Example request:

```text
关于小米 YU7 汽车近期有什么热点，梳理后发送到 recipient@example.com
```

The generated report is printed to the terminal, stored in `sentiment_reports/`, and sent as an attachment.

### Security and limitations

- `.env`, generated reports, search data, and conversation logs are ignored by Git.
- Use an SMTP authorization code rather than an email-account password.
- Verify the recipient and the generated content before acting on an email.
- News and LLM output can be incomplete or inaccurate; treat them as assistance, not authoritative advice.