# 🌅 mcp-news-briefing

一个个性化的AI信息过滤系统，以MCP Server的形式集成到Claude Desktop中。

## 核心理念

> 不是被动接收一封邮件，而是主动打开Claude说"今天有什么值得看的"。

这个系统通过你的兴趣偏好对海量信息进行过滤，只把跟你相关的内容呈现出来。偏好由你自己定义，信源由你自己选择，过滤由AI完成。不限于AI领域——天文、金融、安全、烹饪，你关注什么就设置什么。

所有数据存在你自己的电脑上，没有云端，没有账号，没有追踪。

**👉 我是用户** — 有人给了我一个 .mcpb 文件，我想开始使用 → [安装与使用](#安装与使用)

**👉 我是开发者** — 我想自己 clone 代码跑起来，或者参与开发 → [开发者指南](#开发者指南)

---

## 安装与使用

### 前置条件

- [Claude Desktop](https://claude.ai/download)（macOS 或 Windows）

就这一个。不需要装其他任何东西。

### 安装

1. 拿到 `mcp-news-briefing.mcpb` 文件
2. 打开 Claude Desktop → Settings → Extensions → Advanced Settings → Install Extension
3. 选择这个文件
4. 安装完成

### 注册

跟Claude说：

> "帮我注册一下新闻简报，名字叫（你的名字）"

你会拿到一个token，**请保存好**。不过后续你用名字也能识别身份，不用每次贴token。

第一个注册的用户会自动成为**默认身份**——之后跟Claude说"今天有什么新闻"时不需要指定是谁，直接用就行。

如果你注册了多个账号（比如一个看AI、一个看天文），可以切换默认身份：

> "把默认身份切到（名字）"

### 设置兴趣偏好

有两种方式：

**方式A：问答引导（推荐）**

> "帮我设置一下我关注的内容"

Claude会通过几个问题了解你的职业、关注领域、不想看的内容，然后自动整理好。

**方式B：直接告知**

> "我关注AI Agent、嵌入式开发、天文摄影，不想看融资新闻，帮我设置好"

### 选择信源

偏好设好后：

> "帮我推荐一下适合我的新闻来源"

Claude会根据你的偏好推荐相关的RSS、Reddit板块等，你确认后就订阅了。也可以自己加：

> "帮我加一个RSS源：https://example.com/feed.xml，名字叫my-blog"

### 开始使用

> "今天有什么值得看的"

### 日常用法

| 你说的话 | 会发生什么 |
|---------|-----------|
| "今天有什么值得看的" | 抓取最近24小时 + 过滤 + 呈现（默认8条） |
| "这周有什么值得看的" | 抓取最近7天的内容 |
| "最近的新闻多给点，20条" | 抓取30天内容，返回20条 |
| "这条展开说说" | 详细分析某条内容 |
| "把这条收藏" | 标记感兴趣的内容 |
| "我最近都关注了什么？" | 查看兴趣趋势摘要 |
| "帮我加个关注领域：量子计算" | 动态调整偏好 |
| "我现在订阅了哪些来源？" | 查看当前订阅的信源 |

### 📊 股票监控

除了新闻简报，还可以关注个股动态（美股 / 澳股），包括侧重面定制、预警系统、历史趋势分析等。

详见 **[股票监控指南](stock-monitoring-guide.md)**。

### 💡 提示

- 偏好和信源随时可以调整，不需要重新注册
- 一个人可以注册多个token，比如一个看AI、一个看天文，各自独立；用 `briefing_set_default` 切换当前默认身份
- 信息来源包括RSS、Reddit和Hacker News，覆盖面很广

### 数据存储

所有数据在你本地：

| 系统 | 位置 |
|------|------|
| macOS | `~/Library/Application Support/mcp-news-briefing/` |
| Windows | `%APPDATA%\mcp-news-briefing\` |

### ⚠️ 免责声明

本工具从第三方 RSS 和公开 API 聚合信息。部分可选信源（SEC EDGAR、Seeking Alpha）有各自的使用条款——启用即表示你同意遵守相应条款。

这不是投资建议。利好/利空情绪分析由 AI 模型生成，不应作为投资决策的唯一依据。请自行研究。

---

## 开发者指南

### Clone & 运行

```bash
git clone https://github.com/AmyYingTang/mcp-news-briefing.git
cd mcp-news-briefing
npm install
npm run build
```

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "briefing": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-news-briefing/dist/server.js"]
    }
  }
}
```

完全退出 Claude Desktop 再重新打开（macOS 用 Cmd+Q，不是关窗口）。

### 打包 .mcpb

```bash
bash build-mcpb.sh
```

产物 `mcp-news-briefing.mcpb` 可以分发给任何 Claude Desktop 用户安装。

### 项目结构

```
mcp-news-briefing/
├── manifest.json            # MCPB Desktop Extension 清单
├── build-mcpb.sh            # 打包脚本
├── package.json
├── tsconfig.json
├── README.md
├── stock-monitoring-guide.md # 股票监控：设计理念与使用指南
└── src/
    ├── server.ts            # MCP 工具定义 & 启动入口
    ├── storage.ts           # 跨平台数据目录 & JSON 读写
    ├── auth.ts              # Token 注册 / 验证 / 解析
    ├── profile.ts           # 兴趣偏好 CRUD、引导问卷、信源推荐库
    ├── sources.ts           # RSS / Reddit / HN 抓取 + 缓存
    ├── user-sources.ts      # 用户信源配置管理
    ├── interaction-log.ts   # 阅读行为追踪
    ├── watchlist.ts         # 股票关注列表 CRUD、侧重面推荐、信源目录
    ├── stock-sources.ts     # 股票新闻抓取（per-ticker RSS / 过滤型信源 / fallback）+ 按日期缓存
    └── stock-history.ts     # 情绪快照 CRUD、收盘价抓取、背离检测
```

### 架构

```
Claude Desktop
    │ stdio
    ▼
┌──────────────┐
│  MCP Server  │  ← Node.js (Claude Desktop 内置)
│  (TS/SDK)    │
└──────┬───────┘
       │
  ┌────┼────┐
  ▼    ▼    ▼
缓存  偏好  信源     ← 按 token 隔离，JSON 文件存储
      日志
```

- **缓存策略：** 同一30分钟窗口内，信源配置相同的请求共享缓存（缓存key含信源配置hash）
- **数据隔离：** 每个token对应 `users/<token前8位>/` 目录，包含独立的 profile.json、sources.json、interaction_log.json

### MCP 工具一览

**新闻简报：**

| 工具名 | 功能 |
|--------|------|
| `briefing_register` | 注册新用户，获取token（第一个自动设为默认身份） |
| `briefing_set_default` | 切换默认身份（多账号时使用） |
| `briefing_create_profile_interactive` | 兴趣偏好引导问卷 |
| `briefing_set_profile` | 设置/更新兴趣偏好 |
| `briefing_get_profile` | 获取兴趣偏好 |
| `briefing_suggest_sources` | 根据偏好推荐信源 |
| `briefing_set_sources` | 按分类ID批量订阅 |
| `briefing_add_sources` | 追加自定义信源 |
| `briefing_get_sources` | 查看信源配置 |
| `briefing_fetch_articles` | 抓取文章（24h/168h/720h） |
| `briefing_get_articles` | 获取已保存文章列表 |
| `briefing_log_interaction` | 记录阅读/讨论/收藏 |
| `briefing_interaction_summary` | 兴趣趋势摘要 |
| `briefing_view_log` | 查看阅读记录 |

**股票监控：**

| 工具名 | 功能 |
|--------|------|
| `briefing_stock_watchlist_set` | 添加/更新关注股票，自动推荐侧重面 |
| `briefing_stock_watchlist_get` | 查看关注列表及侧重面配置 |
| `briefing_stock_watchlist_remove` | 移除关注股票 |
| `briefing_stock_watchlist_update_focus` | 调整某只股票的关注侧重面 |
| `briefing_stock_watchlist_custom_sources` | 管理某只股票的自定义 RSS 信源 |
| `briefing_stock_auto_fetch` | 开启/关闭每次启动时自动抓取股票新闻 |
| `briefing_stock_fetch` | 抓取关注股票的最新新闻 |
| `briefing_stock_digest` | 获取股票新闻列表，供 AI 做利好/利空分析（支持历史日期回溯） |
| `briefing_stock_history_record` | 记录每日情绪快照（分析后自动调用） |
| `briefing_stock_history_get` | 查看历史情绪趋势 + 股价走势 + 背离检测（含逐日数据状态） |
| `briefing_stock_alert_set` | 批量创建预警（从分析师报告提取或手动） |
| `briefing_stock_alert_list` | 查看预警列表 + 触发统计 |
| `briefing_stock_alert_update` | 修改预警松紧度、时间窗口、关键词 |
| `briefing_stock_alert_dismiss` | 关闭预警 |
| `briefing_stock_alert_trigger` | 记录预警触发 + 事件级去重（digest 分析时自动调用） |

### 新用户完整流程（工具调用顺序）

1. `briefing_register` → 获取token
2. `briefing_create_profile_interactive` → AI引导对话 → `briefing_set_profile` 提交
3. `briefing_suggest_sources` → 用户确认 → `briefing_set_sources` 订阅
4. `briefing_fetch_articles` → `briefing_get_articles` + `briefing_get_profile` → AI过滤分析

### Roadmap

- [x] 多用户 token 隔离
- [x] 兴趣偏好引导问卷
- [x] 信源推荐引擎
- [x] 阅读行为追踪 & 兴趣趋势分析
- [x] TypeScript 重写（Node.js 原生，.mcpb 就绪）
- [x] .mcpb Desktop Extension 打包
- [x] 股票关注列表（Watchlist）— 美股 / 澳股，侧重面推荐，利好利空分析
- [x] 默认身份（注册后无需每次指定用户名，多账号可切换）
- [x] Watchlist 自定义信源（per-ticker RSS，支持占位符）
- [x] 市场信源自动匹配（SEC EDGAR CIK 查找 + ASX 公告 RSS 降级）
- [ ] Anthropic Extension Directory 提交
- [ ] OAuth 2.1（远程部署场景）
- [ ] Twitter/X 数据源
- [x] 股票历史情绪趋势 + 股价对比 + 背离检测
- [x] 股票预警（Alert）— 分析师报告提取、时效性监控、通用预警、风险提示优先
- [x] 预警事件级去重 — 同一事件多天多源报道只触发一次，实质性进展自动识别
- [x] 启动时自动抓取 — 用户开启后每次打开 Claude Desktop 自动更新股票新闻（幂等，每日一次）
- [x] 按日期保留抓取缓存（14天）— 支持回溯分析历史某天的新闻
- [ ] 预警推送通知（pending notification 写入 + 下次交互时呈现）
- [ ] 偏好自动演进（根据阅读行为调整关注权重）

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.