LearnMCP-xAPI

LearnMCP-xAPI

LearnMCP-xAPI 是一款开源 MCP（模型上下文协议）服务，可通过符合 xAPI 标准的学习记录存储系统，帮助 AI Agent 记录和检索学习活动。与侧重内容生成或自动评分的传统教育 AI 工具不同，LearnMCP-xAPI 在 AI 交互与学习分析之间搭建桥梁，让智能系统能够构建对学习者所知、所练习和所达成内容的上下文理解。

本项目旨在弥补 AI 教育中的一个根本性缺口：让 AI Agent 能够持续维护结构化的学习进度记录，为未来的交互提供参考，并为技能发展提供证据。无论你是在构建 AI 辅导系统、个性化学习助手，还是教育分析平台，LearnMCP-xAPI 都能提供基础设施，让 AI 交互具备学习感知能力。

重要提示： LearnMCP-xAPI 是教育技术系统的基础组件。它通过持续了解学生的进度，让 AI Agent 能够有意义地参与学习过程，但不能取代审慎的教学设计或人类的教育专业知识。

报告 Bug · 请求新功能 · Wiki

目录

动机

LearnMCP-xAPI 的工作原理

主要功能

架构概览

快速开始

集成指南

许可证

参与贡献

动机

当前教育领域的 AI 格局由一些熟悉的模式主导：预先制作的提示词、自动生成内容，以及学生希望 AI 替自己完成作业、教师则竭力防止这一情况发生的永恒拉锯。这种做法将 AI 视为捷径或障碍，却忽略了智能系统真正支持学习的变革潜力。

LearnMCP-xAPI 的灵感源自对这一根本脱节的观察。大多数教育 AI 工具彼此孤立——它们生成答复、创建活动或分析文本，却不会从学生持续的学习历程中学习，也不会为其做出贡献。它们不会记住学生练习过什么、在哪些方面遇到困难，或掌握了哪些内容。每次交互都从零开始。

学习记录存储（LRS）和 xAPI 规范长期以来一直为记录和分析学习活动提供解决方案，但它们与日益成为教育体验核心的 AI 系统基本脱节。LearnMCP-xAPI 弥合了这一差距，使 AI Agent 既能为全面的学习记录做出贡献，也能从中学习。

这种方法带来的可能性远不止传统的 AI 辅导：

• 自适应 AI 学习伙伴：根据学生此前学过的内容和遇到困难的地方调整讲解方式的 AI 助手。
• 基于证据的评估：教师可以从自然的 AI 交互中收集真实的学习证据，而非依赖人为设计的测试场景。
• 个性化学习路径：根据全面的学习历史推荐后续步骤的 AI 系统。
• 跨平台学习连续性：学生的学习进度可以伴随他们在不同的 AI 教育工具间切换。

我们的目标不是取代教师或传统学习方法，而是打造能够有意义地参与学习过程的 AI 系统——理解上下文、以已有知识为基础，并为更丰富、更个性化的教育体验做出贡献。

LearnMCP-xAPI 的工作原理

LearnMCP-xAPI 实现了 Model Context Protocol（MCP），在 AI Agent 与学习分析基础设施之间建立无缝连接。该系统充当桥梁，将自然语言学习交互转换为结构化 xAPI 语句，同时让 AI Agent 能够了解学生的学习进度。

1. AI Agent 集成：通过 MCP，AI Agent 可以使用三种核心学习工具：记录语句、检索进度和管理活动词汇。

2. 自然语言处理：LearnMCP-xAPI 提供了两种互补的学习活动记录方式：

   • 显式学习活动：当学生直接提及自己的学习情况时——“我今天练习了 Python 循环”或“我不太懂二次方程”——AI Agent 会将其转换为结构化语句。
   • 隐式学习证据：AI Agent 可以分析对话，识别学生展现出的知识或知识缺口，并根据教育对话的自然进程，自动记录诸如“学生成功解释了递归概念”或“学生对数据库联接感到困惑”等证据。

3. xAPI 语句生成：LearnMCP-xAPI 将学习活动转换为符合 xAPI 标准的语句，其中包含学习者（主体）、活动（动词 + 对象）、上下文和结果。这些语句符合教育数据标准，还可以包含分数、完成状态和其他元数据。

4. 学习记录存储系统集成：语句会安全地存储在任何符合 xAPI 1.0.3 标准的 LRS 中。系统会自动处理身份验证、验证和错误恢复。

5. 上下文检索：AI Agent 可以查询学习历史，了解学生练习过什么、取得了哪些成果或遇到了哪些困难。这使 AI Agent 能够基于已有知识作答，并满足个人的学习需求。

6. 保护隐私的设计：每位学生都会获得一个唯一标识符（ACTOR_UUID），用于区分其学习记录并保护隐私。系统不会存储任何个人信息，只存储学习活动和进度指标。

这种架构使 AI 系统能够参与完整的学习周期：了解学生的基础情况，提供有意义的教育互动，并建立学习进度证据，让学生和教育工作者都能从中受益。

主要功能

• 符合 xAPI 1.0.3 规范：完全兼容 xAPI 规范，确保与现有教育技术生态系统互操作，
• MCP 集成：原生支持 Model Context Protocol，可无缝连接 AI Agent。
• 插件架构：可扩展的插件系统，支持多个 Learning Record Store，并可轻松切换配置。
• 支持多种 LRS：内置支持 LRS SQL 和 Ralph LRS，架构设计便于添加新的 LRS 实现。
• 灵活的身份验证：根据 LRS 要求，支持包括 Basic Auth 和 OIDC（OpenID Connect）在内的多种身份验证方式。
• 隐私保护设计：学生标识符可配置，并与个人信息分离，确保教育数据隐私。
• 智能语句生成：自动将自然语言学习活动转换为结构化的 xAPI 语句，并提供适当的评分和上下文。
• 情境化学习查询：AI Agent 可以检索经过筛选的学习历史，以了解学生进度并调整回复。
• 重试逻辑和错误处理：可靠的网络处理确保与 Learning Record Store 稳定通信。
• 教育词汇管理：内置支持常见的学习动词（练习、掌握、体验、达成），并采用可扩展架构。
• 支持多名学生：简单的配置即可部署到课堂、机构或个人学习者。
• 实时学习分析：学习数据可立即使用，为自适应 AI 回复和教育洞察提供支持。

架构概览

LearnMCP-xAPI 采用模块化插件架构，专为教育技术集成和可扩展性而设计。

核心组件：

• MCP 工具层：通过标准化的 MCP 协议向 AI Agent 提供学习功能。
• xAPI 语句引擎：将学习活动转换为符合规范的 xAPI 语句，并进行适当验证。
• 插件系统：通过统一接口支持多种 LRS 实现的可扩展架构。
• LRS 插件：针对不同 Learning Record Store（LRS SQL、Ralph LRS）的专用插件，提供特定的身份验证和通信处理。
• 隐私管理：确保安全处理学生标识符和学习数据。
• 配置系统：灵活支持基于环境变量和文件的配置，并可选择和管理插件。

支持的 Learning Record Store：

• LRS SQL：基于 SQLite 的轻量级 LRS，非常适合开发和小规模部署
• Ralph LRS：France Université Numérique 提供的企业级 LRS，支持 Basic Auth 和 OIDC 身份验证
• Veracity Learning：云端或可自托管的 xAPI 兼容 LRS，全面支持 1.0.3 规范和高级分析
• 插件架构：便于添加新的 LRS 实现，无需修改核心代码

入门指南

前置条件

开始之前，请确保你具备：

• Python 3.8 或更高版本
• 可访问符合 xAPI 规范的 Learning Record Store（开发环境推荐使用 LRS SQL）
• 兼容 MCP 的客户端（例如 Claude Desktop）

安装

选项 1：从源代码安装

# Clone the repository
git clone https://github.com/DavidLMS/learnmcp-xapi.git
cd learnmcp-xapi

# Install dependencies
pip install -r requirements.txt

选项 2：使用 venv 安装

# Clone the repository
git clone https://github.com/DavidLMS/learnmcp-xapi.git
cd learnmcp-xapi

# Create and activate a virtual environment
python -m venv learnmcp-env
source learnmcp-env/bin/activate  # On Windows: learnmcp-env\Scripts\activate

# Install dependencies
pip install -r requirements.txt

选项 3：使用 uv 安装

# Install uv if you don't have it
pip install uv

# Clone the repository
git clone https://github.com/DavidLMS/learnmcp-xapi.git
cd learnmcp-xapi

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt

配置

LearnMCP-xAPI 使用灵活的配置系统，同时支持环境变量和配置文件。

基本设置（环境变量）

复制示例配置文件，并根据你的设置进行自定义：

cp .env.example .env

编辑 .env 文件，设置 LRS 插件选择和学生标识符：

# Required: Choose your LRS plugin
LRS_PLUGIN=lrsql  # Options: lrsql, ralph, veracity

# Required: Unique identifier for each student
ACTOR_UUID=student-12345-67890-abcdef

# LRS SQL Configuration (when LRS_PLUGIN=lrsql)
LRSQL_ENDPOINT=http://localhost:8080
LRSQL_KEY=your-api-key
LRSQL_SECRET=your-api-secret

# Ralph LRS Configuration (when LRS_PLUGIN=ralph)
RALPH_ENDPOINT=http://localhost:8100
RALPH_USERNAME=your-username  # For Basic Auth
RALPH_PASSWORD=your-password  # For Basic Auth
# OR for OIDC:
# RALPH_OIDC_TOKEN_URL=http://keycloak:8080/auth/realms/test/protocol/openid-connect/token
# RALPH_OIDC_CLIENT_ID=ralph
# RALPH_OIDC_CLIENT_SECRET=secret

# Veracity LRS Configuration (when LRS_PLUGIN=veracity)
VERACITY_ENDPOINT=https://your-lrs.lrs.io
VERACITY_LRS_NAME=mylrs
VERACITY_USERNAME=your-access-key-username
VERACITY_PASSWORD=your-access-key-password

高级设置（配置文件）

对于更复杂的部署，可以使用配置文件：

# Create configuration directory structure
mkdir -p config/plugins

# Create LRS-specific configuration files
echo "endpoint: \${LRSQL_ENDPOINT:-http://localhost:8080}
key: \${LRSQL_KEY}
secret: \${LRSQL_SECRET}
timeout: 30
retry_attempts: 3" > config/plugins/lrsql.yaml

echo "endpoint: \${RALPH_ENDPOINT:-http://localhost:8100}
username: \${RALPH_USERNAME}
password: \${RALPH_PASSWORD}
oidc_token_url: \${RALPH_OIDC_TOKEN_URL}
oidc_client_id: \${RALPH_OIDC_CLIENT_ID}
oidc_client_secret: \${RALPH_OIDC_CLIENT_SECRET}
timeout: 30
retry_attempts: 3" > config/plugins/ralph.yaml

请参阅 .env.example，了解所有可用的配置选项和插件专属设置。

快速测试

# Start the MCP server
python -m learnmcp_xapi.main

你应该会看到一条表示服务正在启动的响应。

集成指南

LearnMCP-xAPI 通过其插件架构支持多个学习记录存储（LRS），便于与现有教育技术基础设施集成。

学习记录存储集成

• LRS SQL 设置 - 将 LRS SQL 设置为开发用 LRS 的完整指南。
• Ralph LRS 设置 - 支持基本身份验证和 OIDC 的企业级 LRS 集成。
• Veracity Learning 设置 - 支持高级分析的云端和自托管 LRS。
• 自定义 LRS 集成 - 添加对新学习记录存储支持的指南。

AI 客户端集成

• Claude Desktop 设置 - 逐步介绍如何将 Claude Desktop 连接为 AI 学习伙伴
• 即将推出更多客户端集成……

后续开发计划

LearnMCP-xAPI 正在积极开发中，计划改进的内容包括：

• 更多 LRS 插件：支持更多学习记录存储，包括 TinCan API、xAPI Wrapper 和企业平台。
• 增强身份验证：支持更多身份验证方式，包括 JWT、OAuth 2.0 和基于证书的身份验证。
• 扩展集成测试：为更多学习记录存储和 MCP 客户端提供全面的兼容性测试和设置指南。
• 在线演示环境：交互式演示平台，用户无需本地设置即可测试 LearnMCP-xAPI 的功能。
• 教育评估模板：预构建的系统提示词，使 AI Agent 能够根据特定课程标准、评估准则和教育法规要求记录学习证据。
• 可互换的学习档案：动态档案系统，AI Agent 可直接从 MCP 服务获取评估标准和记录格式，无需手动配置提示词。

许可证

LearnMCP-xAPI 根据 MIT 许可证 发布。你可以自由地将代码用于商业或非商业用途，也可以对其进行修改和分发。

贡献

欢迎为 LearnMCP-xAPI 做出贡献！无论是改进代码、完善文档，还是提出新功能建议，你的意见都很有价值。请查看 CONTRIBUTING.md，了解如何开始并有效贡献。

我们尤其欢迎以下方面的贡献：

• 新 LRS 插件：使用我们的插件架构，为更多学习记录存储实现支持
• 身份验证方式：添加对新身份验证协议和安全标准的支持
• 插件测试：全面测试现有和新增的插件实现
• MCP 客户端示例：新增 MCP 客户端实现和集成示例
• 教育应用案例：真实应用案例研究和最佳实践文档
• 性能优化：提升插件性能和资源利用率