Learnhouse MCP

LearnHouse MCP服务器

LearnHouse LMS的模型上下文协议（MCP）服务器

此MCP服务器为AI代理（如GitHub Copilot、Claude和其他AI助手）提供了以编程方式管理LearnHouse学习管理系统实例的能力。

📋 目录

• 概述
• 建筑
• 安装和设置
• 配置
• 可用工具
• 数据模型
• 用法示例
• VS代码集成
• api参考
• 测试结果
• 故障排除

______________________________________________________________________

概述

什么是MCP？

这 模型上下文协议（MCP） 是由Anthropic开发的开放标准，使AI助手能够通过标准化的界面与外部系统进行交互。MCP允许AI模型动态发现和使用工具，而不是硬编码集成。

这个服务器做什么？

LearnHouse MCP服务器公开 21工具 允许AI代理：

• 管理课程：创建、阅读、更新、删除课程
• 组织章节：将课程内容分为章节
• 创建活动：添加学习材料（文档、视频、PDF）
• 设置内容：使用TipTap文档或视频URL填充活动
• 跟踪进度：通过课程监控用户进度
• 搜索：跨课程和内容搜索

为什么使用MCP而不是直接的API调用？

1. 标准化接口：AI模型可以自动发现工具
2. 类型安全：Zod模式验证所有参数
3. 已处理身份验证：一次性登录，持久会话
4. 错误处理：一致的错误响应
5. 多代理就绪：任何与MCP兼容的代理都可以使用这些工具

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────────────────┐
│                        VS Code / AI Agent                        │
│                   (GitHub Copilot, Claude, etc.)                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │ stdio (JSON-RPC)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    LearnHouse MCP Server                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                     FastMCP Framework                     │    │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐│    │
│  │  │ Course  │ │ Chapter │ │Activity │ │ Progress/Search ││    │
│  │  │  Tools  │ │  Tools  │ │  Tools  │ │     Tools       ││    │
│  │  └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘│    │
│  └───────┼───────────┼───────────┼───────────────┼─────────┘    │
│          │           │           │               │               │
│  ┌───────┴───────────┴───────────┴───────────────┴─────────┐    │
│  │                  LearnHouseClient (API Wrapper)          │    │
│  │  • Authentication (login, token management)              │    │
│  │  • HTTP Methods (GET, POST, PUT, DELETE)                 │    │
│  │  • Error Handling                                        │    │
│  └─────────────────────────────┬───────────────────────────┘    │
└────────────────────────────────┼────────────────────────────────┘
                                 │ HTTPS
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│                    LearnHouse API (FastAPI)                      │
│                   http://localhost:3000                          │
└─────────────────────────────────────────────────────────────────┘

关键组件

______________________________________________________________________

安装和设置

选项A：使用NPM（推荐）

您可以直接运行服务器，而无需安装仓库，使用 npx.

npx -y learnhouse-mcp-server@latest

MCP配置(mcp_config.json):

{
  "mcpServers": {
    "learnhouse-remote": {
      "command": "npx",
      "args": ["-y", "learnhouse-mcp-server@latest"],
      "env": {
        "LEARNHOUSE_URL": "https://your-learnhouse-instance.com",
        "LEARNHOUSE_EMAIL": "admin@example.com",
        "LEARNHOUSE_PASSWORD": "your_password",
        "LEARNHOUSE_ORG_ID": "1"
      }
    }
  }
}

选项B：地方发展（来源）

如果要修改服务器代码或进行贡献，请使用此选项。

先决条件

• Node.js 18+
• pnpm （或npm/yarn）
• LearnHouse实例 具有管理员凭据
• VS Code 使用GitHub Copilot（用于集成）

安装依赖项

cd .mcp
pnpm install

建造（用于生产）

pnpm build

以开发模式运行

pnpm dev

测试服务器

# Inspect available tools
pnpm inspect

# Run API tests
pnpm test

______________________________________________________________________

配置

环境变量

VS代码配置

MCP服务器配置在 .vscode/mcp.json:

{
  "servers": {
    "learnhouse": {
      "command": "npx",
      "args": ["tsx", "${workspaceFolder}/.mcp/src/index.ts"],
      "env": {
        "LEARNHOUSE_URL": "http://localhost:3000",
        "LEARNHOUSE_EMAIL": "admin@example.com",
        "LEARNHOUSE_PASSWORD": "YourPassword",
        "LEARNHOUSE_ORG_ID": "1"
      }
    }
  }
}

______________________________________________________________________

可用工具

课程管理（5个工具）

章节管理（4个工具）

活动管理（6个工具）

内容工具（1个工具）

用户和组织（2个工具）

进度跟踪（2个工具）

搜索（1个工具）

______________________________________________________________________

数据模型

活动类型

enum ActivityType {
  TYPE_DYNAMIC = "TYPE_DYNAMIC", // Rich text document (TipTap)
  TYPE_VIDEO = "TYPE_VIDEO", // Video content
  TYPE_DOCUMENT = "TYPE_DOCUMENT", // PDF or document
  TYPE_ASSIGNMENT = "TYPE_ASSIGNMENT", // Assignment
  TYPE_CUSTOM = "TYPE_CUSTOM", // Custom type
}

enum ActivitySubType {
  SUBTYPE_DYNAMIC_PAGE = "SUBTYPE_DYNAMIC_PAGE", // TipTap editor page
  SUBTYPE_VIDEO_YOUTUBE = "SUBTYPE_VIDEO_YOUTUBE", // YouTube embed
  SUBTYPE_VIDEO_HOSTED = "SUBTYPE_VIDEO_HOSTED", // Self-hosted video
  SUBTYPE_DOCUMENT_PDF = "SUBTYPE_DOCUMENT_PDF", // PDF viewer
  SUBTYPE_DOCUMENT_DOC = "SUBTYPE_DOCUMENT_DOC", // Document
}

TipTap文档结构

LearnHouse使用 TipTap 的 作为其富文本编辑器。内容以JSON格式存储：

{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [{ "type": "text", "text": "Welcome" }]
    },
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "This is a paragraph." }]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            {
              "type": "paragraph",
              "content": [{ "type": "text", "text": "Item 1" }]
            }
          ]
        }
      ]
    }
  ]
}

课程结构

Organization (org_id: 1)
└── Course (course_uuid)
    ├── name: string
    ├── description: string
    ├── public: boolean
    ├── published: boolean
    └── chapters[]
        └── Chapter (chapter_id, chapter_uuid)
            ├── name: string
            ├── description: string
            └── activities[]
                └── Activity (activity_uuid)
                    ├── name: string
                    ├── activity_type: ActivityType
                    ├── activity_sub_type: ActivitySubType
                    ├── content: TipTapDocument | VideoContent
                    └── published: boolean

______________________________________________________________________

用法示例

示例1：创建完整课程

User: Create a course called "Python Fundamentals" with two chapters

AI Agent (using MCP tools):
1. create_course(name: "Python Fundamentals", description: "Learn Python basics")
   → Returns course_uuid: "course_abc123"

2. create_chapter(course_id: 15, name: "Getting Started")
   → Returns chapter_id: 70

3. create_chapter(course_id: 15, name: "Variables & Data Types")
   → Returns chapter_id: 71

4. create_activity(chapter_id: 70, name: "Introduction to Python", activity_type: "TYPE_DYNAMIC")
   → Returns activity_uuid: "activity_xyz789"

5. set_document_content(activity_uuid: "activity_xyz789", content: {...tiptap json...})
   → Content saved

6. publish_activity(activity_uuid: "activity_xyz789")
   → Activity published

示例2：添加YouTube视频

User: Add a YouTube tutorial to chapter 70

AI Agent (using MCP tools):
1. create_activity(
     chapter_id: 70,
     name: "Python Tutorial Video",
     activity_type: "TYPE_VIDEO",
     activity_sub_type: "SUBTYPE_VIDEO_YOUTUBE"
   )
   → Returns activity_uuid: "activity_video123"

2. set_video_content(
     activity_uuid: "activity_video123",
     video_url: "https://www.youtube.com/watch?v=example"
   )
   → Video URL set

3. publish_activity(activity_uuid: "activity_video123")
   → Published

示例3：搜索和更新

User: Find all courses about MCP and update their descriptions

AI Agent (using MCP tools):
1. search(query: "MCP")
   → Returns: [{course_uuid: "course_mcp1", name: "MCP Introduction"}]

2. update_course(
     course_uuid: "course_mcp1",
     description: "Updated description for MCP course"
   )
   → Course updated

______________________________________________________________________

VS代码集成

运作原理

1. VS代码加载 mcp.json 启动时
2. 启动MCP服务器 作为子流程
3. 工具可用 转到GitHub Copilot
4. AI代理发现工具 通过MCP协议
5. 工具执行 并返回结果

验证服务器

在VS代码中：

1. 打开命令选项板(Ctrl+Shift+P)
2. 运行“开发人员：显示MCP工具”
3. 您应该看到所有21个LearnHouse工具

与Copilot一起使用

只需让Copilot执行LearnHouse操作：

“列出LearnHouse中的所有课程” “在课程5中创建一个名为“引言”的新章节” “搜索有关Python的课程”

______________________________________________________________________

api参考

基本URL

http://localhost:3000/api/v1

认证

客户使用 OAuth2密码流:

POST /auth/login
Content-Type: application/x-www-form-urlencoded

username=admin@example.com&password=YourPassword

退货：

{
  "user": { "id": 1, "email": "admin@example.com", ... },
  "tokens": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ..."
  }
}

关键终点

______________________________________________________________________

测试结果

工具验证（2026年1月23日）

结果：18/21个工具有效（成功率86%）

3个失败的工具有后端API问题，而不是MCP服务器错误。

______________________________________________________________________

故障排除

服务器无法启动

# Check Node.js version
node --version  # Should be 18+

# Reinstall dependencies
cd .mcp
rm -rf node_modules
pnpm install

身份验证失败

1. 验证环境变量中的凭据
2. 检查用户是否存在于LearnHouse中
3. 确保用户具有管理员权限

工具返回“未找到”

• 验证UUID/ID是否存在
• 检查资源是否在正确的组织中
• 某些端点需要用户注册（进度工具）

“找不到模块”错误

# Rebuild TypeScript
pnpm build

VS Code不显示工具

1. 重新加载VS代码窗口
2. 检查 .vscode/mcp.json 语法
3. 查看输出→ “MCP”通道错误

______________________________________________________________________

依赖项

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证

______________________________________________________________________

贡献

1. 分叉存储库
2. 创建要素分支
3. 对以下内容进行更改 .mcp/src/
4. 测试用 pnpm inspect
5. 提交拉取请求

______________________________________________________________________

相关文件

• 学习API文档
• MCP规范
• TipTap文档