sad-mcp 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +63 -56
  2. package/package.json +1 -1
  3. package/skills/uml-use-case-diagram/SKILL.md +21 -8
package/README.md CHANGED
@@ -1,84 +1,91 @@
1
1
  # sad-mcp
2
2
 
3
- 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.
3
+ MCP server that gives students access to **Software Analysis and Design** course materials and diagram tools through Claude Desktop.
4
4
 
5
- ## What it does
5
+ ## Student Setup
6
6
 
7
- - Exposes course materials (lectures, transcripts, exams) as MCP **resources**
8
- - Provides `search_materials` and `list_materials` **tools** for Claude to query course content
9
- - Extracts text from PPTX, PDF, DOCX, XLSX, and plain text files
10
- - Caches files locally to avoid repeated downloads
11
- - Tracks anonymous usage for research purposes
7
+ ### Step 1 — Find your config file
12
8
 
13
- ## Student setup
9
+ | How you installed Claude Desktop | Config file location |
10
+ |---|---|
11
+ | **Microsoft Store** (Windows) | `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json` |
12
+ | **Standard installer** (Windows) | `%APPDATA%\Roaming\Claude\claude_desktop_config.json` |
13
+ | **Mac** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
14
14
 
15
- Add to your Claude Desktop configuration (`claude_desktop_config.json`):
15
+ Not sure which? Search your user profile for `claude_desktop_config.json`.
16
16
 
17
- ```json
18
- {
19
- "mcpServers": {
20
- "sad-course": {
21
- "command": "npx",
22
- "args": ["-y", "sad-mcp@latest"]
23
- }
24
- }
25
- }
26
- ```
17
+ ### Step 2 — Edit the config file
27
18
 
28
- On Windows, use the full path to `npx.cmd`:
19
+ Open the file in a text editor and add the `sad-mcp` entry. If the file already has other MCP servers, add alongside them:
29
20
 
30
21
  ```json
31
22
  {
32
23
  "mcpServers": {
33
- "sad-course": {
34
- "command": "C:\\Program Files\\nodejs\\npx.cmd",
24
+ "sad-mcp": {
25
+ "command": "npx",
35
26
  "args": ["-y", "sad-mcp@latest"]
36
27
  }
37
28
  }
38
29
  }
39
30
  ```
40
31
 
41
- 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.
42
-
43
- ## Tools
44
-
45
- | Tool | Description |
46
- |------|-------------|
47
- | `search_materials(query)` | Full-text search across all course materials |
48
- | `list_materials(category?)` | List available materials, optionally filtered by `lectures`, `transcripts`, `exams`, or `all` |
32
+ > **Windows note:** If Claude Desktop doesn't find `npx`, use the full path:
33
+ > ```json
34
+ > {
35
+ > "mcpServers": {
36
+ > "sad-mcp": {
37
+ > "command": "C:\\Program Files\\nodejs\\npx.cmd",
38
+ > "args": ["-y", "sad-mcp@latest"]
39
+ > }
40
+ > }
41
+ > }
42
+ > ```
49
43
 
50
- ## Resources
44
+ ### Step 3 — Restart Claude Desktop
51
45
 
52
- 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.
46
+ Fully quit Claude Desktop (system tray → Quit — not just close the window), then reopen it.
53
47
 
54
- ## Local data
48
+ ### Step 4 — Authenticate with Google
55
49
 
56
- The server stores data in `~/.sad-mcp/`:
50
+ 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.
57
51
 
58
- | File | Purpose |
59
- |------|---------|
60
- | `tokens.json` | Google OAuth refresh token |
61
- | `anonymous-id.txt` | Random UUID for usage tracking |
62
- | `usage-log.jsonl` | Local usage event log |
63
- | `cache/` | Downloaded file cache (1-hour TTL) |
64
- | `cache-index.json` | Cache metadata |
52
+ ---
65
53
 
66
- ## Development
67
-
68
- ```bash
69
- npm install
70
- npm run build # compile TypeScript
71
- npm run dev # watch mode
72
- ```
73
-
74
- ## Publishing
75
-
76
- ```bash
77
- # bump version in package.json
78
- npm publish
79
- ```
54
+ ## What it does
80
55
 
81
- Students get the latest version automatically via `npx -y sad-mcp@latest`.
56
+ ### Course materials
57
+ - Search and browse lectures, transcripts, and past exams from the course Google Drive
58
+ - Extracts text from PPTX, PDF, DOCX files for full-text search
59
+
60
+ ### Diagram tools
61
+ | Tool | What it does |
62
+ |---|---|
63
+ | `bpmn_analysis` | Analyze a business process and produce a BPMN 1.0 model |
64
+ | `bpmn_validate_model` | Validate the JSON model before rendering |
65
+ | `bpmn_render` | Render the validated model as an HTML file saved to your Desktop |
66
+ | `uml_use_case` | Create a UML use case diagram |
67
+ | `uml_class_diagram` | Create a UML class diagram |
68
+ | `uml_state_diagram` | Create a UML state diagram |
69
+ | `uml_write_file` | Save a generated UML diagram to your Desktop |
70
+
71
+ ### Course material tools
72
+ | Tool | What it does |
73
+ |---|---|
74
+ | `search_materials` | Full-text search across all course materials |
75
+ | `list_materials` | List available materials by category |
76
+ | `get_material` | Read the full text of a specific file |
77
+ | `list_exams` | List available past exams |
78
+ | `practice_exam` | Get a past exam to practice with |
79
+
80
+ ---
81
+
82
+ ## Requirements
83
+
84
+ - [Claude Desktop](https://claude.ai/download) installed
85
+ - [Node.js](https://nodejs.org/) v18 or later (verify: `node --version` in a terminal)
86
+ - A `@post.bgu.ac.il` Google account with access to the course Drive folder
87
+
88
+ ---
82
89
 
83
90
  ## License
84
91
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sad-mcp",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "MCP server for Software Analysis and Design course materials at BGU",
5
5
  "type": "module",
6
6
  "bin": {
package/skills/uml-use-case-diagram/SKILL.md CHANGED
@@ -24,9 +24,10 @@ The shared files prepended to this prompt define the layout recipes, model shape
24
24
  1. **Hebrew: male form only.** אח (not אחות). מזכיר (not מזכירה). מטופל (not מטופלת). רופא (not רופאה). Verify every Hebrew label before writing.
25
25
  2. **No generic catch-all use cases.** "ניהול הגדרות מערכת" is forbidden. Each entity → its own UC.
26
26
  3. **All ellipses have solid borders.** Dashed = relationship lines only, never ellipse borders.
27
- 4. **«include» target must have 2+ incoming arrows and no direct actor association.** A single-arrow «include» is always wrong.
27
+ 4. **«include» target must have ≥2 incoming «include» arrows AND no direct actor association.** A UC connected to an actor can NEVER be an «include» target. A single «include» arrow is always wrong — fold it into the parent.
28
28
  5. **Every use case must have at least one association line to an actor.**
29
29
  6. **Actors must not overlap** — minimum 200px vertical distance between actor centers.
30
+ 7. **Default: no «include» or «extend».** Most diagrams need zero or one. If you have more than two, you are almost certainly wrong. Treat every «include»/«extend» you consider adding as guilty until proven innocent.
30
31
 
31
32
  ---
32
33
 
@@ -71,18 +72,30 @@ The shared files prepended to this prompt define the layout recipes, model shape
71
72
 
72
73
  ## 4. Include and Extend
73
74
 
75
+ **Start with zero.** Add «include» or «extend» only when you can explicitly justify it against the tests below. When in doubt, leave it out.
76
+
74
77
  ### «include»
75
- Use only when ALL three hold:
76
- 1. Sub-behavior is **mandatory** for the base UC
77
- 2. Sub-behavior is shared by **2+ use cases** — must have ≥2 incoming «include» arrows
78
- 3. The included UC is a **dedicated sub-behavior** — no direct actor associations to it
78
+ Allowed only when **all four** hold:
79
+ 1. The sub-behavior is **mandatory** every time the base UC runs
80
+ 2. The sub-behavior is shared by **2 or more** base UCs — there must be ≥2 incoming «include» arrows
81
+ 3. The included UC has **no direct association to any actor** — if any actor connects to it, it is a regular UC, not an included sub-behavior
82
+ 4. Extracting it genuinely simplifies the diagram — if the diagram becomes more complex, fold it back in
83
+
84
+ Arrow direction: Base UC → Included UC. Dashed line, open arrowhead.
79
85
 
80
- Arrow direction: Base UC → Included UC. Dashed line, open arrowhead. **One arrow = fold into parent.**
86
+ **Immediate disqualifiers — if any apply, do NOT use «include»:**
87
+ - Only one base UC points to it → fold into the parent
88
+ - An actor has an association line to it → it is a standalone UC
89
+ - You added it just to avoid repeating a label → wrong reason; keep behavior inside the UC
81
90
 
82
91
  ### «extend»
83
- Optional/conditional behavior. Arrow: Extension UC → Base UC. Use sparingly.
92
+ Allowed only when:
93
+ 1. The behavior is **genuinely optional or conditional** (not just infrequent)
94
+ 2. The extension would clutter the base UC if included inside it
95
+
96
+ Arrow direction: Extension UC → Base UC. Use at most once or twice per diagram.
84
97
 
85
- **Default**: keep behavior inside the parent UC. Only extract if the sub-behavior is truly shared or optional.
98
+ **If you cannot articulate the exact condition under which the extension fires, do not add it.**
86
99
 
87
100
  ---
88
101