sad-mcp 1.0.3 → 1.1.1

package/README.md

@@ -1,84 +1,91 @@
 # sad-mcp
 
-MCP server that gives students access to **Software Analysis and Design** course materials through Claude Desktop. Materials are served from a shared Google Drive folder.
+MCP server that gives students access to **Software Analysis and Design** course materials and diagram tools through Claude Desktop.
 
-## What it does
+## Student Setup
 
-- Exposes course materials (lectures, transcripts, exams) as MCP **resources**
-- Provides `search_materials` and `list_materials` **tools** for Claude to query course content
-- Extracts text from PPTX, PDF, DOCX, XLSX, and plain text files
-- Caches files locally to avoid repeated downloads
-- Tracks anonymous usage for research purposes
+### Step 1 — Find your config file
 
-## Student setup
+| How you installed Claude Desktop | Config file location |
+|---|---|
+| **Microsoft Store** (Windows) | `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json` |
+| **Standard installer** (Windows) | `%APPDATA%\Roaming\Claude\claude_desktop_config.json` |
+| **Mac** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
 
-Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+Not sure which? Search your user profile for `claude_desktop_config.json`.
 
-```json
-{
-  "mcpServers": {
-    "sad-course": {
-      "command": "npx",
-      "args": ["-y", "sad-mcp@latest"]
-    }
-  }
-}
-```
+### Step 2 — Edit the config file
 
-On Windows, use the full path to `npx.cmd`:
+Open the file in a text editor and add the `sad-mcp` entry. If the file already has other MCP servers, add alongside them:
 
 ```json
 {
   "mcpServers": {
-    "sad-course": {
-      "command": "C:\\Program Files\\nodejs\\npx.cmd",
+    "sad-mcp": {
+      "command": "npx",
       "args": ["-y", "sad-mcp@latest"]
     }
   }
 }
 ```
 
-On first run, a browser window will open for Google authentication. Sign in with your **@post.bgu.ac.il** account. After that, the server connects automatically.
-
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `search_materials(query)` | Full-text search across all course materials |
-| `list_materials(category?)` | List available materials, optionally filtered by `lectures`, `transcripts`, `exams`, or `all` |
+> **Windows note:** If Claude Desktop doesn't find `npx`, use the full path:
+> ```json
+> {
+>   "mcpServers": {
+>     "sad-mcp": {
+>       "command": "C:\\Program Files\\nodejs\\npx.cmd",
+>       "args": ["-y", "sad-mcp@latest"]
+>     }
+>   }
+> }
+> ```
 
-## Resources
+### Step 3 — Restart Claude Desktop
 
-All extractable files from the course Google Drive folder are exposed as MCP resources with URIs like `sad://lectures/filename.pptx` or `sad://transcripts/filename.txt`. Claude can read these directly.
+Fully quit Claude Desktop (system tray → Quit — not just close the window), then reopen it.
 
-## Local data
+### Step 4 — Authenticate with Google
 
-The server stores data in `~/.sad-mcp/`:
+On the first tool call, a browser window will open for Google authentication. Sign in with your **@post.bgu.ac.il** account. After that, the server connects automatically on every restart.
 
-| File | Purpose |
-|------|---------|
-| `tokens.json` | Google OAuth refresh token |
-| `anonymous-id.txt` | Random UUID for usage tracking |
-| `usage-log.jsonl` | Local usage event log |
-| `cache/` | Downloaded file cache (1-hour TTL) |
-| `cache-index.json` | Cache metadata |
+---
 
-## Development
-
-```bash
-npm install
-npm run build    # compile TypeScript
-npm run dev      # watch mode
-```
-
-## Publishing
-
-```bash
-# bump version in package.json
-npm publish
-```
+## What it does
 
-Students get the latest version automatically via `npx -y sad-mcp@latest`.
+### Course materials
+- Search and browse lectures, transcripts, and past exams from the course Google Drive
+- Extracts text from PPTX, PDF, DOCX files for full-text search
+
+### Diagram tools
+| Tool | What it does |
+|---|---|
+| `bpmn_analysis` | Analyze a business process and produce a BPMN 1.0 model |
+| `bpmn_validate_model` | Validate the JSON model before rendering |
+| `bpmn_render` | Render the validated model as an HTML file saved to your Desktop |
+| `uml_use_case` | Create a UML use case diagram |
+| `uml_class_diagram` | Create a UML class diagram |
+| `uml_state_diagram` | Create a UML state diagram |
+| `uml_write_file` | Save a generated UML diagram to your Desktop |
+
+### Course material tools
+| Tool | What it does |
+|---|---|
+| `search_materials` | Full-text search across all course materials |
+| `list_materials` | List available materials by category |
+| `get_material` | Read the full text of a specific file |
+| `list_exams` | List available past exams |
+| `practice_exam` | Get a past exam to practice with |
+
+---
+
+## Requirements
+
+- [Claude Desktop](https://claude.ai/download) installed
+- [Node.js](https://nodejs.org/) v18 or later (verify: `node --version` in a terminal)
+- A `@post.bgu.ac.il` Google account with access to the course Drive folder
+
+---
 
 ## License
 

package/dist/bpmn/export-bpmn.d.ts

@@ -0,0 +1,8 @@
+import type { LaidOutModel } from "./types.js";
+export declare function buildBPMNXml(laid: LaidOutModel): string;
+export declare function safeFilename(m: {
+    title: {
+        he: string;
+        en?: string;
+    };
+}): string;

package/dist/bpmn/export-bpmn.js

@@ -0,0 +1,167 @@
+// Generates BPMN 2.0 XML (with DI section) server-side, using the
+// coordinates already computed by the layout pass. The VP export button
+// embedded in the HTML just triggers a download of this precomputed
+// string — no DOM walking, no getBBox() calls.
+//
+// Reference namespaces from OMG BPMN 2.0:
+//   bpmn   http://www.omg.org/spec/BPMN/20100524/MODEL
+//   bpmndi http://www.omg.org/spec/BPMN/20100524/DI
+//   dc     http://www.omg.org/spec/DD/20100524/DC
+//   di     http://www.omg.org/spec/DD/20100524/DI
+import { escapeXml } from "./svg.js";
+export function buildBPMNXml(laid) {
+    const m = laid.model;
+    const title = escapeXml(m.title.en || m.title.he || "process");
+    // Map pool id → process id (each pool gets its own process element)
+    const processIds = new Map();
+    m.pools.forEach((p, i) => processIds.set(p.id, `process_${i + 1}`));
+    const processLines = [];
+    const collabLines = [];
+    // Participants reference pool processes
+    for (const p of m.pools) {
+        const procId = processIds.get(p.id);
+        collabLines.push(`    <bpmn:participant id="${escapeXml(p.id)}" name="${escapeXml(p.name)}" processRef="${procId}"/>`);
+    }
+    for (const mf of m.messageFlows) {
+        const src = mf.fromElement ?? mf.fromPool;
+        const tgt = mf.toElement ?? mf.toPool;
+        const name = mf.label ? ` name="${escapeXml(mf.label)}"` : "";
+        collabLines.push(`    <bpmn:messageFlow id="${escapeXml(mf.id)}" sourceRef="${escapeXml(src)}" targetRef="${escapeXml(tgt)}"${name}/>`);
+    }
+    // One bpmn:process block per pool
+    const processBlocks = [];
+    for (const p of m.pools) {
+        const procId = processIds.get(p.id);
+        const poolElements = m.elements.filter((el) => {
+            if (el.kind === "task" || el.kind === "gateway" || el.kind === "event" || el.kind === "collapsedSubProcess") {
+                return el.pool === p.id;
+            }
+            return false;
+        });
+        const poolFlows = m.sequenceFlows.filter((f) => {
+            const src = m.elements.find((e) => e.id === f.from);
+            const tgt = m.elements.find((e) => e.id === f.to);
+            if (!src || !tgt)
+                return false;
+            const srcPool = src.pool;
+            const tgtPool = tgt.pool;
+            return srcPool === p.id && tgtPool === p.id;
+        });
+        // Lanes (if organization pool with lanes)
+        const laneSetLines = [];
+        if (p.lanes.length > 0) {
+            laneSetLines.push(`      <bpmn:laneSet id="${procId}_laneset">`);
+            for (const lane of p.lanes) {
+                const laneElements = poolElements.filter((e) => e.lane === lane.id);
+                laneSetLines.push(`        <bpmn:lane id="${escapeXml(lane.id)}" name="${escapeXml(lane.name)}">`);
+                for (const le of laneElements) {
+                    laneSetLines.push(`          <bpmn:flowNodeRef>${escapeXml(le.id)}</bpmn:flowNodeRef>`);
+                }
+                laneSetLines.push(`        </bpmn:lane>`);
+            }
+            laneSetLines.push(`      </bpmn:laneSet>`);
+        }
+        // Element lines
+        const elLines = [];
+        for (const el of poolElements) {
+            const id = escapeXml(el.id);
+            const name = escapeXml(el.name ?? "");
+            if (el.kind === "task") {
+                elLines.push(`      <bpmn:task id="${id}" name="${name}"/>`);
+            }
+            else if (el.kind === "collapsedSubProcess") {
+                elLines.push(`      <bpmn:subProcess id="${id}" name="${name}"/>`);
+            }
+            else if (el.kind === "gateway") {
+                const tag = el.gatewayType === "AND" ? "parallelGateway"
+                    : el.gatewayType === "OR" ? "inclusiveGateway"
+                        : "exclusiveGateway";
+                elLines.push(`      <bpmn:${tag} id="${id}" name="${name}"/>`);
+            }
+            else if (el.kind === "event") {
+                const tag = el.eventType === "start" ? "startEvent"
+                    : el.eventType === "end" ? "endEvent"
+                        : "intermediateCatchEvent";
+                elLines.push(`      <bpmn:${tag} id="${id}" name="${name}"/>`);
+            }
+        }
+        // Data stores and objects are declared at process level
+        for (const el of m.elements) {
+            if (el.kind === "dataStore") {
+                elLines.push(`      <bpmn:dataStoreReference id="${escapeXml(el.id)}" name="${escapeXml(el.name)}"/>`);
+            }
+            else if (el.kind === "dataObject") {
+                elLines.push(`      <bpmn:dataObjectReference id="${escapeXml(el.id)}" name="${escapeXml(el.name)}"/>`);
+            }
+        }
+        for (const f of poolFlows) {
+            const name = f.label ? ` name="${escapeXml(f.label)}"` : "";
+            elLines.push(`      <bpmn:sequenceFlow id="${escapeXml(f.id)}" sourceRef="${escapeXml(f.from)}" targetRef="${escapeXml(f.to)}"${name}/>`);
+        }
+        processBlocks.push(`  <bpmn:process id="${procId}" name="${escapeXml(p.name)}" isExecutable="false">
+${laneSetLines.join("\n")}
+${elLines.join("\n")}
+  </bpmn:process>`);
+    }
+    // DI section — harvest coords from layout
+    const diLines = [];
+    // Pool shapes
+    for (const p of laid.pools) {
+        diLines.push(`      <bpmndi:BPMNShape id="${escapeXml(p.poolId)}_di" bpmnElement="${escapeXml(p.poolId)}" isHorizontal="true">
+        <dc:Bounds x="${round(p.x)}" y="${round(p.y)}" width="${round(p.w)}" height="${round(p.h)}"/>
+      </bpmndi:BPMNShape>`);
+        for (const ln of p.lanes) {
+            if (!ln.laneId)
+                continue;
+            diLines.push(`      <bpmndi:BPMNShape id="${escapeXml(ln.laneId)}_di" bpmnElement="${escapeXml(ln.laneId)}" isHorizontal="true">
+        <dc:Bounds x="${round(ln.x)}" y="${round(ln.y)}" width="${round(ln.w)}" height="${round(ln.h)}"/>
+      </bpmndi:BPMNShape>`);
+        }
+    }
+    // Element shapes
+    for (const [id, pl] of laid.placements) {
+        diLines.push(`      <bpmndi:BPMNShape id="${escapeXml(id)}_di" bpmnElement="${escapeXml(id)}">
+        <dc:Bounds x="${round(pl.box.x)}" y="${round(pl.box.y)}" width="${round(pl.box.w)}" height="${round(pl.box.h)}"/>
+      </bpmndi:BPMNShape>`);
+    }
+    // Sequence flow edges
+    for (const r of laid.sequenceRoutes) {
+        const waypoints = r.points.map((p) => `        <di:waypoint x="${round(p.x)}" y="${round(p.y)}"/>`).join("\n");
+        diLines.push(`      <bpmndi:BPMNEdge id="${escapeXml(r.id)}_di" bpmnElement="${escapeXml(r.id)}">
+${waypoints}
+      </bpmndi:BPMNEdge>`);
+    }
+    for (const r of laid.messageRoutes) {
+        const waypoints = r.points.map((p) => `        <di:waypoint x="${round(p.x)}" y="${round(p.y)}"/>`).join("\n");
+        diLines.push(`      <bpmndi:BPMNEdge id="${escapeXml(r.id)}_di" bpmnElement="${escapeXml(r.id)}">
+${waypoints}
+      </bpmndi:BPMNEdge>`);
+    }
+    const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+  xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
+  xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
+  xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  id="Definitions_1" targetNamespace="http://bpmn.io/schema/bpmn">
+${processBlocks.join("\n")}
+  <bpmn:collaboration id="collab_1">
+${collabLines.join("\n")}
+  </bpmn:collaboration>
+  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
+    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="collab_1">
+${diLines.join("\n")}
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</bpmn:definitions>`;
+    return xml;
+}
+function round(n) { return Math.round(n); }
+// Returned for completeness — a caller may want the stable safe title
+export function safeFilename(m) {
+    const base = (m.title.en || m.title.he || "process")
+        .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+        .replace(/\s+/g, "_")
+        .slice(0, 60);
+    return base || "process";
+}

package/dist/bpmn/index.d.ts

@@ -0,0 +1,18 @@
+import { layoutModel } from "./layout.js";
+import { routeAll } from "./routing.js";
+import { computeStats, renderHTML, type RenderStats } from "./template.js";
+import { parseAndValidate, validateModel, formatIssues } from "./validate.js";
+import type { DiagramModel, ValidationIssue } from "./types.js";
+import { safeFilename } from "./export-bpmn.js";
+export type RenderResult = {
+    ok: true;
+    html: string;
+    stats: RenderStats;
+    filenameBase: string;
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+};
+export declare function renderBPMN(rawJson: string | object): RenderResult;
+export { validateModel, parseAndValidate, formatIssues, layoutModel, routeAll, renderHTML, computeStats, safeFilename, };
+export type { DiagramModel, ValidationIssue };

package/dist/bpmn/index.js

@@ -0,0 +1,23 @@
+// Public entry point for the BPMN rendering pipeline.
+// Pipeline: raw JSON → validate → layout → route → render HTML.
+import { layoutModel } from "./layout.js";
+import { routeAll } from "./routing.js";
+import { computeStats, renderHTML } from "./template.js";
+import { parseAndValidate, validateModel, formatIssues } from "./validate.js";
+import { safeFilename } from "./export-bpmn.js";
+export function renderBPMN(rawJson) {
+    const vr = typeof rawJson === "string"
+        ? parseAndValidate(rawJson)
+        : validateModel(rawJson);
+    if (!vr.ok)
+        return { ok: false, issues: vr.issues };
+    const laid = routeAll(layoutModel(vr.model));
+    const html = renderHTML(laid);
+    return {
+        ok: true,
+        html,
+        stats: computeStats(laid),
+        filenameBase: safeFilename(vr.model),
+    };
+}
+export { validateModel, parseAndValidate, formatIssues, layoutModel, routeAll, renderHTML, computeStats, safeFilename, };

package/dist/bpmn/layout.d.ts

@@ -0,0 +1,22 @@
+import type { DiagramModel, LaidOutModel } from "./types.js";
+export declare const L: {
+    readonly TASK_W: 140;
+    readonly TASK_H: 64;
+    readonly GW: 48;
+    readonly EVT_R: 18;
+    readonly COL_W: 186;
+    readonly GAP_X: 46;
+    readonly GAP_Y: 20;
+    readonly POOL_HEADER_W: 30;
+    readonly LANE_HEADER_W: 24;
+    readonly POOL_VGAP: 16;
+    readonly LANE_MIN_H: 140;
+    readonly LANE_CORRIDOR_H: 56;
+    readonly EMPTY_POOL_H: 60;
+    readonly CANVAS_TOP: 72;
+    readonly CANVAS_LEFT_PAD: 20;
+    readonly CANVAS_RIGHT_PAD: 40;
+    readonly CANVAS_BOTTOM_PAD: 20;
+    readonly MIN_CANVAS_W: 1400;
+};
+export declare function layoutModel(m: DiagramModel): LaidOutModel;