MCP 服务器

mcpUPB

MCP server that turns UPB Virtual (Moodle) into a structured knowledge source, enabling AI assistants to query courses, assignments, deadlines, announcements, and sync materials via REST API.

README

An <a href="https://modelcontextprotocol.io">MCP</a> server for UPB Virtual (Moodle) — turn your university LMS into a structured knowledge source an AI assistant can query, sync and reason over.

"What's due this week?" · "Summarize the latest announcement" · "Build a study plan from this course" · "Sync all my Algorithms material to markdown"

It talks to Moodle's official Web Services REST API (no browser scraping), so it's fast and robust. Although it's tuned for UPB Virtual, it works against any Moodle site with web services enabled — just change MOODLE_BASE_URL.

⚠️ Personal tool. It acts on your account with your token. Respect your institution's terms of service and only access data you're entitled to.

How it works

flowchart LR
    A["🤖 AI Assistant<br/>(Claude, mcpjam…)"] -- MCP / stdio --> B
    subgraph B ["mcp-upb server"]
        T["🛠️ Tools"]
        R["📚 Resources<br/>upb://…"]
        P["💬 Prompts"]
    end
    B --> C["Moodle REST client<br/>(token auth)"]
    C -- "webservice/rest/server.php" --> M[("🎓 UPB Virtual<br/>Moodle")]
    B --> V["🔄 Vault sync"]
    V --> D["🗂️ vault/<br/>markdown + files"]

A typical request flows straight through to the LMS and back as clean JSON:

sequenceDiagram
    participant U as You
    participant AI as AI Assistant
    participant S as mcp-upb
    participant M as Moodle
    U->>AI: "What's due this week?"
    AI->>S: weekly_digest()
    S->>M: core_calendar / forum / messages
    M-->>S: JSON
    S-->>AI: deadlines + announcements + alerts
    AI-->>U: "3 things due, 1 overdue…"

Features

Tools

Tool	Description
`whoami`	Verify the connection; return the authenticated user + site info
`list_courses`	All enrolled courses
`search_courses`	Search the site catalogue
`get_course`	Sections, activities and downloadable files of a course
`list_assignments`	Assignments (deadlines + attachments) for one or more courses
`get_assignment`	Full detail of one assignment
`submission_status`	Whether an assignment is submitted, plus grade/feedback
`get_grades`	Grade items and your grades for a course
`list_announcements`	Latest announcements for a course
`latest_announcements`	Latest announcements across all courses
`notifications`	Recent Moodle notifications
`upcoming_deadlines`	Calendar deadlines across all courses, sorted
`weekly_digest`	One overview: deadlines + announcements + unread notifications
`download_file`	Download a Moodle file by its `fileurl` to `./downloads`
`pdf_to_markdown`	Convert a local PDF to markdown (text layer)
`save_markdown`	Save markdown into the vault
`sync_course`	Download all new files of a course into the vault, converting PDFs (incremental)
`sync_all`	Sync every enrolled course

Resources

Browsable upb:// URIs a client can attach as context:

upb://courses — enrolled courses
upb://course/{id} — a course's contents
upb://course/{id}/assignments — a course's assignments

Prompts

Ready-made commands: weekly_summary, study_plan (arg: course), assignment_checklist (arg: assignment).

Setup

npm install
cp .env.example .env        # Windows: copy .env.example .env
npm run get-token           # enter your UPB username + password

get-token calls login/token.php and prints a MOODLE_TOKEN=... line. Paste it into .env. Your password is never stored — only the token, which lives in .env (gitignored).

If get-token fails with an invalid-login error, your account may use SSO/Google login, which can disable password-based tokens. In that case generate a token manually in Moodle under Preferences → Security keys and paste it into .env.

Environment variables

Variable	Default	Purpose
`MOODLE_BASE_URL`	`https://www.upbvirtual.net/upbvirtual`	Moodle site root (no trailing slash)
`MOODLE_TOKEN`	—	Web-services token (required)
`DOWNLOAD_DIR`	`./downloads`	Where `download_file` saves
`VAULT_DIR`	`./vault`	Where synced material is written
`CACHE_DIR`	`./.cache`	Incremental-sync metadata

Testing with mcpjam

mcpjam spawns the server as a stdio process and gives you a UI to run tools, browse resources and chat against an LLM.

Launch the inspector (opens http://127.0.0.1:6274):

npm run inspect          # = npx @mcpjam/inspector@latest

Add Server → STDIO:

Field Value

Transport STDIO

Command npx

Arguments tsx src/server.ts

Working directory the project root

Environment MOODLE_TOKEN=<token> (most reliable; avoids .env/cwd issues)

For the compiled build: npm run build, then Command node, Arguments dist/server.js.
Open Tools and start with whoami. Then list_courses → copy an id → get_course, list_assignments, get_grades, etc.

Field	Value
Transport	`STDIO`
Command	`npx`
Arguments	`tsx src/server.ts`
Working directory	the project root
Environment	`MOODLE_TOKEN=<token>` (most reliable; avoids `.env`/cwd issues)

Use with Claude / other MCP clients

After npm run build, add to your client's MCP config:

{
  "mcpServers": {
    "upb": {
      "command": "node",
      "args": ["C:/Users/User/Desktop/GitHub/mcpUPB/dist/server.js"],
      "env": { "MOODLE_TOKEN": "your-token-here" }
    }
  }
}

Scripts

Script	What it does
`npm run dev`	Run the server with tsx (stdio)
`npm run build`	Compile to `dist/`
`npm start`	Run the compiled server
`npm run get-token`	Exchange credentials for a token
`npm run inspect`	Launch mcpjam inspector

Notes & limitations

pdf_to_markdown / sync_course extract the PDF text layer only (good for slides and notes; no tables/math reconstruction). For high-fidelity conversion, plug in a Docling / PyMuPDF4LLM helper — the rest of the pipeline is unchanged.
Available data depends on what your Moodle role/capabilities expose via web services; some tools may return errors if a function is disabled site-wide.

Project structure

src/
  server.ts          MCP server entry (stdio)
  config.ts          env config
  tools.ts           tool registrations
  resources.ts       upb:// resources
  prompts.ts         prompt templates
  moodle/
    client.ts        REST transport (token, params, file urls)
    api.ts           typed Moodle function wrappers
  storage/
    cache.ts         incremental-sync cache
  vault/
    sync.ts          sync_course / sync_all
    pdf.ts           pdf -> markdown
    markdown.ts      vault writer
scripts/
  get-token.ts       credentials -> token helper