blackboard-upc 1.0.0 → 1.0.2

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+    "mcpServers": {
+      "blackboard": {
+        "command": "npx",
+        "args": ["blackboard-upc", "mcp"]
+      }
+    }
+  }

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `blackboard-upc` will be documented here.
 
 ---
 
+## [1.0.1] — 2026-03-30
+
+### Added
+- `courses members <courseId>` — lista compañeros e instructor de un curso (con `--role` y `--json`)
+
+### Improved
+- `courses list` — usa `expand=course` en una sola llamada en vez de 1+N (antes: 1 llamada por curso)
+- `assignments list` — usa bulk grades (`/gradebook/users/{id}`) en paralelo con columns, eliminando N llamadas individuales
+- `courses members` — usa `expand=user` para traer nombres en una sola llamada
+
+---
+
 ## [1.0.0] — 2026-03-30
 
 ### Added
@@ -53,7 +65,7 @@ All notable changes to `blackboard-upc` will be documented here.
 
 ## Roadmap
 
-- [ ] `npx` install sin clonar repo (publicación en npm)
+- [x] `npx` install sin clonar repo (publicación en npm)
 - [ ] Refresh automático de sesión antes de expirar
 - [ ] Notificaciones de entregas próximas (`assignments due`)
 - [ ] Descarga de videos de grabaciones de clase

package/README.md

@@ -21,7 +21,7 @@ npm install -g blackboard-upc
 blackboard login
 
 # Opción 3 — clonar el repo
-git clone https://github.com/aleoroni/blackboard-cli
+git clone https://github.com/alejooroncoy/blackboard-cli
 cd blackboard-cli
 npm install
 npx playwright install chromium
@@ -40,13 +40,15 @@ blackboard login
 
 Se abre una ventana del navegador con el login de Microsoft UPC. Inicia sesión con tu cuenta `u20XXXXXXX@upc.edu.pe` (incluye MFA si lo tienes). La ventana se cierra sola y la sesión queda guardada 8 horas.
 
+> **Importante:** durante el login, Microsoft mostrará el mensaje **"Stay signed in?"** con un checkbox **"Don't show this again"**. Activa ese checkbox y haz clic en **Yes** — esto le indica a Microsoft que mantenga la sesión activa y es necesario para que el CLI pueda guardar las cookies correctamente.
+
 ```
   ██████  ██       █████   ██████ ██   ██ ██████   ██████   █████  ██████  ██████
   ...
   CLI no oficial para UPC Aula Virtual · Blackboard Learn
 
   ✓ Sesión guardada — expira en 8 horas
-    Usuario: Alejandro Daniel Oroncoy Almeyda
+    Usuario: Juan Pérez García
 
   ¿Qué puedo hacer ahora?
 
@@ -61,15 +63,15 @@ Se abre una ventana del navegador con el login de Microsoft UPC. Inicia sesión
 ```bash
 blackboard courses list
 
-  _529630_1  Fundamentos de Arquitectura de Software [Ultra]
-  _529580_1  Finanzas e Ingeniería Económica [Ultra]
-  _529533_1  Desarrollo de Soluciones IOT [Ultra]
-  _529760_1  Diseño de Experimentos de Ingeniería de Software [Ultra]
+  _100001_1  Cálculo Diferencial e Integral [Ultra]
+  _100002_1  Programación Orientada a Objetos [Ultra]
+  _100003_1  Bases de Datos [Ultra]
+  _100004_1  Algoritmos y Estructuras de Datos [Ultra]
 
-blackboard assignments list _529760_1
+blackboard assignments list _100004_1
 
-  _13890556_1  Tarea 1  [manual]
-    Nota: sin entregar · Máx: 3 pts · Entrega: 05/03/2026 (vencida hace 23d)
+  _200001_1  Tarea 1  [manual]
+    Nota: sin entregar · Máx: 5 pts · Entrega: 15/04/2026 (vence en 17d)
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blackboard-upc",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "CLI no oficial para UPC Aula Virtual (Blackboard Learn) — acceso desde la terminal y MCP para Claude",
   "main": "run.js",
   "bin": {

package/src/api/courses.ts

@@ -14,20 +14,9 @@ export async function getMyCourses(
   const params: Record<string, any> = { limit: opts.limit ?? 50 };
   if (opts.offset) params.offset = opts.offset;
 
+  params.expand = 'course';
   const r = await client.get(`/learn/api/public/v1/users/${userId}/courses`, { params });
-  const memberships: UserCourse[] = r.data.results;
-
-  // Resolve course names in parallel
-  const courseDetails = await Promise.allSettled(
-    memberships.map((m) => getCourse(client, m.courseId))
-  );
-
-  const results = memberships.map((m, i) => ({
-    ...m,
-    course: courseDetails[i].status === 'fulfilled' ? courseDetails[i].value : undefined,
-  }));
-
-  return { results, paging: r.data.paging };
+  return { results: r.data.results, paging: r.data.paging };
 }
 
 export async function getCourse(client: AxiosInstance, courseId: string): Promise<Course> {

package/src/commands/assignments.ts

@@ -61,7 +61,16 @@ export function assignmentsCommand(program: Command) {
         let userId = session.userId;
         if (!userId) { const me = await getMe(client); userId = me.id; }
 
-        const columns = await listAssignments(client, courseId);
+        const [columns, gradesRes] = await Promise.all([
+          listAssignments(client, courseId),
+          client
+            .get(`/learn/api/public/v1/courses/${courseId}/gradebook/users/${userId}`, {
+              params: { limit: 200 },
+            })
+            .then((r) => r.data.results as any[])
+            .catch(() => [] as any[]),
+        ]);
+
         spinner.succeed(`${columns.length} assignments found`);
 
         if (opts.json) { console.log(JSON.stringify(columns, null, 2)); return; }
@@ -71,19 +80,11 @@ export function assignmentsCommand(program: Command) {
           return;
         }
 
-        // Fetch my grade for each assignment in parallel
-        const gradeResults = await Promise.allSettled(
-          columns.map((c) =>
-            client
-              .get(`/learn/api/public/v1/courses/${courseId}/gradebook/users/${userId}/columns/${c.id}`)
-              .then((r) => r.data)
-              .catch(() => null)
-          )
-        );
+        const gradeMap = new Map(gradesRes.map((g: any) => [g.columnId, g]));
 
         console.log('');
-        columns.forEach((col, i) => {
-          const grade = gradeResults[i].status === 'fulfilled' ? gradeResults[i].value : null;
+        columns.forEach((col) => {
+          const grade = gradeMap.get(col.id) ?? null;
           const possible = col.score?.possible ?? '?';
           const due = col.grading?.due;
           const attemptsAllowed = col.grading?.attemptsAllowed === 0

package/src/commands/courses.ts

@@ -231,6 +231,63 @@ export function coursesCommand(program: Command) {
       }
     });
 
+  // Members
+  courses
+    .command('members <courseId>')
+    .description('List students and instructors in a course')
+    .option('--json', 'Output raw JSON')
+    .option('--role <role>', 'Filter by role: Student, Instructor')
+    .action(async (courseId, opts) => {
+      const session = requireSession();
+      const client = createClient(session);
+      const spinner = ora({ text: 'Fetching course members...', stream: process.stderr }).start();
+
+      try {
+        const res = await client.get(
+          `/learn/api/public/v1/courses/${courseId}/users?expand=user&limit=200`
+        );
+        let members: any[] = res.data.results ?? [];
+
+        if (opts.role) {
+          const roleFilter = opts.role.toLowerCase();
+          members = members.filter((m: any) => m.courseRoleId?.toLowerCase() === roleFilter);
+        }
+
+        spinner.succeed(`${members.length} members`);
+
+        if (opts.json) {
+          console.log(JSON.stringify({ results: members }, null, 2));
+          return;
+        }
+
+        const students = members.filter((m: any) => m.courseRoleId === 'Student');
+        const instructors = members.filter((m: any) => m.courseRoleId !== 'Student');
+
+        console.log('');
+        if (instructors.length > 0) {
+          console.log(chalk.bold('  Instructores'));
+          for (const m of instructors) {
+            const name = m.user ? `${m.user.name.given} ${m.user.name.family}` : m.userId;
+            console.log(`  ${chalk.yellow(name)}`);
+          }
+          console.log('');
+        }
+
+        if (students.length > 0) {
+          console.log(chalk.bold(`  Estudiantes (${students.length})`));
+          students.forEach((m: any, i: number) => {
+            const name = m.user ? `${m.user.name.given} ${m.user.name.family}` : m.userId;
+            const num = chalk.gray(`${String(i + 1).padStart(2, ' ')}.`);
+            console.log(`  ${num} ${name}`);
+          });
+        }
+        console.log('');
+      } catch (err: any) {
+        spinner.fail(err.message);
+        process.exit(1);
+      }
+    });
+
   // Grades
   courses
     .command('grades <courseId>')

package/src/mcp/server.ts

@@ -143,37 +143,116 @@ export async function startMcpServer() {
   // ── download_attachment ─────────────────────────────────────────────────────
   server.tool(
     'download_attachment',
-    'Download a file from a course content item. Returns base64-encoded content.',
+    'Download a file from a course content item. attachmentId can be a Blackboard attachment ID (for x-bb-file) or a full bbcswebdav URL (for x-bb-document embedded files). Returns base64-encoded content.',
     {
       courseId: z.string().describe('Blackboard course ID'),
       contentId: z.string().describe('Content item ID'),
-      attachmentId: z.string().describe('Attachment ID from list_attachments'),
+      attachmentId: z.string().describe('Attachment ID from list_attachments, or a full bbcswebdav URL for embedded files'),
     },
     async ({ courseId, contentId, attachmentId }) => {
       const { client } = getClient();
-      const r = await client.get(
-        `/learn/api/public/v1/courses/${courseId}/contents/${contentId}/attachments/${attachmentId}/download`,
-        { responseType: 'arraybuffer' }
-      );
+
+      // If attachmentId is a full URL (embedded file), download directly
+      const url = attachmentId.startsWith('http')
+        ? attachmentId
+        : `/learn/api/public/v1/courses/${courseId}/contents/${contentId}/attachments/${attachmentId}/download`;
+
+      const r = await client.get(url, { responseType: 'arraybuffer', headers: { Accept: '*/*' } });
       const b64 = Buffer.from(r.data).toString('base64');
-      return { content: [{ type: 'text', text: b64 }] };
+      const contentDisposition = r.headers['content-disposition'] as string | undefined;
+      const filename = contentDisposition
+        ? (contentDisposition.match(/filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/))?.[1]?.replace(/['"]/g, '').trim()
+        : undefined;
+      const mimeType = (r.headers['content-type'] as string | undefined) ?? 'application/octet-stream';
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ filename: filename ?? 'file', mimeType, size: r.data.byteLength, base64: b64 }, null, 2),
+        }],
+      };
     }
   );
 
   // ── list_attachments ────────────────────────────────────────────────────────
   server.tool(
     'list_attachments',
-    'List file attachments for a course content item',
+    'List file attachments for a course content item. Works for x-bb-file (REST API) and x-bb-document (embedded files in body HTML).',
     {
       courseId: z.string().describe('Blackboard course ID'),
       contentId: z.string().describe('Content item ID'),
     },
     async ({ courseId, contentId }) => {
       const { client } = getClient();
+
+      // Try standard REST attachments endpoint first (works for x-bb-file)
+      try {
+        const r = await client.get(
+          `/learn/api/public/v1/courses/${courseId}/contents/${contentId}/attachments`
+        );
+        return { content: [{ type: 'text', text: JSON.stringify(r.data, null, 2) }] };
+      } catch (err: any) {
+        if (err.response?.status !== 400 && err.response?.status !== 404) throw err;
+      }
+
+      // Fallback: fetch content and parse embedded files from body HTML (x-bb-document, x-bb-lesson)
       const r = await client.get(
-        `/learn/api/public/v1/courses/${courseId}/contents/${contentId}/attachments`
+        `/learn/api/public/v1/courses/${courseId}/contents/${contentId}`
       );
-      return { content: [{ type: 'text', text: JSON.stringify(r.data, null, 2) }] };
+      const body: string = r.data?.body ?? '';
+      const matches = [...body.matchAll(/data-bbfile="([^"]+)"/g)];
+      const files = matches.map((m) => {
+        try {
+          const meta = JSON.parse(m[1].replace(/"/g, '"'));
+          return {
+            type: 'embedded',
+            displayName: meta.displayName ?? meta.linkName ?? 'unknown',
+            mimeType: meta.mimeType ?? 'application/octet-stream',
+            resourceUrl: meta.resourceUrl ?? null,
+          };
+        } catch {
+          return null;
+        }
+      }).filter(Boolean);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(
+            { type: 'embedded_files', note: 'Use download_file_url with resourceUrl to download', results: files },
+            null, 2
+          ),
+        }],
+      };
+    }
+  );
+
+  // ── download_file_url ───────────────────────────────────────────────────────
+  server.tool(
+    'download_file_url',
+    'Download a file directly from a Blackboard bbcswebdav URL (for x-bb-document embedded files). Returns base64-encoded content and filename.',
+    {
+      url: z.string().describe('Direct file URL from bbcswebdav (resourceUrl from content body)'),
+      filename: z.string().optional().describe('Desired filename for saving the file'),
+    },
+    async ({ url, filename }) => {
+      const { client } = getClient();
+      const r = await client.get(url, {
+        responseType: 'arraybuffer',
+        headers: { Accept: '*/*' },
+      });
+      const b64 = Buffer.from(r.data).toString('base64');
+      const contentDisposition = r.headers['content-disposition'] as string | undefined;
+      const detectedName = contentDisposition
+        ? (contentDisposition.match(/filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/))?.[1]?.replace(/['"]/g, '').trim()
+        : undefined;
+      const finalName = filename ?? detectedName ?? 'file';
+      const mimeType = (r.headers['content-type'] as string | undefined) ?? 'application/octet-stream';
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ filename: finalName, mimeType, size: r.data.byteLength, base64: b64 }, null, 2),
+        }],
+      };
     }
   );