你的 markdown 笔记目录
                         │  notes-mcp server 启动时自动建库
                         ▼
        ┌────────────────────────────────────┐
        │   notes-mcp server(FastMCP)        │
        │   · Chroma 向量库(语义检索)        │
        │   · BM25 索引(关键词检索)          │
        │   · SQLite 增量状态(只更新变化)    │
        │                                    │
        │   暴露三大原语:                     │
        │     Tools    / Resources / Prompts │
        └────────────────────────────────────┘
            │ MCP 协议(stdio)
            ▼
┌──────────────────────────────────────────────┐
│       Spring Boot 后端(port 8000)            │
│       · ProviderRouter(多 Provider 路由)      │
│       · ChatHistoryService(对话记录 SQLite)  │
│       · MCP client(调用 notes-mcp 工具)      │
└──────────────────────────────────────────────┘
            │ REST API(/api/*)
            ▼
┌──────────────────────────────────────────────┐
│       React 前端(port 5173)                  │
│       · 三栏布局(侧边栏/对话/信息)           │
│       · 设置中心(Provider/模型/笔记目录)     │
│       · 学习模式(讲解/复习/自测/对比)        │
│       · 笔记详情页(Markdown 渲染)            │
│       · 对话记录持久化                        │
└──────────────────────────────────────────────┘

cd notes-mcp
python -m venv venv && venv\Scripts\activate
pip install -r requirements.txt
pip install -e .
cp .env.example .env
# 编辑 .env:NOTES_DIR=d:/你的笔记目录
python -m notes_mcp index   # 首次建库

cd web/backend
mvn spring-boot:run
# 启动在 http://localhost:8000

cd web/frontend
npm install
npm run dev
# 启动在 http://localhost:5173

{
  "mcpServers": {
    "notes-mcp": {
      "command": "python",
      "args": ["-m", "notes_mcp", "serve", "--transport", "stdio"]
    }
  }
}

notes-mcp/
├── notes_mcp/              # Python MCP Server
│   ├── server.py           # FastMCP:三大原语 + lifespan 建库
│   ├── indexer.py          # 增量建库(Chroma + BM25 + SQLite)
│   ├── search.py           # Hybrid 检索(RRF 融合)
│   ├── embedder.py         # OllamaEmbedder(bge-m3)
│   ├── chunker.py          # Markdown 切块
│   ├── cli.py              # CLI:serve / index / query
│   └── config.py           # 读 .env
├── web/
│   ├── backend/            # Spring Boot 后端
│   │   └── src/main/java/com/notesmcp/backend/
│   │       ├── ProviderRouter.java    # 多 Provider 路由
│   │       ├── SettingsService.java   # 配置管理
│   │       ├── ChatHistoryService.java # 对话记录 SQLite
│   │       ├── ChatController.java    # /api/chat
│   │       ├── NotesController.java   # /api/notes/*
│   │       ├── SettingsController.java # /api/settings/*
│   │       ├── SessionController.java  # /api/sessions/*
│   │       └── ...
│   └── frontend/           # React 前端
│       └── src/
│           ├── components/ # Header/Sidebar/ChatArea/SettingsDrawer/...
│           ├── pages/      # HomePage/NoteDetailPage/DashboardPage/LearningPage
│           └── api/        # API 客户端(client.ts + settings.ts)
├── agent.py                # 消费侧 LangGraph agent(命令行)
├── settings.json           # 多 Provider 配置(运行时可切换)
├── docs/                   # 设计文档 + 开发规范 + 踩坑记录
├── tests/                  # pytest(96 tests)
└── scripts/dev.py          # 统一开发命令(lint/type/test/coverage)

# Python 端
python scripts/dev.py lint        # ruff 检查
python scripts/dev.py type        # mypy 类型检查
python scripts/dev.py test        # pytest(96 tests)

# Java 端
cd web/backend && mvn compile

# 前端
cd web/frontend && npx tsc --noEmit && npx vite build