Content
# SecNews · AI + Security Knowledge Workstation
> **v1.7.6** · Single-person local deployment · Three subsystems work together · **Standard MCP protocol exposed**
>
> An integrated personal workstation for AI and security practitioners, featuring "hotspot aggregation → knowledge closed loop → project management → AI collaboration".
[English](#english) | [中文](#%E4%B8%AD%E6%96%87)
## English
### What is this
**SecNews** (development codename `hotspot`) is a single-person local workstation for **AI + Security practitioners**. It combines three separate tasks into one local system:
| Subsystem | Problem solved | Entrance |
|---|---|---|
| **SecNews Hotspot Aggregation** | 7 major areas, 30+ data sources, automatically pulled, categorized, deduplicated, and stored | `/` |
| **Knowledge LLM-Wiki** | File system-driven knowledge base (OKF + LLM-Wiki 2.0), automatically refined from favorites/bookmarks/Cubox | `/knowledge` |
| **CodeGarden Project Management** | Full lifecycle of personal code projects (Idea → Archive), with service grid/resource center/linkage engine | `/codegarden` |
| **Security Knowledge Graph** (v1.5+) | MITRE ATT&CK + CVE + compliance ontology, security information automatically mapped | `/security` |
| **MCP Server** (v1.7 Phase 7) | 13 standard tools, allowing **Cursor / Claude Desktop / Trae / Workbuddy** to directly read and write local knowledge base | `stdio` / `http://127.0.0.1:8000/mcp/sse` |
### Who is it for
- **AI/ML practitioners**: track latest model releases, papers, open-source projects (aihot/OpenAI/Anthropic/HackerNews/ProductHunt)
- **Security researchers / Red and Blue teams**: track CVE, ATT&CK tactics, Alibaba Cloud vulnerability library, CNNVD, Qi Anxin, 360 Security, FreeBuf, THN, and 17+ security sources
- **Independent developers / Entrepreneurs**: manage side projects' full lifecycle, automatically allocate ports, scan services, and orchestrate Playbooks
- **Knowledge workers**: automatically sediment daily information, bookmarks, and collections into a searchable, reviewable, and associable local knowledge base
> One person, one computer, zero external services. LLM reasoning is handed over to external AI Agents (via MCP protocol), while hotspot only handles data storage + 13 tool exposures.
### Core Features
#### 1. SecNews — Multi-source Hotspot Aggregation
- **7 major areas**: `ai` / `security` / `finance` / `startup` / `bid` / `github` / `tech`
- **30+ data sources**: aihot.virxact.com, Sina Finance, Tencent Securities, Alibaba Cloud vulnerability library, CNNVD, Hacker News, Product Hunt, GitHub Trending, etc.
- **13 quality gates** (`backend/quality/`): URL validation, title summarization, source credibility, noise filtering, Recency gate (Monday 00:00 UTC+8), etc.
- **5min automatic collection** + **1h trend recalculation** + **24h data backup**
#### 2. Knowledge — OKF + LLM-Wiki 2.0 Unified Storage
- **4-layer pyramid**: L1 database (`.md` files) → L2 concept library → L3 learning plan → L4 content creation
- **3 major data sources automatically synchronized**:
- **SecNews favorites** (one-star → automatically added to knowledge base)
- **Cubox** (`cubox-cli` synchronization, including full text + annotations)
- **Chrome bookmarks** (import JSON, automatically deduplicated)
- **Implicit personalization**: EMA weight + interest distribution, automatically generating `SOUL.md` role portrait
- **SM-2 spaced repetition**: automatically arrange review schedule, ensuring knowledge retention
- **Multi-dimensional tags + cross-layer search**: query once, penetrate all 4 layers
#### 3. CodeGarden — Full Project Lifecycle
- **Lifecycle state machine**: `ideation` → `prototype` → `development` → `testing` → `running` → `maintenance` → `archived` → `deprecated`
- **M2 service grid** (v1.6 Phase 2b): automatically discover local services (`lsof`/`docker ps`/`pm2 list`), topology graph + logs + restart
- **M3 resource center**: 4 types of resources (port / domain / env_template / volume), protected port 8898
- **M4 linkage engine**: dependency graph + event bus + Playbook YAML execution + impact analysis (BFS backtracking)
- **Batch import**: import projects from knowledge base / GitHub
#### 4. Security Knowledge Graph (v1.5+)
- **MITRE ATT&CK** full STIX parsing → `security_entities` + `security_edges` (CC-BY-4.0 licensed)
- **NVD CVE** on-demand query + 30-day local cache
- **Terminology standardization** (zh-CN): synonym dictionary + compliance ontology (equal protection 2.0 / key regulations / data security law)
- **Automatic mapping**: each security information automatically extracts `cve_ids` / `attack_techniques` / `compliance_refs`
#### 5. MCP Server (v1.7 Phase 7 — Option A Simplified)
- **13 standard tools** (5 read + 8 write):
| Read (5) | Write (8) |
|---|---|
| `search_hotspots` | `add_favorite` |
| `get_hotspot` | `remove_favorite` |
| `list_favorites` | `add_annotation` |
| `search_knowledge` | `update_knowledge_item` |
| `get_personal_profile` | `trigger_extract_tags` |
| | `trigger_cubox_sync` |
| | `create_alert_rule` |
| | `mark_digest_read` |
- **Dual transmission**: `stdio` (default, Cursor / Trae / Claude Desktop) + `SSE` (`/mcp/sse`)
- **Zero state**: hotspot does not maintain session / heartbeat, AI Agent synchronizes directly
- **Local priority**: default binding `127.0.0.1:8000`
### Quick Start
#### Environment Requirements
- **Python** 3.10+ (recommended 3.11 / 3.12)
- **Node.js** 18+ (recommended 20 LTS)
- **macOS / Linux** (Windows not tested, path separator may have issues)
- Optional: proxy client (Clash / V2RayN / Surge, for `security_collector` and `github_collector`)
#### 1. Clone & Install Dependencies
```bash
git clone https://github.com/anyeduke11/secnews.git
cd secnews
# Backend dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
# Frontend dependencies
cd frontend
npm install
cd ..
```
#### 2. Configure Proxy (important)
`backend/proxy_config.json` is in `.gitignore`, **not distributed with the repository**. Must configure manually after installation, otherwise `security_collector` and `github_collector` will not work.
Edit `backend/proxy_config.json`:
```json
{
"mode": "manual",
"http_proxy": "http://127.0.0.1:7897",
"https_proxy": "http://127.0.0.1:7897",
"socks_proxy": "http://127.0.0.1:7897",
"no_proxy": "localhost,127.0.0.1,::1"
}
```
Change `7897` to your proxy port (Clash default 7890, V2RayN default 10809). If no proxy is used, change to `"mode": "off"`. Can also modify via frontend `/api/proxy/settings` at runtime, no restart needed.
#### 3. Start Backend
```bash
# Root directory startup script (recommended)
python run.py
# Equivalent command
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
```
Environment variables:
- `HOST` (default `0.0.0.0`)
- `PORT` (default `8000`)
- `WORKERS` (default `1`, SQLite WAL mode may have lock competition)
- `HOTSPOT_FEATURE_MCP_SERVER` (default `true`, disable MCP tool exposure if off)
Backend starts and automatically:
1. `init_db()` applies 39 migrations
2. Schedules 13 APScheduler jobs
3. Starts 13 MCP tool metadata seeding
4. Mounts SSE endpoint `/mcp/sse`
#### 4. Start Frontend
```bash
cd frontend
npm run dev
```
Frontend runs at `http://localhost:8898` (**fixed port**, no drift).
#### 5. Configure MCP Server (optional but recommended)
Open frontend → top-right **Settings** → **MCP Server** card → click **Copy stdio configuration**.
Paste the JSON into your AI Agent configuration file:
| AI Agent | Config file path |
|---|---|
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Trae** | `~/.trae/mcp_config.json` |
| **Cursor** | `~/.cursor/mcp.json` |
| **Claude Code** | project root directory `.mcp.json` |
```json
{
"mcpServers": {
"hotspot": {
"command": "python",
"args": ["-m", "backend.mcp_stdio_main"],
"cwd": "/absolute/path/secnews"
}
}
}
```
After starting the AI Agent, it will automatically discover 13 tools and can directly ask "List recent 24h security hotspots, sorted by threat level".
#### 6. Access
Open browser → `http://localhost:8898`
### Architecture
```
┌─────────────────────────────────────────────────────────────────────┐
│ Browser (React SPA) │
│ SecNews / Knowledge / CodeGarden / Security / Settings / MCP Card │
│ (60+ components, React 18 + Vite 5 + TypeScript + Tailwind 3) │
└───────────────┬─────────────────────────────────────┬───────────────┘
│ HTTP / JSON │ SSE / stdio
│ │
┌───────────────▼────────────────────┐ ┌──────────▼──────────────┐
│ FastAPI process (single process, port 8000) │ │ MCP Server (13 tools) │
│ ┌──────────────────────────────┐ │ │ 5 read + 8 write │
│ │ 23 routers (~50 lines ea) │ │ │ stdio / SSE dual transmission │
│ │ /api/hotspots /knowledge │ │ └──────────┬──────────────┘
│ │ /api/codegarden /security │ │ │
│ │ /api/mcp /api/profile ... │ │ │
│ └────────────┬─────────────────┘ │ │
│ │ │ │
│ ┌────────────▼─────────────────┐ │ │
│ │ 41 services (business logic layer) │ │◄──────────────┘
│ │ Hotspot / Sync / Cubox / │ │ External AI Agent direct call
│ │ Knowledge / CodeGarden / │ │ (Cursor / Claude / Trae)
│ │ Security / AutoClassifier │ │
│ └────────────┬─────────────────┘ │
│ │ │
│ ┌────────────▼─────────────────┐ │
│ │ 20 repository (DAO layer) │ │
│ │ SQLite WAL + 39 migrations │ │
│ └────────────┬─────────────────┘ │
│ │ │
│ ┌────────────▼─────────────────┐ │
│ │ 8 collectors (data sources) │ │
│ │ 13 quality gates (filtering) │ │
│ │ APScheduler (13 jobs) │ │
│ └────────────┬─────────────────┘ │
└───────────────┼─────────────────────┘
│
┌───────┴────────┐
▼ ▼
┌─────────┐ ┌──────────┐
│ SQLite │ │ .md files │
│ hotspot │ │ knowledge/│
│ .db │ │ items/ │
│ + WAL │ │ concepts/ │
└─────────┘ └──────────┘
▲
│ Encrypted (Fernet)
│
┌────┴────────┐
│ WebDAV sync │ ← Cross-platform config (坚果云 / Nextcloud)
│ (optional) │
└─────────────┘
```
#### Technology Selection Reasons
| Component | Selection | Reason |
|---|---|---|
| Web framework | FastAPI | async + OpenAPI ecosystem mature |
| Main storage | **SQLite (WAL mode)** | zero deployment, strong SQL, FTS5 full-text search, single file easy backup |
| Knowledge storage | **`.md` files** | file system as knowledge base, git-friendly, AI Agent can read directly |
| Scheduling | APScheduler | single process scheduling, no external MQ |
| Cache | `cachetools.TTLCache` | in-process LRU, TTL 5min |
| Logging | `loguru` | structured, automatic rotation |
| HTTP client | `aiohttp` + `ProxySession` | anti-scraping friendly |
| MCP integration | `fastapi-mcp` | OpenAPI → MCP automatic conversion |
| Frontend | React 18 + Vite 5 + TypeScript | existing ~60 components, type-safe |
| Charts | echarts + recharts | dashboard style |
| Encryption | Fernet (PBKDF2 derived) | sync package / secrets |
| Cross-platform sync | WebDAV (坚果云) | zip container, Fernet encryption |
### Directory Structure
```
secnews/
├── backend/ # FastAPI Backend
│ ├── main.py # API Entry + Lifespan
│ ├── mcp_stdio_main.py # MCP Stdio Transport Entry
│ ├── config.py # Pydantic Settings
│ ├── api/ # 23 Routers (~50 lines each)
│ │ ├── hotspots.py # Hotspot Aggregation API
│ │ ├── knowledge.py # Knowledge Base API
│ │ ├── codegarden*.py # CodeGarden API
│ │ ├── security.py # Security Knowledge Graph API
│ │ ├── mcp.py / mcp_*.py # MCP Server
│ │ └── ... # 18 Other Routers
│ ├── services/ # 41 Business Logic Files
│ ├── repository/ # 20 Repositories + 39 Migrations
│ ├── collectors/ # 8 Data Source Collectors
│ ├── quality/ # 13 Quality Gates
│ ├── scheduler/ # APScheduler Jobs
│ ├── security/ # MITRE/NVD Integration
│ ├── parsers/ # Independent Parsers
│ └── tests/ # 67 Pytest Test Files
├── frontend/ # React + Vite
│ └── src/
│ ├── components/ # ~60 Components
│ │ ├── codegarden/ # CodeGarden Subcomponents
│ │ ├── knowledge/ # Knowledge 4 Major Domains
│ │ ├── security/ # Security Graph
│ │ └── settings/ # Settings Panel (including MCP Card)
│ ├── hooks/ # Custom Hooks
│ ├── types/ # TS Type Definitions
│ └── App.tsx # Routing + Theme
├── knowledge/ # LLM-Wiki 2.0 Knowledge Base
│ ├── _MAP.md # Auto-generated Index
│ ├── _SCHEMA.md # Data Model Contract
│ ├── SOUL.md # Role Profiles (auto-generated)
│ ├── items/ # L1 Knowledge Base (.md)
│ ├── concepts/ # L2 Concept Base
│ ├── learning/ # L3 Learning Plan
│ │ └── tasks/ # pending / done / failed
│ ├── content/ # L4 Content Creation
│ └── summaries/ # Weekly Reports / Retrospectives
├── codegarden/ # CodeGarden Data
│ ├── playbooks/ # Playbook YAML
│ ├── sdds/ # Software Design Documents
│ ├── specs/ # Project Specifications
│ └── exports/ # Exported Products
├── docs/ # Design Documents (28)
│ ├── ARCHITECTURE.md # Architecture Overview
│ ├── CodeGarden_PRD_v2.0.md # CodeGarden Complete PRD
│ ├── hotspot_v1.7_PRD.md # v1.7 Complete PRD
│ ├── SECURITY_KNOWLEDGE_GRAPH.md
│ ├── mcp_integration.md # MCP Integration Guide
│ ├── phase7_changelog.md # v1.7.6 Changelog
│ └── ...
├── run.py # Startup Script
├── AGENTS.md # Project-level Agent Rules
├── CLAUDE.md # Project-level Agent Rules
└── README.md # This File
```
---
### Configuration
#### Backend Environment Variables
| Variable | Default | Description |
|---|---|---|
| `HOST` | `0.0.0.0` | Listen Address |
| `PORT` | `8000` | Listen Port |
| `WORKERS` | `1` | Uvicorn Worker Count (keep 1, SQLite WAL lock) |
| `HOTSPOT_FEATURE_MCP_SERVER` | `true` | Enable MCP Server |
| `HOTSPOT_LOG_LEVEL` | `INFO` | Log Level |
| `HOTSPOT_PROXY_CONFIG` | `backend/proxy_config.json` | Proxy Configuration Path |
| `HOTSPOT_MASTER_KEY` | (empty → auto-generated) | Fernet Master Key (persisted to keyring before restart) |
#### Frontend Configuration
No build-time configuration. All runtime configurations go through `/api/settings/*` endpoints, which can be modified in the frontend UI.
#### Data Directory
| Type | Path | Backup |
|---|---|---|
| SQLite DB | `backend/hotspot.db` | `backend/data/backup_*.db` (24h rolling) |
| Knowledge Files | `knowledge/items/*.md` | git tracked (recommended) |
| Encrypted Secrets | OS keyring | non-exportable |
| Sync Packages | WebDAV (Nuts Cloud) | zip container, Fernet encrypted |
| Logs | `backend/logs/*.log` | loguru auto-rotation |
---
### Testing
#### Backend (67 Test Files, pytest)
```bash
# All tests
.venv/bin/python3 -m pytest backend/tests/ -v
# Filter by keyword
.venv/bin/python3 -m pytest backend/tests/ -k "merge"
# Single file
.venv/bin/python3 -m pytest backend/tests/test_sync_merge.py -v
# Compilation check
.venv/bin/python3 -m py_compile backend/services/sync_merge.py
```
Test hierarchy:
- **Pure function tests** (no DB): `test_sync_merge.py` / `test_auto_classifier.py` / `test_knowledge_watcher.py`
- **DAO tests** (tmp DB): `test_db.py` / `test_favorite_created_via.py`
- **API tests**: one test file per router
- **E2E tests**: `test_codegarden_phase2b_e2e.py` (full flow + 8898 protection + topology + Playbook 404)
#### Frontend (Vitest + jsdom)
```bash
cd frontend
npm run test:run # All tests
npm run test:watch # watch mode
npx tsc --noEmit # type checking
npm run build # production build (tsc + vite)
```
Test distribution: 60+ component tests, 240+ test cases, covering 4 major domains sub-pages + Settings + Knowledge + CodeGarden.
#### CI
`.github/workflows/ci.yml` runs on push / PR: Python compile + pytest + tsc + vitest + vite build.
---
### Data Sources
| Domain | Data Source | Count |
|---|---|---|
| Tech/AI | aihot.virxact.com | 1 |
| Cybersecurity | Alibaba Cloud Vulnerability Database (AVD) / CNNVD / Security News / FreeBuf / THN / QiAnXin / NSFOCUS / Sogou WeChat | 17+ |
| Finance/Investment | Sina Finance / Tencent Securities | 2 |
| Independent Development/Entrepreneurship | Hacker News / Product Hunt | 2 |
| GitHub | GitHub Trending + Search | 1 |
| Bidding | Government Procurement Network (agent crawling) | 1 |
| Knowledge | Cubox / Browser Bookmarks / SecNews Favorites | 3 |
Complete list in [`backend/collectors/`](file:///Users/duke/Documents/hotspot/backend/collectors).
---
### Phase Roadmap
| Phase | Status | Content |
|---|---|---|
| v1.0–v1.4 | ✅ | Hotspot Aggregation 5 categories + Quality Gates + Sync |
| v1.5 | ✅ | Security Knowledge Graph (MITRE + CVE + compliance) |
| v1.6 | ✅ | CodeGarden Phase 2b (Service Mesh / Resource Hub / Orchestration Engine) |
| v1.7.1–v1.7.5 | ✅ | Phase 1–6: Knowledge Lifecycle + SM-2 Review + Alerts + Personal Profile + KV Cache + FTS |
| **v1.7.6 Phase 7** | ✅ | **MCP Server (13 tools, stdio + SSE)** |
| v1.8 (planned) | 🚧 | Phase 8+: more MCP tools (Cubox full-text search / multi-end synchronization) |
---
### Core Design Principles
1. **Local-first**: all data stored locally, process crash/restart without loss
2. **Simple over complex**: single process, embedded storage, no interface reserved for distributed requirements
3. **Protocol over runtime**: open through standard MCP protocol, AI inference handed over to external agent
4. **Data and intelligence separation**: hotspot exposes data + tools, LLM inference undertaken by external AI Agent
5. **Elegant degradation**: single data source failure does not block other sources; external network failure does not block cache reading
6. **Observable but not heavy**: structured logs + simple metrics, **no introduction** of Prometheus / Grafana
Complete design in [`docs/ARCHITECTURE.md`](file:///Users/duke/Documents/hotspot/docs/ARCHITECTURE.md).
---
### FAQ
**Q: Why not built-in LLM inference?**
A: Let users reason in their own configured AI Agent environment (Cursor/Claude Desktop/Trae), avoid repeated configuration and API key management. hotspot only responsible for data storage + 13 tool exposure.
**Q: Can it support multiple users?**
A: Currently single-user local workstation, no multi-user/permission isolation. SQLite WAL mode `WORKERS=1` is a constraint.
**Q: How to backup data?**
A: 3 options:
1. `backend/data/backup_*.db` (24h rolling, APScheduler auto)
2. WebDAV sync package (Nuts Cloud, zip + Fernet encryption)
3. git track `knowledge/` directory
**Q: Is remote access secure?**
A: Default bind `127.0.0.1`, not exposed to public network. If needed, change `HOST=0.0.0.0` + add nginx reverse proxy + HTTPS.
**Q: What if port conflict?**
A: Backend change `PORT=8001` to start; frontend change `vite --port 8899`. **Note**: CodeGarden Resource Hub's 8898 is a protected port, prohibited from release.
---
### Contribution
PR / Issue welcome! But please read:
- [`AGENTS.md`](file:///Users/duke/Documents/hotspot/AGENTS.md) — Project-level agent rules
- [`CLAUDE.md`](file:///Users/duke/Documents/hotspot/CLAUDE.md) — Complete development guide
- [`docs/IMPROVEMENT_PLAN.md`](file:///Users/duke/Documents/hotspot/docs/IMPROVEMENT_PLAN.md) — Improvement plan
**Prohibited**:
- Submit `.env` / real proxy configuration / personal data
- Introduce new frameworks (Redis / PostgreSQL / Celery) — violate "simple over complex" principle
- Multiple workers — SQLite WAL lock limit
**Recommended**:
- Add data source → inherit `BaseCollector`, add test
- Add quality gate → inherit `BaseGate`, add to `pipeline.py`
- Add MCP tool → add Pydantic in `mcp_types.py`, add operation_id in `mcp_config.py`
---
### License
[LICENSE](file:///Users/duke/Documents/hotspot/LICENSE) — see file for details.
---
### Acknowledgements
- [fastapi-mcp](https://github.com/ycd/manage-fastapi) — MCP protocol integration
- [Anthropic MCP](https://modelcontextprotocol.io/) — MCP protocol specification
- [MITRE ATT&CK](https://attack.mitre.org/) — attack technology ontology (CC-BY-4.0)
- [NVD](https://nvd.nist.gov/) — CVE data source
# Edit backend/proxy_config.json — see "Configure proxy" in English section
# Start backend
python run.py # http://127.0.0.1:8000
# Frontend (in another terminal)
cd frontend && npm install && npm run dev # http://localhost:8898
### Configure MCP Server (recommended)
Open the frontend → top-right **Settings** → **MCP Server** card → click **Copy stdio config**.
Paste into your AI Agent's config:
| AI Agent | Config path |
|---|---|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Trae | `~/.trae/mcp_config.json` |
| Cursor | `~/.cursor/mcp.json` |
| Claude Code | project root `.mcp.json` |
```json
{
"mcpServers": {
"hotspot": {
"command": "python",
"args": ["-m", "backend.mcp_stdio_main"],
"cwd": "/absolute/path/to/secnews"
}
}
}
```
13 tools (5 read + 8 write) will be auto-discovered.
### Tech stack
- **Backend**: Python 3.10+, FastAPI, SQLite (WAL), APScheduler, fastapi-mcp, loguru
- **Frontend**: React 18, Vite 5, TypeScript, Tailwind 3, echarts, recharts
- **Storage**: SQLite + filesystem (`.md` files as source of truth)
- **Crypto**: Fernet (PBKDF2-derived key)
- **Sync**: WebDAV (Nutstore/Nextcloud) with zip + Fernet envelope
- **Tests**: 67 backend pytest + 60+ frontend Vitest (240+ cases)
### License
[LICENSE](file:///Users/duke/Documents/hotspot/LICENSE) — see file for details.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available