blackboard-upc 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `blackboard-upc` will be documented here.
 
 ---
 
+## [1.0.3] — 2026-03-30
+
+### Changed
+- Todos los tools MCP migrados de `server.tool()` a `server.registerTool()` (API nueva del SDK v1.28+)
+- Elimina todos los warnings de TypeScript por uso de API deprecada
+
+---
+
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blackboard-upc",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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

@@ -1,6 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import fs from 'fs';
+import path from 'path';
 import { loadSession, isSessionValid } from '../auth/session.js';
 import { createClient } from '../api/client.js';
 import {
@@ -30,21 +32,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 +55,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 +69,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 +86,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 +100,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 +114,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 +131,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,45 +155,57 @@ export async function startMcpServer() {
   );
 
   // ── download_attachment ─────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'download_attachment',
-    '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, or a full bbcswebdav URL for embedded files'),
+      description: 'Download a file from a course content item and save it to disk. attachmentId can be a Blackboard attachment ID (for x-bb-file) or a full bbcswebdav URL (for x-bb-document embedded files). Saves to outputDir (default: current working directory).',
+      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'),
+        filename: z.string().optional().describe('Filename to save as (e.g. displayName from list_attachments). Falls back to Content-Disposition header.'),
+        outputDir: z.string().optional().describe('Directory to save the file (default: current working directory)'),
+      },
     },
-    async ({ courseId, contentId, attachmentId }) => {
+    async ({ courseId, contentId, attachmentId, filename, outputDir }) => {
       const { client } = getClient();
 
-      // 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');
+
       const contentDisposition = r.headers['content-disposition'] as string | undefined;
-      const filename = contentDisposition
+      const detectedName = contentDisposition
         ? (contentDisposition.match(/filename[^;=\n]*=((['"]).*?\2|[^;\n]*)/))?.[1]?.replace(/['"]/g, '').trim()
         : undefined;
+      const finalName = filename ?? detectedName ?? 'download';
+
+      const dir = path.resolve(outputDir ?? process.cwd());
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      const dest = path.join(dir, finalName);
+      fs.writeFileSync(dest, Buffer.from(r.data));
+
       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),
+          text: JSON.stringify({ saved: dest, size: r.data.byteLength, mimeType }, null, 2),
         }],
       };
     }
   );
 
   // ── list_attachments ────────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     'list_attachments',
-    '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'),
+      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();
@@ -199,15 +225,22 @@ export async function startMcpServer() {
         `/learn/api/public/v1/courses/${courseId}/contents/${contentId}`
       );
       const body: string = r.data?.body ?? '';
-      const matches = [...body.matchAll(/data-bbfile="([^"]+)"/g)];
-      const files = matches.map((m) => {
+
+      // 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(m[1].replace(/&quot;/g, '"'));
+          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',
-            resourceUrl: meta.resourceUrl ?? null,
+            downloadUrl,
           };
         } catch {
           return null;
@@ -218,7 +251,7 @@ export async function startMcpServer() {
         content: [{
           type: 'text',
           text: JSON.stringify(
-            { type: 'embedded_files', note: 'Use download_file_url with resourceUrl to download', results: files },
+            { type: 'embedded_files', note: 'Pass downloadUrl as attachmentId to download_attachment', results: files },
             null, 2
           ),
         }],
@@ -227,44 +260,52 @@ export async function startMcpServer() {
   );
 
   // ── download_file_url ───────────────────────────────────────────────────────
-  server.tool(
+  server.registerTool(
     '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'),
+      description: 'Download a file directly from a Blackboard bbcswebdav URL and save it to disk. Saves to outputDir (default: current working directory).',
+      inputSchema: {
+        url: z.string().describe('Direct file URL from bbcswebdav (downloadUrl from list_attachments)'),
+        filename: z.string().optional().describe('Filename to save as (e.g. displayName from list_attachments)'),
+        outputDir: z.string().optional().describe('Directory to save the file (default: current working directory)'),
+      },
     },
-    async ({ url, filename }) => {
+    async ({ url, filename, outputDir }) => {
       const { client } = getClient();
-      const r = await client.get(url, {
-        responseType: 'arraybuffer',
-        headers: { Accept: '*/*' },
-      });
-      const b64 = Buffer.from(r.data).toString('base64');
+      const r = await client.get(url, { responseType: 'arraybuffer', headers: { Accept: '*/*' } });
+
       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 finalName = filename ?? detectedName ?? 'download';
+
+      const dir = path.resolve(outputDir ?? process.cwd());
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      const dest = path.join(dir, finalName);
+      fs.writeFileSync(dest, Buffer.from(r.data));
+
       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),
+          text: JSON.stringify({ saved: dest, size: r.data.byteLength, mimeType }, 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();
@@ -278,14 +319,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();