blackboard-upc 1.0.1 → 1.0.3

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.2] — 2026-03-30
+
+### Fixed
+- `list_attachments` — fallback automático a parseo del HTML del `body` para contenido tipo `x-bb-document` y `x-bb-lesson` (antes retornaba 400 en estos casos)
+- `download_attachment` — ahora acepta URLs directas de `bbcswebdav` además de IDs estándar de Blackboard
+
+### Added
+- `download_file_url` (MCP) — nueva herramienta para descargar archivos embebidos directamente desde URLs de `bbcswebdav` con las cookies de sesión autenticadas
+- Todos los tools de descarga ahora retornan `filename`, `mimeType` y `size` junto al contenido `base64`
+
+---
+
 ## [1.0.1] — 2026-03-30
 
 ### Added

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.1",
+  "version": "1.0.3",
   "description": "CLI no oficial para UPC Aula Virtual (Blackboard Learn) — acceso desde la terminal y MCP para Claude",
   "main": "run.js",
   "bin": {

package/src/mcp/server.ts

@@ -30,21 +30,21 @@ export async function startMcpServer() {
   });
 
   // ── whoami ─────────────────────────────────────────────────────────────────
-  server.tool('whoami', 'Get the currently authenticated UPC student info', {}, async () => {
+  server.registerTool('whoami', { description: 'Get the currently authenticated UPC student info' }, async () => {
     const { client } = getClient();
     const me = await getMe(client);
     return { content: [{ type: 'text', text: JSON.stringify(me, null, 2) }] };
   });
 
   // ── system_version ─────────────────────────────────────────────────────────
-  server.tool('system_version', 'Get Blackboard Learn server version', {}, async () => {
+  server.registerTool('system_version', { description: 'Get Blackboard Learn server version' }, async () => {
     const { client } = getClient();
     const v = await getSystemVersion(client);
     return { content: [{ type: 'text', text: JSON.stringify(v, null, 2) }] };
   });
 
   // ── list_courses ────────────────────────────────────────────────────────────
-  server.tool('list_courses', 'List all enrolled courses for the current student', {}, async () => {
+  server.registerTool('list_courses', { description: 'List all enrolled courses for the current student' }, async () => {
     const { client, session } = getClient();
     let userId = session.userId;
     if (!userId) { const me = await getMe(client); userId = me.id; }
@@ -53,10 +53,12 @@ export async function startMcpServer() {
   });
 
   // ── get_course ──────────────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'get_course',
-    'Get details of a specific course by its Blackboard ID (e.g. _529580_1)',
-    { courseId: z.string().describe('Blackboard course ID like _529580_1') },
+    {
+      description: 'Get details of a specific course by its Blackboard ID (e.g. _529580_1)',
+      inputSchema: { courseId: z.string().describe('Blackboard course ID like _529580_1') },
+    },
     async ({ courseId }) => {
       const { client } = getClient();
       const data = await getCourse(client, courseId);
@@ -65,12 +67,14 @@ export async function startMcpServer() {
   );
 
   // ── list_contents ───────────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'list_contents',
-    'List content items inside a course or folder. Use parentId to navigate into subfolders.',
     {
-      courseId: z.string().describe('Blackboard course ID'),
-      parentId: z.string().optional().describe('Parent folder content ID (omit for root level)'),
+      description: 'List content items inside a course or folder. Use parentId to navigate into subfolders.',
+      inputSchema: {
+        courseId: z.string().describe('Blackboard course ID'),
+        parentId: z.string().optional().describe('Parent folder content ID (omit for root level)'),
+      },
     },
     async ({ courseId, parentId }) => {
       const { client } = getClient();
@@ -80,10 +84,12 @@ export async function startMcpServer() {
   );
 
   // ── list_announcements ──────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'list_announcements',
-    'List recent announcements for a course',
-    { courseId: z.string().describe('Blackboard course ID') },
+    {
+      description: 'List recent announcements for a course',
+      inputSchema: { courseId: z.string().describe('Blackboard course ID') },
+    },
     async ({ courseId }) => {
       const { client } = getClient();
       const data = await getCourseAnnouncements(client, courseId);
@@ -92,10 +98,12 @@ export async function startMcpServer() {
   );
 
   // ── list_assignments ────────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'list_assignments',
-    'List assignments and tasks in a course with due dates, scores and submission status',
-    { courseId: z.string().describe('Blackboard course ID') },
+    {
+      description: 'List assignments and tasks in a course with due dates, scores and submission status',
+      inputSchema: { courseId: z.string().describe('Blackboard course ID') },
+    },
     async ({ courseId }) => {
       const { client } = getClient();
       const data = await listAssignments(client, courseId);
@@ -104,12 +112,14 @@ export async function startMcpServer() {
   );
 
   // ── list_attempts ───────────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'list_attempts',
-    'List submission attempts for a specific assignment (gradebook column)',
     {
-      courseId: z.string().describe('Blackboard course ID'),
-      columnId: z.string().describe('Gradebook column ID (assignment ID)'),
+      description: 'List submission attempts for a specific assignment (gradebook column)',
+      inputSchema: {
+        courseId: z.string().describe('Blackboard course ID'),
+        columnId: z.string().describe('Gradebook column ID (assignment ID)'),
+      },
     },
     async ({ courseId, columnId }) => {
       const { client } = getClient();
@@ -119,10 +129,12 @@ export async function startMcpServer() {
   );
 
   // ── get_grades ──────────────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'get_grades',
-    'Get all grades for the current student in a course',
-    { courseId: z.string().describe('Blackboard course ID') },
+    {
+      description: 'Get all grades for the current student in a course',
+      inputSchema: { courseId: z.string().describe('Blackboard course ID') },
+    },
     async ({ courseId }) => {
       const { client, session } = getClient();
       let userId = session.userId;
@@ -141,51 +153,145 @@ export async function startMcpServer() {
   );
 
   // ── download_attachment ─────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'download_attachment',
-    'Download a file from a course content item. 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'),
+      description: '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.',
+      inputSchema: {
+        courseId: z.string().describe('Blackboard course ID'),
+        contentId: z.string().describe('Content item ID'),
+        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(
+  server.registerTool(
     'list_attachments',
-    'List file attachments for a course content item',
     {
-      courseId: z.string().describe('Blackboard course ID'),
-      contentId: z.string().describe('Content item ID'),
+      description: 'List file attachments for a course content item. Works for x-bb-file (REST API) and x-bb-document (embedded files in body HTML).',
+      inputSchema: {
+        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 ?? '';
+
+      // Extract <a> tags with data-bbfile — capture both the JSON metadata and the href (signed download URL)
+      // Handle both attribute orderings: data-bbfile...href and href...data-bbfile
+      const filePattern = /data-bbfile="([^"]+)"[^<]*?href="([^"]+)"|href="([^"]+)"[^<]*?data-bbfile="([^"]+)"/g;
+      const anchorMatches = [...body.matchAll(filePattern)];
+      const files = anchorMatches.map((m) => {
+        const bbfileRaw = m[1] ?? m[4];
+        const hrefRaw   = m[2] ?? m[3];
+        try {
+          const meta = JSON.parse(bbfileRaw.replace(/&quot;/g, '"'));
+          const downloadUrl = hrefRaw ? hrefRaw.replace(/&amp;/g, '&') : (meta.resourceUrl ?? null);
+          return {
+            type: 'embedded',
+            displayName: meta.displayName ?? meta.linkName ?? 'unknown',
+            mimeType: meta.mimeType ?? 'application/octet-stream',
+            downloadUrl,
+          };
+        } catch {
+          return null;
+        }
+      }).filter(Boolean);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(
+            { type: 'embedded_files', note: 'Pass downloadUrl as attachmentId to download_attachment', results: files },
+            null, 2
+          ),
+        }],
+      };
+    }
+  );
+
+  // ── download_file_url ───────────────────────────────────────────────────────
+  server.registerTool(
+    'download_file_url',
+    {
+      description: 'Download a file directly from a Blackboard bbcswebdav URL (for x-bb-document embedded files). Returns base64-encoded content and filename.',
+      inputSchema: {
+        url: z.string().describe('Direct file URL from bbcswebdav (downloadUrl from list_attachments)'),
+        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),
+        }],
+      };
     }
   );
 
   // ── submit_attempt ──────────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'submit_attempt',
-    'Submit an assignment attempt. ALWAYS confirm with the user before submitting.',
     {
-      courseId: z.string().describe('Blackboard course ID'),
-      columnId: z.string().describe('Assignment (gradebook column) ID'),
-      studentComments: z.string().optional().describe('Comment to the instructor'),
-      studentSubmission: z.string().optional().describe('Text body of the submission'),
+      description: 'Submit an assignment attempt. ALWAYS confirm with the user before submitting.',
+      inputSchema: {
+        courseId: z.string().describe('Blackboard course ID'),
+        columnId: z.string().describe('Assignment (gradebook column) ID'),
+        studentComments: z.string().optional().describe('Comment to the instructor'),
+        studentSubmission: z.string().optional().describe('Text body of the submission'),
+      },
     },
     async ({ courseId, columnId, studentComments, studentSubmission }) => {
       const { client } = getClient();
@@ -199,14 +305,16 @@ export async function startMcpServer() {
   );
 
   // ── raw_api ─────────────────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'raw_api',
-    'Make a raw REST API call to Blackboard Learn. Use for any endpoint not covered by other tools.',
     {
-      method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
-      path: z.string().describe('API path, e.g. /learn/api/public/v1/users/me'),
-      query: z.string().optional().describe('Query string, e.g. limit=10&offset=0'),
-      body: z.string().optional().describe('JSON body string for POST/PUT/PATCH'),
+      description: 'Make a raw REST API call to Blackboard Learn. Use for any endpoint not covered by other tools.',
+      inputSchema: {
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
+        path: z.string().describe('API path, e.g. /learn/api/public/v1/users/me'),
+        query: z.string().optional().describe('Query string, e.g. limit=10&offset=0'),
+        body: z.string().optional().describe('JSON body string for POST/PUT/PATCH'),
+      },
     },
     async ({ method, path, query, body }) => {
       const { client } = getClient();