sad-mcp 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,2 @@
+import { type Auth } from "googleapis";
+export declare function getAuthenticatedClient(): Promise<Auth.OAuth2Client>;

package/dist/auth.js

@@ -0,0 +1,105 @@
+import { google } from "googleapis";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { createServer } from "http";
+import open from "open";
+// OAuth credentials — embedded for desktop app (not secret per Google docs)
+// TODO: Replace with actual credentials from Google Cloud Console
+const CLIENT_ID = "721600472437-vaqegrbgqr2dta3fbmc55heqju7f6hl5.apps.googleusercontent.com";
+const CLIENT_SECRET = "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";
+const REDIRECT_URI = "http://localhost:3456/oauth2callback";
+const SCOPES = ["https://www.googleapis.com/auth/drive.readonly"];
+const CONFIG_DIR = join(homedir(), ".sad-mcp");
+const TOKEN_PATH = join(CONFIG_DIR, "tokens.json");
+function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+function loadStoredToken() {
+    try {
+        const data = readFileSync(TOKEN_PATH, "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+function saveToken(token) {
+    ensureConfigDir();
+    writeFileSync(TOKEN_PATH, JSON.stringify(token, null, 2));
+}
+async function getAuthCodeFromBrowser(authUrl) {
+    return new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url, `http://localhost:3456`);
+            const code = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            if (error) {
+                res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(`<h1>Authentication failed</h1><p>${error}</p>`);
+                server.close();
+                reject(new Error(`OAuth error: ${error}`));
+                return;
+            }
+            if (code) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end("<h1>Authentication successful!</h1><p>You can close this window and return to Claude Desktop.</p>");
+                server.close();
+                resolve(code);
+            }
+        });
+        server.listen(3456, () => {
+            open(authUrl).catch(() => {
+                // If open fails, user will need to manually open the URL
+                console.error(`Please open this URL in your browser:\n${authUrl}`);
+            });
+        });
+        // Timeout after 2 minutes
+        setTimeout(() => {
+            server.close();
+            reject(new Error("OAuth timeout — no response within 2 minutes"));
+        }, 120_000);
+    });
+}
+export async function getAuthenticatedClient() {
+    ensureConfigDir();
+    const oauth2Client = new google.auth.OAuth2(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI);
+    // Try loading stored token
+    const storedToken = loadStoredToken();
+    if (storedToken) {
+        oauth2Client.setCredentials(storedToken);
+        // Check if token needs refresh
+        if (storedToken.expiry_date &&
+            storedToken.expiry_date < Date.now()) {
+            try {
+                const { credentials } = await oauth2Client.refreshAccessToken();
+                saveToken(credentials);
+                oauth2Client.setCredentials(credentials);
+            }
+            catch {
+                // Refresh failed — need to re-authenticate
+                return await performOAuthFlow(oauth2Client);
+            }
+        }
+        return oauth2Client;
+    }
+    // No stored token — perform OAuth flow
+    return await performOAuthFlow(oauth2Client);
+}
+async function performOAuthFlow(oauth2Client) {
+    const authUrl = oauth2Client.generateAuthUrl({
+        access_type: "offline",
+        scope: SCOPES,
+        prompt: "consent",
+    });
+    console.error("SAD MCP: Opening browser for Google authentication...");
+    console.error("Sign in with your BGU account (@post.bgu.ac.il) to access course materials.");
+    const code = await getAuthCodeFromBrowser(authUrl);
+    const { tokens } = await oauth2Client.getToken(code);
+    saveToken(tokens);
+    oauth2Client.setCredentials(tokens);
+    console.error("SAD MCP: Authentication successful!");
+    return oauth2Client;
+}

package/dist/drive.d.ts

@@ -0,0 +1,11 @@
+export interface DriveFile {
+    id: string;
+    name: string;
+    mimeType: string;
+    path: string;
+    size?: number;
+    modifiedTime?: string;
+}
+export declare function listAllFiles(): Promise<DriveFile[]>;
+export declare function downloadFile(file: DriveFile): Promise<Buffer>;
+export declare function categorizeFile(file: DriveFile): string;

package/dist/drive.js

@@ -0,0 +1,123 @@
+import { google } from "googleapis";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { getAuthenticatedClient } from "./auth.js";
+const FOLDER_ID = "1PnjBoLOFPf70QbpZQGbH_EgbOKc_DyZ-";
+const CACHE_DIR = join(homedir(), ".sad-mcp", "cache");
+const CACHE_INDEX_PATH = join(homedir(), ".sad-mcp", "cache-index.json");
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+function loadCacheIndex() {
+    try {
+        return JSON.parse(readFileSync(CACHE_INDEX_PATH, "utf-8"));
+    }
+    catch {
+        return { files: {} };
+    }
+}
+function saveCacheIndex(index) {
+    mkdirSync(CACHE_DIR, { recursive: true });
+    writeFileSync(CACHE_INDEX_PATH, JSON.stringify(index, null, 2));
+}
+function isCacheValid(entry) {
+    if (!existsSync(entry.localPath))
+        return false;
+    return Date.now() - entry.cachedAt < CACHE_TTL_MS;
+}
+let driveClient = null;
+async function getDrive() {
+    if (driveClient)
+        return driveClient;
+    const auth = await getAuthenticatedClient();
+    driveClient = google.drive({ version: "v3", auth });
+    return driveClient;
+}
+async function listFolderRecursive(drive, folderId, pathPrefix = "") {
+    const files = [];
+    let pageToken;
+    do {
+        const res = await drive.files.list({
+            q: `'${folderId}' in parents and trashed = false`,
+            fields: "nextPageToken, files(id, name, mimeType, size, modifiedTime)",
+            pageSize: 100,
+            pageToken,
+        });
+        for (const file of res.data.files || []) {
+            const filePath = pathPrefix ? `${pathPrefix}/${file.name}` : file.name;
+            if (file.mimeType === "application/vnd.google-apps.folder") {
+                // Recurse into subfolders
+                const subFiles = await listFolderRecursive(drive, file.id, filePath);
+                files.push(...subFiles);
+            }
+            else {
+                files.push({
+                    id: file.id,
+                    name: file.name,
+                    mimeType: file.mimeType,
+                    path: filePath,
+                    size: file.size ? parseInt(file.size) : undefined,
+                    modifiedTime: file.modifiedTime || undefined,
+                });
+            }
+        }
+        pageToken = res.data.nextPageToken || undefined;
+    } while (pageToken);
+    return files;
+}
+export async function listAllFiles() {
+    const index = loadCacheIndex();
+    // Return cached listing if still valid
+    if (index.folderListedAt &&
+        Date.now() - index.folderListedAt < CACHE_TTL_MS &&
+        index.folderListing) {
+        return index.folderListing;
+    }
+    const drive = await getDrive();
+    const files = await listFolderRecursive(drive, FOLDER_ID);
+    // Cache the listing
+    index.folderListedAt = Date.now();
+    index.folderListing = files;
+    saveCacheIndex(index);
+    return files;
+}
+export async function downloadFile(file) {
+    const index = loadCacheIndex();
+    const cached = index.files[file.id];
+    // Return from cache if valid
+    if (cached && isCacheValid(cached)) {
+        return readFileSync(cached.localPath);
+    }
+    const drive = await getDrive();
+    // Download the file
+    const res = await drive.files.get({ fileId: file.id, alt: "media" }, { responseType: "arraybuffer" });
+    const buffer = Buffer.from(res.data);
+    // Cache locally
+    mkdirSync(CACHE_DIR, { recursive: true });
+    const sanitizedName = file.path.replace(/[/\\:*?"<>|]/g, "_");
+    const localPath = join(CACHE_DIR, sanitizedName);
+    writeFileSync(localPath, buffer);
+    index.files[file.id] = {
+        fileId: file.id,
+        cachedAt: Date.now(),
+        localPath,
+        modifiedTime: file.modifiedTime,
+    };
+    saveCacheIndex(index);
+    return buffer;
+}
+export function categorizeFile(file) {
+    const pathLower = file.path.toLowerCase();
+    if (pathLower.includes("תמלולים") || pathLower.endsWith(".txt") || pathLower.endsWith(".vtt")) {
+        return "transcripts";
+    }
+    if (pathLower.includes("מבחנ") || pathLower.includes("exam")) {
+        return "exams";
+    }
+    if (pathLower.endsWith(".pptx") ||
+        pathLower.endsWith(".pdf") ||
+        pathLower.includes("שיעור") ||
+        pathLower.includes("הרצאה")) {
+        return "lectures";
+    }
+    return "other";
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerResourceHandlers } from "./resources.js";
+import { registerToolHandlers } from "./tools.js";
+import { trackServerStart } from "./tracking.js";
+const server = new Server({ name: "sad-mcp", version: "0.1.0" }, {
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+// Register all handlers
+registerResourceHandlers(server);
+registerToolHandlers(server);
+// Track server startup
+trackServerStart();
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("SAD MCP server started. Course materials available from Google Drive.");
+}
+main().catch((err) => {
+    console.error("SAD MCP failed to start:", err);
+    process.exit(1);
+});

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function registerResourceHandlers(server: Server): void;

package/dist/resources.js

@@ -0,0 +1,50 @@
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { listAllFiles, downloadFile, categorizeFile } from "./drive.js";
+import { extractText, isExtractable } from "./text-extract.js";
+import { trackResourceRead } from "./tracking.js";
+function fileToUri(file) {
+    const category = categorizeFile(file);
+    const encodedName = encodeURIComponent(file.name);
+    return `sad://${category}/${encodedName}`;
+}
+function mimeForExtraction(file) {
+    // All resources are served as extracted text
+    return "text/plain";
+}
+export function registerResourceHandlers(server) {
+    // List all available resources
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        const files = await listAllFiles();
+        const extractableFiles = files.filter(isExtractable);
+        return {
+            resources: extractableFiles.map((file) => ({
+                uri: fileToUri(file),
+                name: file.name,
+                description: `[${categorizeFile(file)}] ${file.path}`,
+                mimeType: mimeForExtraction(file),
+            })),
+        };
+    });
+    // Read a specific resource
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        const files = await listAllFiles();
+        // Find the file matching this URI
+        const file = files.find((f) => fileToUri(f) === uri);
+        if (!file) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        trackResourceRead(uri);
+        const buffer = await downloadFile(file);
+        const text = await extractText(file, buffer);
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: "text/plain",
+                    text,
+                },
+            ],
+        };
+    });
+}

package/dist/text-extract.d.ts

@@ -0,0 +1,3 @@
+import type { DriveFile } from "./drive.js";
+export declare function extractText(file: DriveFile, buffer: Buffer): Promise<string>;
+export declare function isExtractable(file: DriveFile): boolean;

package/dist/text-extract.js

@@ -0,0 +1,67 @@
+import officeparser from "officeparser";
+import pdf from "pdf-parse";
+export async function extractText(file, buffer) {
+    const mimeType = file.mimeType;
+    const name = file.name.toLowerCase();
+    // Plain text files — return as-is
+    if (mimeType === "text/plain" ||
+        name.endsWith(".txt") ||
+        name.endsWith(".vtt") ||
+        name.endsWith(".md")) {
+        return buffer.toString("utf-8");
+    }
+    // PDF files
+    if (mimeType === "application/pdf" || name.endsWith(".pdf")) {
+        try {
+            const data = await pdf(buffer);
+            return data.text;
+        }
+        catch (err) {
+            return `[Error extracting PDF text: ${err instanceof Error ? err.message : String(err)}]`;
+        }
+    }
+    // PPTX files
+    if (mimeType === "application/vnd.openxmlformats-officedocument.presentationml.presentation" ||
+        name.endsWith(".pptx")) {
+        try {
+            const text = await officeparser.parseOfficeAsync(buffer);
+            return text;
+        }
+        catch (err) {
+            return `[Error extracting PPTX text: ${err instanceof Error ? err.message : String(err)}]`;
+        }
+    }
+    // DOCX files
+    if (mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document" ||
+        name.endsWith(".docx")) {
+        try {
+            const text = await officeparser.parseOfficeAsync(buffer);
+            return text;
+        }
+        catch (err) {
+            return `[Error extracting DOCX text: ${err instanceof Error ? err.message : String(err)}]`;
+        }
+    }
+    // XLSX files
+    if (mimeType === "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" ||
+        name.endsWith(".xlsx")) {
+        try {
+            const text = await officeparser.parseOfficeAsync(buffer);
+            return text;
+        }
+        catch (err) {
+            return `[Error extracting XLSX text: ${err instanceof Error ? err.message : String(err)}]`;
+        }
+    }
+    return `[Unsupported file format: ${mimeType}]`;
+}
+export function isExtractable(file) {
+    const name = file.name.toLowerCase();
+    return (name.endsWith(".txt") ||
+        name.endsWith(".vtt") ||
+        name.endsWith(".md") ||
+        name.endsWith(".pdf") ||
+        name.endsWith(".pptx") ||
+        name.endsWith(".docx") ||
+        name.endsWith(".xlsx"));
+}

package/dist/tools.d.ts

@@ -0,0 +1,2 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function registerToolHandlers(server: Server): void;

package/dist/tools.js

@@ -0,0 +1,151 @@
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { listAllFiles, downloadFile, categorizeFile } from "./drive.js";
+import { extractText, isExtractable } from "./text-extract.js";
+import { trackToolCall } from "./tracking.js";
+// In-memory text cache for search (populated on first search)
+const textCache = new Map();
+async function ensureTextCache() {
+    if (textCache.size > 0)
+        return;
+    const files = await listAllFiles();
+    const extractableFiles = files.filter(isExtractable);
+    for (const file of extractableFiles) {
+        try {
+            const buffer = await downloadFile(file);
+            const text = await extractText(file, buffer);
+            textCache.set(file.id, { file, text });
+        }
+        catch {
+            // Skip files that fail to download/extract
+        }
+    }
+}
+function searchInText(text, query) {
+    const queryLower = query.toLowerCase();
+    const lines = text.split("\n");
+    const matches = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].toLowerCase().includes(queryLower)) {
+            matches.push({ line: lines[i].trim(), lineNumber: i + 1 });
+        }
+    }
+    return matches;
+}
+export function registerToolHandlers(server) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "search_materials",
+                description: "Search across all course materials (lecture transcripts, presentations, exams) for relevant content. Use this when a student asks about a specific topic.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "The search query (topic, keyword, or phrase to find in course materials)",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "list_materials",
+                description: "List all available course materials, optionally filtered by category.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        category: {
+                            type: "string",
+                            enum: ["lectures", "transcripts", "exams", "all"],
+                            description: "Filter by category. Defaults to 'all'.",
+                        },
+                    },
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        trackToolCall(name, args);
+        if (name === "search_materials") {
+            const query = args.query;
+            if (!query) {
+                return {
+                    content: [{ type: "text", text: "Error: query parameter is required" }],
+                };
+            }
+            await ensureTextCache();
+            const results = [];
+            for (const [, { file, text }] of textCache) {
+                const matches = searchInText(text, query);
+                if (matches.length > 0) {
+                    results.push({
+                        fileName: file.name,
+                        path: file.path,
+                        category: categorizeFile(file),
+                        matches: matches.slice(0, 5), // Top 5 matches per file
+                    });
+                }
+            }
+            if (results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No results found for "${query}" in course materials.`,
+                        },
+                    ],
+                };
+            }
+            const formatted = results
+                .map((r) => {
+                const matchLines = r.matches
+                    .map((m) => `  Line ${m.lineNumber}: ${m.line.substring(0, 200)}`)
+                    .join("\n");
+                return `📄 ${r.fileName} [${r.category}]\n   Path: ${r.path}\n${matchLines}`;
+            })
+                .join("\n\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Found matches in ${results.length} file(s) for "${query}":\n\n${formatted}`,
+                    },
+                ],
+            };
+        }
+        if (name === "list_materials") {
+            const category = args.category || "all";
+            const files = await listAllFiles();
+            const extractableFiles = files.filter(isExtractable);
+            const filtered = category === "all"
+                ? extractableFiles
+                : extractableFiles.filter((f) => categorizeFile(f) === category);
+            // Group by category
+            const grouped = {};
+            for (const file of filtered) {
+                const cat = categorizeFile(file);
+                if (!grouped[cat])
+                    grouped[cat] = [];
+                grouped[cat].push(file);
+            }
+            const formatted = Object.entries(grouped)
+                .map(([cat, files]) => {
+                const fileList = files
+                    .map((f) => `  - ${f.name} (${f.path})`)
+                    .join("\n");
+                return `📁 ${cat.toUpperCase()} (${files.length} files)\n${fileList}`;
+            })
+                .join("\n\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Course materials${category !== "all" ? ` [${category}]` : ""}:\n\n${formatted}`,
+                    },
+                ],
+            };
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    });
+}

package/dist/tracking.d.ts

@@ -0,0 +1,6 @@
+export declare function getAnonymousId(): string;
+export declare function trackEvent(event: string, data?: Record<string, unknown>): void;
+export declare function trackToolCall(toolName: string, args?: Record<string, unknown>): void;
+export declare function trackResourceRead(uri: string): void;
+export declare function trackServerStart(): void;
+export declare function trackError(error: string, context?: string): void;

package/dist/tracking.js

@@ -0,0 +1,55 @@
+import { readFileSync, writeFileSync, appendFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { randomUUID } from "crypto";
+const CONFIG_DIR = join(homedir(), ".sad-mcp");
+const ANON_ID_PATH = join(CONFIG_DIR, "anonymous-id.txt");
+const LOG_PATH = join(CONFIG_DIR, "usage-log.jsonl");
+function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+}
+export function getAnonymousId() {
+    ensureConfigDir();
+    try {
+        return readFileSync(ANON_ID_PATH, "utf-8").trim();
+    }
+    catch {
+        const id = randomUUID();
+        writeFileSync(ANON_ID_PATH, id);
+        return id;
+    }
+}
+export function trackEvent(event, data) {
+    ensureConfigDir();
+    const entry = {
+        timestamp: new Date().toISOString(),
+        anonymousId: getAnonymousId(),
+        event,
+        data,
+    };
+    try {
+        appendFileSync(LOG_PATH, JSON.stringify(entry) + "\n");
+    }
+    catch {
+        // Silently fail — tracking should never break the server
+    }
+    // TODO: MCPcat integration
+    // When MCPcat TypeScript SDK is configured, send events here:
+    //   import { MCPCat } from "mcpcat";
+    //   const mcpcat = new MCPCat({ apiKey: "YOUR_MCPCAT_API_KEY" });
+    //   mcpcat.track(entry);
+}
+export function trackToolCall(toolName, args) {
+    trackEvent("tool_call", { tool: toolName, arguments: args });
+}
+export function trackResourceRead(uri) {
+    trackEvent("resource_read", { uri });
+}
+export function trackServerStart() {
+    trackEvent("server_start", { version: "0.1.0" });
+}
+export function trackError(error, context) {
+    trackEvent("error", { error, context });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "sad-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Software Analysis and Design course materials at BGU",
+  "type": "module",
+  "bin": {
+    "sad-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "course-materials",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "googleapis": "^144.0.0",
+    "open": "^10.0.0",
+    "officeparser": "^4.0.0",
+    "pdf-parse": "^1.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0",
+    "@types/pdf-parse": "^1.1.4"
+  }
+}