词汇应用程序
全栈间隔重复词汇学习系统。人工智能助手可以通过MCP工具将单词直接推送到您的个人学习平台，您可以在可安装的移动PWA上查看它们。
组件
| 组件 | 描述 |
|---|---|
backend/ | FastAPI+SQLite REST API |
mcp-server/ | MCP服务器暴露 add_vocabulary AI助手 |
pwa/ | 可安装的PWA闪卡学习应用程序 |
______________________________________________________________________
1.后端API
在本地运行
cd backend
uv sync
# Create a .env file
echo "API_KEY=$(openssl rand -hex 32)" > .env
echo "DATABASE_PATH=./vocab.db" >> .env
uv run --env-file .env uvicorn main:app --reloadAPI将于 http://localhost:8000.互动文档 http://localhost:8000/docs.
测试终点
export API_KEY=
# Health check (no auth required)
curl http://localhost:8000/health
# Add a word
curl -X POST http://localhost:8000/vocabulary \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"word":"épanouissement","definition":"A blossoming or fulfillment","language":"French"}'
# List all words
curl http://localhost:8000/vocabulary -H "X-API-Key: $API_KEY"
# Words due for review
curl http://localhost:8000/vocabulary/due -H "X-API-Key: $API_KEY"
# Submit a review (quality 0-5)
curl -X PATCH http://localhost:8000/vocabulary/1/review \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"quality":4}'
# Delete a word
curl -X DELETE http://localhost:8000/vocabulary/1 -H "X-API-Key: $API_KEY"部署
- 在任何支持Python的平台上托管后端（例如VPS、容器服务或PaaS）。
- 为SQLite数据库装载一个持久卷。
- 设置环境变量：
- API_KEY --生成与 openssl rand -hex 32 - DATABASE_PATH --路径到 .db 持久卷上的文件
- 启动命令：
uvicorn main:app --host 0.0.0.0 --port $PORT - 确认服务正在运行：
curl https://your-backend-url/health
______________________________________________________________________
2.MCP服务器
设置
cd mcp-server
uv sync
cat > .env
EOF配置您的AI助手
使用AI助手的配置注册MCP服务器。指向 mcp-server/server.py 并传递以下环境变量：
VOCAB_API_URL--已部署后端的基本URLVOCAB_API_KEY-来自后端的API密钥.env
配置后，您可以询问您的助手： *“将‘繁荣’保存到我的Vocab甲板。”*
______________________________________________________________________
3.PWA
在本地运行
打开 pwa/index.html 直接在浏览器中或与任何静态文件服务器一起使用：
cd pwa
npx serve .更新 API_URL 和 API_KEY 顶部的常数 pwa/app.js 指向您部署的后端。
部署
主机 pwa/ 文件夹作为任何静态托管提供商上的静态站点。该网站 必须 通过HTTPS为服务人员提供服务，并“添加到主屏幕”工作。
在移动设备上安装
- 网间网操作系统： 在Safari中打开→ 分享→ 添加到主屏幕
- 安卓： 在Chrome中打开→ menu → 添加到主屏幕/安装应用程序
______________________________________________________________________
安全说明
- PWA仅通过服务器端代理与后端通信(
functions/api/).API密钥从不向浏览器公开。 - 商店
BACKEND_URL（以及任何秘密）作为托管平台中的环境变量——永远不要将它们提交给版本控制。 - 后端允许所有CORS源(
*).如果需要，在部署后限制到PWA的域。
______________________________________________________________________
建筑
AI Assistant
│ MCP tool: add_vocabulary
▼
MCP Server (local) — POST /vocabulary
▼
Backend API — SQLite
▼
PWA — GET /vocabulary/due → flashcard study → PATCH /vocabulary/{id}/review