使用说明

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调用？

标准化接口：AI模型可以自动发现工具
类型安全：Zod模式验证所有参数
已处理身份验证：一次性登录，持久会话
错误处理：一致的错误响应
多代理就绪：任何与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                          │
└─────────────────────────────────────────────────────────────────┘

关键组件

组件	文件	描述
MCP 服务器	`src/index.ts`	使用Zod模式的工具定义
API客户端	`src/client.ts`	LearnHouseClient包装类
类型定义	`src/types.ts`	TypeScript接口和枚举
配置	`.vscode/mcp.json`	VS代码MCP服务器配置

安装和设置

选项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

配置

环境变量

变量	描述	默认值
`LEARNHOUSE_URL`	LearnHouse API的基本URL	`http://localhost:3000`
`LEARNHOUSE_EMAIL`	用于身份验证的管理员电子邮件	必填
`LEARNHOUSE_PASSWORD`	管理员密码	必填
`LEARNHOUSE_ORG_ID`	组织ID	`1`

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个工具）

工具	说明	参数
`list_courses`	列出组织中的所有课程	`page?`, `limit?`
`get_course`	获取详细的课程信息	`course_uuid`
`create_course`	创建新课程	`name`, `description`, `public?`
`update_course`	更新现有课程	`course_uuid`, `name?`, `description?`, `published?`
`delete_course`	删除课程	`course_uuid`

章节管理（4个工具）

工具	说明	参数
`list_chapters`	列出课程中的所有章节	`course_id`
`get_chapter`	获取章节详细信息	`chapter_id`
`create_chapter`	创建新章节	`course_id`, `name`, `description?`, `org_id?`
`update_chapter`	更新章节	`chapter_id`, `name?`, `description?`

活动管理（6个工具）

工具	说明	参数
`list_activities`	在一章中列出所有活动	`chapter_id`
`get_activity`	获取活动详细信息	`activity_uuid`
`create_activity`	创建新活动	`chapter_id`, `name`, `activity_type?`, `activity_sub_type?`, `published?`
`update_activity`	更新活动	`activity_uuid`, `name?`, `published?`
`publish_activity`	发布活动	`activity_uuid`
`set_document_content`	设置TipTap文档内容	`activity_uuid`, `content` （JSON字符串）

内容工具（1个工具）

工具	说明	参数
`set_video_content`	设置活动的视频URL	`activity_uuid`, `video_url`

用户和组织（2个工具）

工具	说明	参数
`get_current_user`	获取经过身份验证的用户信息	无
`get_organization`	获取组织详细信息	`org_id?`

进度跟踪（2个工具）

工具	说明	参数
`get_course_progress`	获取用户的课程进度	`course_uuid`
`mark_activity_complete`	将活动标记为已完成	`activity_uuid`

搜索（1个工具）

工具	说明	参数
`search`	搜索课程和内容	`query`, `org_slug?`

数据模型

活动类型

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代码集成

运作原理

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

验证服务器

在VS代码中：

打开命令选项板(Ctrl+Shift+P)
运行“开发人员：显示MCP工具”
您应该看到所有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..."
  }
}

关键终点

方法	端点	描述
得到	`/courses/org_slug/{slug}/page/{p}/limit/{l}`	列出课程
得到	`/courses/{uuid}`	获取课程
职位	`/courses/`	创建课程
PUT	`/courses/{uuid}`	更新课程
删除	`/courses/{uuid}`	删除课程
得到	`/chapters/{id}`	获取章节
职位	`/chapters/`	创建章节
PUT	`/chapters/{id}`	更新章节
得到	`/activities/{uuid}`	获取活动
职位	`/activities/`	创建活动
PUT	`/activities/{uuid}`	更新活动
得到	`/search/org_slug/{slug}?query=`	搜索

测试结果

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

#	工具	状态	注释
1	`list_courses`	✅ 通过	返回12门课程
2	`get_course`	✅ 通行证	已检索课程详细信息
3	`create_course`	✅ 通过	创建课程id=13
4	`update_course`	✅ 通行证	姓名已更新
5	`delete_course`	✅ 通过	课程已删除
6	`list_chapters`	❌ API错误	HTTP 500（后端问题）
7	`get_chapter`	✅ 通过	检索到章节详细信息
8	`create_chapter`	✅ 通过	创建章节id=62
9	`update_chapter`	✅ 通行证	姓名/描述已更新
10	`list_activities`	✅ 通行证	列出的活动
11	`get_activity`	✅ 通过	检索到活动详细信息
12	`create_activity`	✅ Pass	创建的活动（文档和视频）
13	`update_activity`	✅ 通行证	姓名已更新
14	`publish_activity`	✅ Pass	活动已发布
15	`set_document_content`	✅ Pass	TipTap内容集
16	`set_video_content`	✅ 传递	YouTube URL集
17	`get_current_user`	✅ 通过	admin@example.com
18	`get_organization`	✅ Pass	AgentOne组织详细信息
19	`search`	✅ 通过	找到课程
20	`get_course_progress`	❌ API错误	需要注册
21	`mark_activity_complete`	❌ API错误	需要注册

结果：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

身份验证失败

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

工具返回“未找到”

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

“找不到模块”错误

# Rebuild TypeScript
pnpm build

VS Code不显示工具

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

依赖项

包装	版本	用途
`fastmcp`	^3.29.0	MCP框架
`zod`	^3.23.8	模式验证
`typescript`	^5.x	类型安全
`tsx`	^4.x	TypeScript执行

许可证

MIT许可证-请参阅许可证

贡献

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