sad-mcp 1.1.0 → 1.1.2

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 +18 -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.2",
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,27 @@ 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
+ «include» means: every time the base UC runs, the included UC **always** runs as part of it — no exceptions, no conditions. It is not "if X happens, then Y" — that is «extend». It is "X always does Y as part of its execution."
79
+
80
+ However, **always-happens does not automatically mean extract**. A step that always happens inside a UC is usually just part of that UC. Only extract it when:
81
+ 1. It is shared by **2 or more** base UCs — there must be ≥2 incoming «include» arrows
82
+ 2. The included UC has **no direct association to any actor** — actor-connected UCs are standalone UCs, not sub-behaviors
83
+ 3. Extracting it genuinely reduces duplication — not just because it feels like a "step"
84
+
85
+ Arrow direction: Base UC → Included UC. Dashed line, open arrowhead.
79
86
 
80
- Arrow direction: Base UC → Included UC. Dashed line, open arrowhead. **One arrow = fold into parent.**
87
+ **Immediate disqualifiers:**
88
+ - Only one base UC points to it → fold it into the parent UC
89
+ - An actor connects to it → it is a regular standalone UC, not an «include» target
90
+ - It is conditional or optional → that is «extend», not «include»
81
91
 
82
92
  ### «extend»
83
- Optional/conditional behavior. Arrow: Extension UC → Base UC. Use sparingly.
93
+ «extend» means: sometimes, under a specific condition, an additional behavior fires. The base UC runs fine without it.
84
94
 
85
- **Default**: keep behavior inside the parent UC. Only extract if the sub-behavior is truly shared or optional.
95
+ Arrow direction: Extension UC → Base UC. Use at most once or twice per diagram. If you cannot state the exact condition in one sentence, do not add it.
86
96
 
87
97
  ---
88
98