内容
# LinguaMCP
> [English](./README.md) | [繁體中文（台灣）](./docs/README.zh-TW.md) | [繁體中文（香港）](./docs/README.zh-HK.md) | [简体中文](./docs/README.zh-CN.md)
> 开放式课程协议，适用于 AI 语言辅导 — 通过日常练习与任何 AI 工具自然学习。
## 什么是 LinguaMCP？
LinguaMCP 是一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io/) 服务器，提供每日语言课程，来自结构化的课程内容。它适用于 Claude、Cursor、Windsurf 或任何支持 MCP 的 AI 工具。
你不需要使用闪存卡或语法练习，而是通过对话自然地进行练习。你的 AI 辅导员知道你已经学了什么，跟踪你的进度，并在你准备好时引入新内容。
## 快速开始
### 选项 1：零配置 SQLite（推荐）
```bash
# 全局安装
npm install -g lingua-mcp
# 初始化数据库和课程
lingua-mcp-init
# 启动服务器
lingua-mcp
```
就这样。不需要设置数据库，不需要 API 密钥，也不需要云服务。你的进度存储在 `~/.lingua-mcp/lingua.db`。
### 选项 2：Supabase（云或自托管）
```bash
# 克隆并安装
git clone https://github.com/Marsmanleo/LinguaMCP.git
cd LinguaMCP
npm install
# 设置环境
cp .env.example .env
# 使用你的 Supabase 凭证编辑 .env
# 运行 Supabase 迁移（在 supabase/migrations/ 中）
# 然后导入课程
npm run ingest
# 启动服务器
npm start
```
## 配置你的 AI 工具
### Claude Desktop
添加到你的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"lingua": {
"command": "npx",
"args": ["-y", "lingua-mcp"]
}
}
}
```
### Cursor / Windsurf
添加到你的 MCP 设置中：
```json
{
"lingua": {
"command": "node",
"args": ["/path/to/LinguaMCP/server.mjs"]
}
}
```
### Supabase 模式
在启动前设置环境变量：
```bash
SUPABASE_BASE_URL=https://your-project.supabase.co \
SUPABASE_ANON_KEY=your-anon-key \
node server.mjs
```
## MCP 工具
连接后，你的 AI 工具将获得 **六种工具** — 三种用于练习，三种用于内容管理：
### 练习工具
| 工具 | 描述 |
|------|-------------|
| `get_today_lesson` | 返回你的下一个未掌握的课程，包含上下文和练习提示 |
| `get_user_progress` | 显示掌握、练习和剩余的计数 |
| `log_response` | 记录你的练习响应（分数 1-5，≥4 = 掌握） |
### 内容管理工具
| 工具 | 描述 |
|------|-------------|
| `add_lesson` | 添加一个新课程到章节（标题、内容、类型、难度、标签） |
| `add_resource` | 链接外部资源到课程（YouTube、文章、播客） |
| `remove_lesson` | 软删除课程（标记为废弃，不再提供） |
#### 添加课程
你的 AI 可以从任何来源添加课程 — YouTube 频道、文章或原创内容：
```
AI: "我找到一个关于 'however' vs 'although' 的很好的 YouTube 视频。
我应该把它添加为一个课程吗？"
你: "是的，添加到 Linking Words 技能书中"
AI: → 调用 add_lesson，包含标题、内容、难度
← "课程添加成功"
```
#### 管理资源
链接外部材料到任何课程以供参考：
```
AI: → 调用 add_resource，包含 lesson_id、url、type="youtube"
← "资源 'Emily Daily English EP1' 已添加"
```
#### 删除低质量课程
标记课程为废弃而不删除数据：
```
AI: → 调用 remove_lesson，包含 lesson_id、reason="not useful"
← "课程已废弃"
```
## 课程内容
目前使用来自 [English-level-up-tips](https://github.com/byoungd/English-level-up-tips) 的结构化内容（50k+ 星，MIT 许可证）。
**可用技能书：**
- 🔗 **Linking Words** — 4 章节，20 个课程，涵盖对比、添加、因果和条件连接词
更多技能书和语言即将推出。
## 工作原理
```
┌─────────────┐ MCP ┌─────────────┐ 查询 ┌──────────┐
│ 你的 AI │──────────────▶│ LinguaMCP │──────────────▶│ 数据库 │
│ 工具 │◀──────────────│ 服务器 │◀──────────────│ │
└─────────────┘ 课程 & └─────────────┘ 进度 & └──────────┘
进度 课程
```
1. 你正常地与你的 AI 工具聊天
2. AI 调用 LinguaMCP 获取当天的课程
3. 你通过对话进行练习
4. LinguaMCP 跟踪你已经掌握的内容和下一个课程
## 架构
```
server.mjs ← MCP 服务器入口点
storage/
interface.mjs ← 存储接口
supabase.mjs ← Supabase/PostgREST 适配器
sqlite.mjs ← SQLite 适配器（零配置）
schema/
sqlite.sql ← SQLite 架构
scripts/
ingest-english-tips.ts ← 内容导入（Supabase）
init-sqlite.mjs ← 内容导入（SQLite）
src/
index.ts ← TypeScript 类型
```
## 存储模式
| 模式 | 何时 | 数据库 | 最适合 |
|------|------|----------|----------|
| **SQLite** | 未设置 `SUPABASE_BASE_URL` | `~/.lingua-mcp/lingua.db` | 个人使用、自托管 |
| **Supabase** | 已设置 `SUPABASE_BASE_URL` | PostgreSQL via PostgREST | 云、多用户、团队 |
相同的工具、相同的响应、相同的课程。服务器自动检测使用哪种模式。
## 贡献
参见 [CONTRIBUTING.md](./CONTRIBUTING.md)，了解如何添加课程内容、存储适配器或语言支持。
## 许可证
Apache License 2.0 — 参见 [LICENSE](./LICENSE)。
课程内容来自 English-level-up-tips，遵循 MIT 许可证。
## 相关
- [MarsNMe](https://github.com/Marsmanleo/MarsNMe) — AI 记忆伴侣（姊妹项目）
- [模型上下文协议](https://modelcontextprotocol.io/) — 使此功能得以实现的协议
