cysuml 0.1.0__tar.gz
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.
- cysuml-0.1.0/LICENSE +21 -0
- cysuml-0.1.0/PKG-INFO +466 -0
- cysuml-0.1.0/README.md +450 -0
- cysuml-0.1.0/pyproject.toml +33 -0
- cysuml-0.1.0/pyproject.toml.orig +32 -0
- cysuml-0.1.0/src/cysuml/__init__.py +1 -0
- cysuml-0.1.0/src/cysuml/__main__.py +13 -0
- cysuml-0.1.0/src/cysuml/activitydiagram.py +74 -0
- cysuml-0.1.0/src/cysuml/boxcheck.py +740 -0
- cysuml-0.1.0/src/cysuml/boxdiagram.py +1061 -0
- cysuml-0.1.0/src/cysuml/canvas.py +454 -0
- cysuml-0.1.0/src/cysuml/classcheck.py +15 -0
- cysuml-0.1.0/src/cysuml/classdiagram.py +472 -0
- cysuml-0.1.0/src/cysuml/componentdiagram.py +173 -0
- cysuml-0.1.0/src/cysuml/deploymentdiagram.py +94 -0
- cysuml-0.1.0/src/cysuml/flowshapes.py +251 -0
- cysuml-0.1.0/src/cysuml/fonts/LiberationSans-Bold.ttf +0 -0
- cysuml-0.1.0/src/cysuml/fonts/LiberationSans-LICENSE.txt +102 -0
- cysuml-0.1.0/src/cysuml/fonts/LiberationSans-Regular.ttf +0 -0
- cysuml-0.1.0/src/cysuml/fonts/NotoSansKR-Bold.otf +0 -0
- cysuml-0.1.0/src/cysuml/fonts/NotoSansKR-LICENSE.txt +92 -0
- cysuml-0.1.0/src/cysuml/fonts/NotoSansKR-Regular.otf +0 -0
- cysuml-0.1.0/src/cysuml/fonts/README.md +12 -0
- cysuml-0.1.0/src/cysuml/geom.py +659 -0
- cysuml-0.1.0/src/cysuml/guide.py +245 -0
- cysuml-0.1.0/src/cysuml/packagediagram.py +61 -0
- cysuml-0.1.0/src/cysuml/parsing.py +84 -0
- cysuml-0.1.0/src/cysuml/report.py +109 -0
- cysuml-0.1.0/src/cysuml/sequencecheck.py +706 -0
- cysuml-0.1.0/src/cysuml/sequencediagram.py +1456 -0
- cysuml-0.1.0/src/cysuml/server.py +374 -0
- cysuml-0.1.0/src/cysuml/shapes.py +269 -0
- cysuml-0.1.0/src/cysuml/statediagram.py +84 -0
- cysuml-0.1.0/src/cysuml/text.py +159 -0
- cysuml-0.1.0/src/cysuml/usecasediagram.py +205 -0
cysuml-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 yschoi9733
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
cysuml-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,466 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cysuml
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server that draws document-ready UML diagrams: the AI lays them out, cysUML draws and checks them
|
|
5
|
+
License-Expression: MIT AND OFL-1.1
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
License-File: src/cysuml/fonts/LiberationSans-LICENSE.txt
|
|
8
|
+
License-File: src/cysuml/fonts/NotoSansKR-LICENSE.txt
|
|
9
|
+
Requires-Dist: fonttools>=4.38
|
|
10
|
+
Requires-Dist: mcp>=2.3.0
|
|
11
|
+
Requires-Dist: pillow>=10.1.0
|
|
12
|
+
Requires-Python: >=3.10
|
|
13
|
+
Project-URL: Repository, https://github.com/yschoi9733/cysUML
|
|
14
|
+
Project-URL: Issues, https://github.com/yschoi9733/cysUML/issues
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# cysUML
|
|
18
|
+
|
|
19
|
+
An MCP server for document-ready UML diagrams: the AI lays them out, cysUML draws and checks them.
|
|
20
|
+
|
|
21
|
+
[한국어 안내](#한국어)
|
|
22
|
+
|
|
23
|
+
Auto-layout tools are quick, but lines often run through boxes and labels, and the result is hard to fix by hand.
|
|
24
|
+
cysUML takes the other way round: your AI assistant decides where every box goes, cysUML draws exactly that and
|
|
25
|
+
checks the drawing. If a line crosses a box or a label, the check fails and says what to move. The assistant fixes
|
|
26
|
+
the layout and draws again until the check passes.
|
|
27
|
+
|
|
28
|
+
- Several kinds of UML diagram; the list is under [Use](#use). Sequence diagrams are laid out by cysUML from the order
|
|
29
|
+
of participants and messages, and checked the same way.
|
|
30
|
+
- PNG output. The fonts are bundled, so every machine draws the same picture, Korean text included.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
You need [uv](https://docs.astral.sh/uv/). This one line downloads cysUML from [PyPI](https://pypi.org/project/cysuml/)
|
|
35
|
+
and starts the server:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
uvx cysuml
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
It talks MCP over stdin/stdout, so on its own it just waits for a client. Register it with your MCP client instead.
|
|
42
|
+
|
|
43
|
+
**Claude Code**
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
claude mcp add cysuml -- uvx cysuml
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
**Other clients** (Claude Desktop, Cursor, …) take the same command in their JSON config:
|
|
50
|
+
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"mcpServers": {
|
|
54
|
+
"cysuml": {
|
|
55
|
+
"command": "uvx",
|
|
56
|
+
"args": ["cysuml"]
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
**Versions.** `uvx cysuml` runs the newest release: each time the client starts the server, uv asks PyPI and reuses
|
|
63
|
+
the answer for up to ten minutes. If you installed it with `uv tool install cysuml`, uvx runs that copy instead;
|
|
64
|
+
update it with `uv tool upgrade cysuml`. To stay on one version, put it after the name: `uvx cysuml@0.1.0` (in JSON,
|
|
65
|
+
`"args": ["cysuml@0.1.0"]`). The releases are listed in the [release history](https://pypi.org/project/cysuml/#history).
|
|
66
|
+
|
|
67
|
+
## Use
|
|
68
|
+
|
|
69
|
+
Ask your assistant for a diagram, for example "draw a class diagram of the order domain with cysUML" or "draw the
|
|
70
|
+
checkout flow as a sequence diagram with cysUML". The server tells the assistant how to lay it out, so you don't
|
|
71
|
+
have to.
|
|
72
|
+
|
|
73
|
+
### Class diagrams
|
|
74
|
+
|
|
75
|
+
The tool is `draw_class_diagram`. The assistant sends boxes with their top-left corners and relations with
|
|
76
|
+
optional bend points:
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
{
|
|
80
|
+
"file_name": "order",
|
|
81
|
+
"classes": [
|
|
82
|
+
{"name": "Order", "left": 0, "top": 0, "attributes": ["-id: long"]},
|
|
83
|
+
{"name": "Customer", "left": 200, "top": 0}
|
|
84
|
+
],
|
|
85
|
+
"relations": [
|
|
86
|
+
{"kind": "association", "from": "Order", "to": "Customer", "name": "places", "to_multiplicity": "1"}
|
|
87
|
+
]
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
It gets back the check result, the size and place of every box as drawn, the saved file path, and the picture.
|
|
92
|
+
The check **fails** when boxes overlap, a line runs through a box, a label or another line's arrowhead, or labels
|
|
93
|
+
overlap. Crossing lines and the picture size are reported but don't fail. Inheritance lines from several children to
|
|
94
|
+
one parent may join into one trunk that shares a single triangle (realization lines too, but not mixed with
|
|
95
|
+
inheritance); the tool description tells the assistant how to give the bend points for it.
|
|
96
|
+
|
|
97
|
+
Relations must follow UML notation, and the tool rejects the input otherwise: a generalization joins two boxes of the
|
|
98
|
+
same kind (a class and an abstract class count as one kind), never runs in a cycle, and neither a generalization nor a
|
|
99
|
+
realization points back to its own box. A realization made by an interface, or one that ends on something other than
|
|
100
|
+
an interface, is drawn and reported as a notice. The package, component and deployment tools follow the same rules.
|
|
101
|
+
There a package or a provided interface ball is never an end of a generalization, a realization made by either of
|
|
102
|
+
them gets a notice, and a realization from a class to a component (the class realizes the component) does not. Icon
|
|
103
|
+
notations of components and artifacts count as the same kind as the plain ones.
|
|
104
|
+
|
|
105
|
+
### Package diagrams
|
|
106
|
+
|
|
107
|
+
The tool is `draw_package_diagram`. It draws packages and the dependencies between them, with classes and packages
|
|
108
|
+
inside packages, and takes components, artifacts and nodes in the same picture. Every element has a `kind`. An element
|
|
109
|
+
names the one it sits in with `in`, and the outer element grows right and down to cover it:
|
|
110
|
+
|
|
111
|
+
```json
|
|
112
|
+
{
|
|
113
|
+
"file_name": "packages",
|
|
114
|
+
"elements": [
|
|
115
|
+
{"kind": "package", "name": "web", "left": 0, "top": 0},
|
|
116
|
+
{"kind": "class", "name": "OrderController", "in": "web", "left": 20, "top": 44},
|
|
117
|
+
{"kind": "package", "name": "domain", "left": 0, "top": 180},
|
|
118
|
+
{"kind": "class", "name": "Order", "in": "domain", "left": 20, "top": 224},
|
|
119
|
+
{"kind": "class", "name": "Customer", "in": "domain", "left": 200, "top": 224}
|
|
120
|
+
],
|
|
121
|
+
"relations": [
|
|
122
|
+
{"kind": "dependency", "from": "web", "to": "domain", "stereotype": "use"},
|
|
123
|
+
{"kind": "association", "from": "Order", "to": "Customer", "name": "places", "to_multiplicity": "1"}
|
|
124
|
+
]
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
It gets back the same things as the class diagram tool, with the place of every element (and, for a package, the
|
|
129
|
+
point its lines aim at, since that is not the middle of the package). Besides the class diagram
|
|
130
|
+
checks, the check fails when an element inside another sits too close to its edge or name tab, or a line runs along
|
|
131
|
+
the edge of a package it starts or ends in, or through a package's name tab.
|
|
132
|
+
|
|
133
|
+
Components and artifacts can also be drawn in icon notation. `component_icon` is the UML 1 component: a box with two
|
|
134
|
+
small rectangles across its left edge, which lines may not cross. `artifact_icon` is a folded-page icon with the name
|
|
135
|
+
(often a file name) outside it, on the side `name_side` gives.
|
|
136
|
+
|
|
137
|
+
### Component diagrams
|
|
138
|
+
|
|
139
|
+
The tool is `draw_component_diagram`. It draws components with the interfaces they provide, the artifacts that
|
|
140
|
+
implement them, and the classes that realize them. It takes every element of the package diagram tool (icon notations included), plus
|
|
141
|
+
`lollipop`: a provided interface drawn as a small circle with its name outside (`name_side` puts the name below,
|
|
142
|
+
above, left or right of the circle). The providing component joins the circle with an `association`, drawn without
|
|
143
|
+
an arrowhead in this tool unless `navigable` is given, and each user points at the circle with a `dependency`:
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"file_name": "components",
|
|
148
|
+
"elements": [
|
|
149
|
+
{"kind": "package", "name": "web", "left": 0, "top": 0},
|
|
150
|
+
{"kind": "component", "name": "OrderController", "in": "web", "left": 20, "top": 44},
|
|
151
|
+
{"kind": "component", "name": "AdminController", "in": "web", "left": 220, "top": 44},
|
|
152
|
+
{"kind": "package", "name": "service", "left": 0, "top": 220},
|
|
153
|
+
{"kind": "component", "name": "OrderService", "in": "service", "left": 110, "top": 324},
|
|
154
|
+
{"kind": "lollipop", "name": "OrderApi", "in": "service", "left": 70, "top": 264, "name_side": "left"},
|
|
155
|
+
{"kind": "artifact", "name": "order-service.jar", "left": 400, "top": 324}
|
|
156
|
+
],
|
|
157
|
+
"relations": [
|
|
158
|
+
{"kind": "association", "from": "OrderService", "to": "OrderApi"},
|
|
159
|
+
{"kind": "dependency", "from": "OrderController", "to": "OrderApi"},
|
|
160
|
+
{"kind": "dependency", "from": "AdminController", "to": "OrderApi"},
|
|
161
|
+
{"kind": "dependency", "from": "order-service.jar", "to": "OrderService", "stereotype": "manifest"}
|
|
162
|
+
]
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
It gets back the same things as the package diagram tool, and for each circle the place of the circle alone next to
|
|
167
|
+
the place of the circle with its name. The checks are the same: a line through a circle or its name fails.
|
|
168
|
+
|
|
169
|
+
A user of an interface can also be drawn as a socket. A `requires` relation from the user to the circle is a solid
|
|
170
|
+
line that stops short of the circle and ends in a half circle wrapped around it (ball and socket). Its `to` must be a
|
|
171
|
+
`lollipop` and its `from` must not be one. A circle takes one socket, since two half circles overlap, so any other
|
|
172
|
+
user points at the circle with a `dependency`. A line that touches a half circle fails. With the icon notations,
|
|
173
|
+
the same tool draws a textbook-style picture of UML 1 components and folded-page artifacts:
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{
|
|
177
|
+
"file_name": "billing",
|
|
178
|
+
"elements": [
|
|
179
|
+
{"kind": "artifact_icon", "name": "Billing.exe", "left": 38, "top": 0, "name_side": "right"},
|
|
180
|
+
{"kind": "component_icon", "name": "Billing", "left": 0, "top": 110},
|
|
181
|
+
{"kind": "lollipop", "name": "IBilling", "left": 190, "top": 124},
|
|
182
|
+
{"kind": "component_icon", "name": "Register", "stereotype": "component", "left": 320, "top": 103},
|
|
183
|
+
{"kind": "component_icon", "name": "Course", "left": 0, "top": 260},
|
|
184
|
+
{"kind": "artifact_icon", "name": "Course.dll", "left": 24, "top": 380}
|
|
185
|
+
],
|
|
186
|
+
"relations": [
|
|
187
|
+
{"kind": "dependency", "from": "Billing.exe", "to": "Billing", "stereotype": "manifest"},
|
|
188
|
+
{"kind": "association", "from": "Billing", "to": "IBilling"},
|
|
189
|
+
{"kind": "requires", "from": "Register", "to": "IBilling"},
|
|
190
|
+
{"kind": "dependency", "from": "Register", "to": "Course", "via": [[385, 284]]},
|
|
191
|
+
{"kind": "dependency", "from": "Course.dll", "to": "Course", "stereotype": "manifest"}
|
|
192
|
+
]
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Deployment diagrams
|
|
197
|
+
|
|
198
|
+
The tool is `draw_deployment_diagram`. It shows which computers (nodes) the software runs on: components and
|
|
199
|
+
artifacts sit inside nodes with `in`, and a node can sit inside another node. It takes the same elements as the package
|
|
200
|
+
diagram tool, icon notations included. A communication path between nodes is an `association` with the protocol as its `name`. This tool draws
|
|
201
|
+
every association without an arrowhead (between classes too) unless `navigable` says otherwise. A «deploy» arrow from
|
|
202
|
+
an element outside a node is a `dependency` with `"stereotype": "deploy"`:
|
|
203
|
+
|
|
204
|
+
```json
|
|
205
|
+
{
|
|
206
|
+
"file_name": "deployment",
|
|
207
|
+
"elements": [
|
|
208
|
+
{"kind": "node", "name": "PC", "stereotype": "device", "left": 0, "top": 0, "height": 220},
|
|
209
|
+
{"kind": "component", "name": "Browser", "in": "PC", "left": 20, "top": 66},
|
|
210
|
+
{"kind": "node", "name": "App Server", "stereotype": "device", "left": 240, "top": 0, "height": 220},
|
|
211
|
+
{"kind": "node", "name": "Tomcat", "stereotype": "executionEnvironment", "in": "App Server", "left": 260, "top": 66},
|
|
212
|
+
{"kind": "component", "name": "OrderService", "in": "Tomcat", "left": 280, "top": 132},
|
|
213
|
+
{"kind": "node", "name": "DB Server", "stereotype": "device", "left": 620, "top": 0, "height": 220},
|
|
214
|
+
{"kind": "artifact", "name": "orders.db", "in": "DB Server", "left": 640, "top": 66},
|
|
215
|
+
{"kind": "artifact", "name": "order.war", "left": 310, "top": 280}
|
|
216
|
+
],
|
|
217
|
+
"relations": [
|
|
218
|
+
{"kind": "association", "from": "PC", "to": "App Server", "name": "HTTPS"},
|
|
219
|
+
{"kind": "association", "from": "App Server", "to": "DB Server", "name": "JDBC"},
|
|
220
|
+
{"kind": "dependency", "from": "order.war", "to": "Tomcat", "stereotype": "deploy"}
|
|
221
|
+
]
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
It gets back the same things as the package diagram tool, and the check fails in the same cases, such as a
|
|
226
|
+
communication path running through a node it does not connect or through an element inside one.
|
|
227
|
+
|
|
228
|
+
### Use case diagrams
|
|
229
|
+
|
|
230
|
+
The tool is `draw_use_case_diagram`. It draws actors, use cases and the system boundary, joined by associations,
|
|
231
|
+
«include» and «extend» dependencies, and generalizations. Use cases sit inside the system boundary with `in`. Actors
|
|
232
|
+
stand outside it and write their name beside the figure, on the side `name_side` gives:
|
|
233
|
+
|
|
234
|
+
```json
|
|
235
|
+
{
|
|
236
|
+
"file_name": "use-cases",
|
|
237
|
+
"elements": [
|
|
238
|
+
{"kind": "system", "id": "shop", "name": "Online shop", "left": 160, "top": 0},
|
|
239
|
+
{"kind": "use_case", "name": "Browse items", "in": "shop", "left": 200, "top": 50},
|
|
240
|
+
{"kind": "use_case", "name": "Place order", "in": "shop", "left": 200, "top": 150},
|
|
241
|
+
{"kind": "use_case", "name": "Pay", "in": "shop", "left": 420, "top": 150},
|
|
242
|
+
{"kind": "actor", "name": "Customer", "left": 0, "top": 130, "name_side": "left"},
|
|
243
|
+
{"kind": "actor", "name": "Bank", "left": 660, "top": 157, "name_side": "right"}
|
|
244
|
+
],
|
|
245
|
+
"relations": [
|
|
246
|
+
{"kind": "association", "from": "Customer", "to": "Browse items"},
|
|
247
|
+
{"kind": "association", "from": "Customer", "to": "Place order"},
|
|
248
|
+
{"kind": "dependency", "from": "Place order", "to": "Pay", "stereotype": "include"},
|
|
249
|
+
{"kind": "association", "from": "Pay", "to": "Bank"}
|
|
250
|
+
]
|
|
251
|
+
}
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
It gets back the same things as the package diagram tool. An actor's place covers the figure and its name, and the
|
|
255
|
+
figure's own place comes after it. The check is the same as for package diagrams, and it also fails when a line runs
|
|
256
|
+
through an actor's name or the name at the top of the system boundary. Generalization lines to one parent may share
|
|
257
|
+
one trunk, as inheritance lines do in class diagrams.
|
|
258
|
+
|
|
259
|
+
### State diagrams
|
|
260
|
+
|
|
261
|
+
The tool is `draw_state_diagram`. It draws start and end points, states and choice diamonds joined by transitions. A
|
|
262
|
+
state lists its `entry /`, `do /` and `exit /` lines in `actions`, written as given, and can hold other states with
|
|
263
|
+
`in`. Start and end points and choices have no name, so they get an `id` for transitions to point to. The transition
|
|
264
|
+
`name` is written as given too, brackets and slash included:
|
|
265
|
+
|
|
266
|
+
```json
|
|
267
|
+
{
|
|
268
|
+
"file_name": "order-states",
|
|
269
|
+
"elements": [
|
|
270
|
+
{"kind": "initial", "id": "start", "left": 85, "top": 0},
|
|
271
|
+
{"kind": "state", "name": "Waiting", "left": 25, "top": 60, "width": 140},
|
|
272
|
+
{"kind": "state", "name": "Checking", "left": 25, "top": 180, "width": 140,
|
|
273
|
+
"actions": ["entry / reserve stock", "do / wait for payment"]},
|
|
274
|
+
{"kind": "final", "id": "end", "left": 83, "top": 340}
|
|
275
|
+
],
|
|
276
|
+
"relations": [
|
|
277
|
+
{"from": "start", "to": "Waiting"},
|
|
278
|
+
{"from": "Waiting", "to": "Checking", "name": "order [in stock] / accept"},
|
|
279
|
+
{"from": "Waiting", "to": "Waiting", "name": "tick", "via": [[190, 68], [190, 92]]},
|
|
280
|
+
{"from": "Checking", "to": "end", "name": "paid"}
|
|
281
|
+
]
|
|
282
|
+
}
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
It gets back the same things as the package diagram tool. The check also fails when a line runs through the name and
|
|
286
|
+
actions of a state it starts or ends in, or a label sits on them.
|
|
287
|
+
|
|
288
|
+
### Activity diagrams
|
|
289
|
+
|
|
290
|
+
The tool is `draw_activity_diagram`. It draws start and end points, actions, and decision and merge diamonds joined
|
|
291
|
+
by flows. The guard of a flow out of a decision goes in its `name`, brackets included:
|
|
292
|
+
|
|
293
|
+
```json
|
|
294
|
+
{
|
|
295
|
+
"file_name": "order-flow",
|
|
296
|
+
"elements": [
|
|
297
|
+
{"kind": "initial", "id": "start", "left": 140, "top": 0},
|
|
298
|
+
{"kind": "action", "name": "Take order", "left": 95, "top": 60, "width": 110},
|
|
299
|
+
{"kind": "decision", "id": "stock?", "left": 135, "top": 150},
|
|
300
|
+
{"kind": "action", "name": "Ship", "left": 0, "top": 230},
|
|
301
|
+
{"kind": "action", "name": "Restock", "left": 200, "top": 230},
|
|
302
|
+
{"kind": "merge", "id": "done?", "left": 135, "top": 320},
|
|
303
|
+
{"kind": "final", "id": "end", "left": 138, "top": 400}
|
|
304
|
+
],
|
|
305
|
+
"relations": [
|
|
306
|
+
{"from": "start", "to": "Take order"},
|
|
307
|
+
{"from": "Take order", "to": "stock?"},
|
|
308
|
+
{"from": "stock?", "to": "Ship", "name": "[in stock]", "via": [[45, 165]]},
|
|
309
|
+
{"from": "stock?", "to": "Restock", "name": "[out of stock]", "via": [[245, 165]]},
|
|
310
|
+
{"from": "Ship", "to": "done?", "via": [[45, 335]]},
|
|
311
|
+
{"from": "Restock", "to": "done?", "via": [[245, 335]]},
|
|
312
|
+
{"from": "done?", "to": "end"}
|
|
313
|
+
]
|
|
314
|
+
}
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
It gets back the same things as the package diagram tool, and checks the same way.
|
|
318
|
+
|
|
319
|
+
### Sequence diagrams
|
|
320
|
+
|
|
321
|
+
The tool is `draw_sequence_diagram`. The assistant sends no coordinates: only the participants, the messages in
|
|
322
|
+
order, frames (`loop`, `opt`, `alt`) that cover a range of messages, and `ref` boxes placed before a message.
|
|
323
|
+
cysUML spaces the lifelines to fit the text and draws the activation bars:
|
|
324
|
+
|
|
325
|
+
```json
|
|
326
|
+
{
|
|
327
|
+
"file_name": "checkout",
|
|
328
|
+
"participants": [{"name": "Customer", "kind": "actor"}, {"name": "Shop"}, {"name": "Payment"}],
|
|
329
|
+
"messages": [
|
|
330
|
+
{"from": "Customer", "to": "Shop", "name": "order()"},
|
|
331
|
+
{"from": "Shop", "to": "Payment", "name": "pay(amount)"},
|
|
332
|
+
{"from": "Payment", "to": "Shop", "kind": "reply", "name": "receipt"},
|
|
333
|
+
{"from": "Shop", "to": "Customer", "kind": "reply"}
|
|
334
|
+
],
|
|
335
|
+
"frames": [{"kind": "opt", "first": 1, "last": 2, "condition": "paid by card"}]
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
It gets back the check result, the saved file path, and the picture. As cysUML does the layout, a failed check is a
|
|
340
|
+
cysUML bug. Each finding still says what to change in the input to get around it: the order of participants or
|
|
341
|
+
messages, the messages a frame covers, shorter text, or splitting the diagram.
|
|
342
|
+
|
|
343
|
+
### All tools
|
|
344
|
+
|
|
345
|
+
- **Saved to** `out_dir`, or `diagrams/` under the server's working folder when `out_dir` is not given. The same
|
|
346
|
+
`file_name` overwrites the file. Some clients start servers in a folder you can't write to (such as `/`); the tool
|
|
347
|
+
then answers with an error, and the assistant should pass an `out_dir`.
|
|
348
|
+
- **Returned picture** is shrunk to 1568 px on its long side when it is bigger. The saved file keeps its full size.
|
|
349
|
+
|
|
350
|
+
The full input format is in the tool descriptions, which your client hands to the assistant.
|
|
351
|
+
|
|
352
|
+
## Develop
|
|
353
|
+
|
|
354
|
+
```
|
|
355
|
+
uv sync
|
|
356
|
+
uv run pytest
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
To try your working copy in Claude Code, register it under another name:
|
|
360
|
+
|
|
361
|
+
```
|
|
362
|
+
claude mcp add cysuml-dev -- uv run --directory /path/to/cysUML cysuml
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
To try the latest `main` before it is released, use `uvx --from git+https://github.com/yschoi9733/cysUML cysuml`.
|
|
366
|
+
|
|
367
|
+
## License
|
|
368
|
+
|
|
369
|
+
cysUML is under the [MIT License](https://github.com/yschoi9733/cysUML/blob/main/LICENSE). The bundled fonts are
|
|
370
|
+
Liberation Sans and Noto Sans KR, both under the SIL Open Font License 1.1 (see
|
|
371
|
+
[`LiberationSans-LICENSE.txt`](https://github.com/yschoi9733/cysUML/blob/main/src/cysuml/fonts/LiberationSans-LICENSE.txt)
|
|
372
|
+
and [`NotoSansKR-LICENSE.txt`](https://github.com/yschoi9733/cysUML/blob/main/src/cysuml/fonts/NotoSansKR-LICENSE.txt)).
|
|
373
|
+
|
|
374
|
+
---
|
|
375
|
+
|
|
376
|
+
## 한국어
|
|
377
|
+
|
|
378
|
+
AI가 배치하고 도구가 그리는, 문서용 UML 그림 MCP 서버다.
|
|
379
|
+
|
|
380
|
+
자동 배치 도구는 빠르지만 선이 상자나 글자를 가로지르기 쉽고, 손으로 다듬기도 어렵다. cysUML은 반대로 간다. AI 어시스턴트가
|
|
381
|
+
상자 자리를 정하면 cysUML은 그대로 그리고 그림을 검사한다. 선이 상자나 글자를 지나면 불합격이고, 무엇을 옮길지 알려 준다.
|
|
382
|
+
어시스턴트는 배치를 고쳐 합격할 때까지 다시 그린다.
|
|
383
|
+
|
|
384
|
+
- 여러 UML 그림을 그린다(목록은 아래 [쓰기](#쓰기)). 교류도는 참여자·메시지 차례를 받아 cysUML이 배치하고, 똑같이 검사한다.
|
|
385
|
+
- PNG로 낸다. 글꼴을 함께 넣어 어느 컴퓨터에서든 같은 그림이 나오고, 한글도 그린다.
|
|
386
|
+
|
|
387
|
+
### 설치
|
|
388
|
+
|
|
389
|
+
[uv](https://docs.astral.sh/uv/)가 있어야 한다. 아래 한 줄이 [PyPI](https://pypi.org/project/cysuml/)에서 cysUML을 받아
|
|
390
|
+
서버를 띄운다:
|
|
391
|
+
|
|
392
|
+
```
|
|
393
|
+
uvx cysuml
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
표준 입출력으로 MCP를 주고받으므로 혼자 띄우면 클라이언트를 기다리기만 한다. 쓰려면 MCP 클라이언트에 등록한다.
|
|
397
|
+
|
|
398
|
+
- **Claude Code:** `claude mcp add cysuml -- uvx cysuml`
|
|
399
|
+
- **다른 클라이언트:** 위 영어 안내의 JSON 설정에 같은 명령을 넣는다.
|
|
400
|
+
- **버전:** `uvx cysuml`은 가장 새 버전을 띄운다. 클라이언트가 서버를 띄울 때마다 uv가 PyPI에 묻고, 받은 답은 10분까지 다시
|
|
401
|
+
쓴다. `uv tool install cysuml`로 설치해 두었으면 uvx는 그 설치본을 띄우니 `uv tool upgrade cysuml`로 올린다. 한 버전에
|
|
402
|
+
머물려면 이름 뒤에 버전을 붙인다 — `uvx cysuml@0.1.0`(JSON에서는 `"args": ["cysuml@0.1.0"]`). 나온 버전은
|
|
403
|
+
[PyPI 릴리스 기록](https://pypi.org/project/cysuml/#history)에 있다.
|
|
404
|
+
|
|
405
|
+
### 쓰기
|
|
406
|
+
|
|
407
|
+
어시스턴트에게 "cysUML로 주문 도메인 클래스도를 그려 줘"나 "결제 흐름을 cysUML 교류도로 그려 줘"처럼 부탁한다. 배치 요령은
|
|
408
|
+
서버가 어시스턴트에게 알려 준다.
|
|
409
|
+
|
|
410
|
+
- **클래스도**는 `draw_class_diagram`으로 그린다. 어시스턴트가 상자의 왼쪽 위 자리와, 필요하면 관계선의 꺾는 점을 준다. 결과로
|
|
411
|
+
검사 결과, 상자마다 그린 자리와 크기, 저장한 파일 경로, 그림을 돌려준다. 상자끼리 겹치거나, 선이 상자·글자·다른 선의 화살촉을
|
|
412
|
+
지나거나, 글자끼리 겹치면 불합격이다. 선끼리 엇갈린 곳과 그림 크기는 알려 주기만 하고 불합격이 아니다. 같은 부모로 가는
|
|
413
|
+
상속끼리, 실체화끼리는 여러 선을 한 줄기로 모아 삼각형 하나를 함께 써도 된다(꺾는 점을 주는 법은 도구 설명에 있다). 관계는
|
|
414
|
+
UML 표기를 따라야 하고, 어기면 그리지 않고 입력 오류로 돌려준다 — 상속은 같은 종류끼리(클래스와 추상 클래스는 같은 종류)
|
|
415
|
+
긋고, 고리를 이루거나 자기 자신으로 가는 상속·실체화는 받지 않는다. 인터페이스가 하는 실체화와 인터페이스가 아닌 것으로 가는
|
|
416
|
+
실체화는 그리되 알림을 준다. 패키지도·컴포넌트도·배치도(deployment diagram)도 같은 규칙을 쓴다. 거기서 패키지와 제공
|
|
417
|
+
인터페이스 원은 상속의 끝이 될 수 없고, 둘이 하는 실체화에는 알림을 주며, 클래스가 컴포넌트를 실현하는 실체화에는 알림을 주지
|
|
418
|
+
않는다. 아이콘 표기 컴포넌트·아티팩트는 기본 표기와 같은 종류로 친다.
|
|
419
|
+
- **패키지도**는 `draw_package_diagram`으로 그린다. 패키지와 패키지 사이 의존을 그리고, 패키지 안에 클래스·패키지를 넣는다.
|
|
420
|
+
컴포넌트·아티팩트·노드도 한 그림에 함께 그린다. 요소마다 `kind`를 주고, 다른 요소 안에 둘 요소는 `in`으로 품은 요소를
|
|
421
|
+
가리킨다 — 바깥 요소는 안의 요소를 덮도록 오른쪽·아래로 늘어난다. 결과는 클래스도와 같고 요소마다 그린 자리를 돌려준다(패키지는
|
|
422
|
+
선이 가운데가 아니라 탭 오른쪽 몸통의 가운데를 향하므로 그 점도 함께).
|
|
423
|
+
클래스도 검사에 더해, 안의 요소가 바깥 요소의 테두리·이름 탭에 붙거나, 선이 그 끝을 품은 패키지의 테두리를 따라가거나 패키지
|
|
424
|
+
탭을 지나면 불합격이다. 컴포넌트·아티팩트는 아이콘 표기로도 그린다 — `component_icon`은 왼쪽 변에 작은 네모 둘이 걸친 UML 1
|
|
425
|
+
표기 컴포넌트(선이 네모를 지나면 불합격), `artifact_icon`은 귀 접힌 문서 아이콘과 그 밖(`name_side`)에 쓰는 이름이다.
|
|
426
|
+
- **컴포넌트도**는 `draw_component_diagram`으로 그린다. 컴포넌트와 제공 인터페이스, 컴포넌트를 구현하는 아티팩트, 컴포넌트를
|
|
427
|
+
실현하는 클래스를 그린다. 패키지도 도구가 받는 요소(아이콘 표기 포함)에 더해 `lollipop`(제공 인터페이스 원 — 작은 원과 그 밖에 쓰는
|
|
428
|
+
이름으로 그린다. 이름 쪽은 `name_side`)을 받는다. 제공하는 컴포넌트는 원과 `association`으로 잇고(이 도구에서는 `navigable`을
|
|
429
|
+
주지 않으면 화살촉이 없다), 쓰는 쪽은 원으로 `dependency`를 긋는다. 결과는 패키지도와 같고, 원마다 원만의 자리도 함께
|
|
430
|
+
돌려준다. 검사도 같고, 선이 원이나 그 이름을 지나면 불합격이다. 쓰는 쪽은 소켓으로도 그린다 — 쓰는 쪽에서 원으로
|
|
431
|
+
`requires`를 그으면 실선이 원 앞에서 멈추고 그 끝에 원을 감싸는 반원이 붙는다. `to`는 원이어야 하고 `from`은 원이 아니어야
|
|
432
|
+
한다. 한 원에 소켓은 하나이고(반원 둘은 겹친다), 다른 쓰는 쪽은 `dependency`로 원을 가리킨다. 반원에 닿는 선은 불합격이다.
|
|
433
|
+
아이콘 표기 컴포넌트·아티팩트와 소켓을 함께 쓴 그림이 위 영어 절의 `billing` 예시다.
|
|
434
|
+
- **배치도**(deployment diagram)는 `draw_deployment_diagram`으로 그린다. 소프트웨어(컴포넌트·아티팩트)가 어느 컴퓨터(노드)에서
|
|
435
|
+
도는지 보인다. 노드 안에 컴포넌트·아티팩트·노드를 `in`으로 넣고, 노드끼리는 통신 경로(`association` — `name`에 HTTPS 같은
|
|
436
|
+
프로토콜)로 잇고, 노드 밖 요소에서 노드로 «deploy»(`stereotype`이 `deploy`인 `dependency`)를 긋는다. 이 도구는 클래스끼리
|
|
437
|
+
이은 것까지 모든 연관을 화살촉 없는 실선으로 그린다(필요하면 `navigable`을 준다). 받는 요소(아이콘 표기 포함)·결과·검사는 패키지도와 같다.
|
|
438
|
+
- **유즈케이스도**는 `draw_use_case_diagram`으로 그린다. 액터·유즈케이스·시스템 경계를 그리고, 연관·의존(«include»·«extend»)·
|
|
439
|
+
일반화로 잇는다. 유즈케이스는 `in`으로 시스템 경계 안에 넣고, 액터는 경계 밖에 두어 이름을 사람 모양 옆(`name_side`가 정한
|
|
440
|
+
쪽)에 쓴다. 결과는 패키지도와 같고, 액터는 이름까지 덮는 자리 뒤에 사람 모양 자리를 함께 돌려준다. 검사는 패키지도와 같고,
|
|
441
|
+
선이 액터 이름이나 시스템 경계 이름을 지나도 불합격이다. 같은 부모로 가는 일반화 선은 클래스도의 상속처럼 한 줄기로 모아도 된다.
|
|
442
|
+
- **상태도**는 `draw_state_diagram`으로 그린다. 시작·끝 점, 상태, 선택 마름모를 전이로 잇는다. 상태의 `entry /`·`do /`·`exit /`
|
|
443
|
+
줄은 `actions`에 주면 받은 그대로 쓰고, 상태 안에 상태를 넣을 때는 `in`으로 품은 상태를 가리킨다. 이름이 없는 시작·끝 점과
|
|
444
|
+
선택은 `id`를 주어 전이가 가리키게 한다. 전이 글자(`name`)도 대괄호·빗금까지 받은 그대로 쓴다. 결과는 패키지도와 같다. 선이 그
|
|
445
|
+
끝을 품은 상태의 이름·동작 칸을 지나거나 전이 글자가 그 칸에 겹쳐도 불합격이다.
|
|
446
|
+
- **액티비티도**는 `draw_activity_diagram`으로 그린다. 시작·끝 점, 행동, 결정·합류 마름모를 흐름으로 잇는다. 결정에서 나가는
|
|
447
|
+
흐름의 조건은 `name`에 대괄호까지 쓴다. 결과와 검사는 패키지도와 같다.
|
|
448
|
+
- **교류도**는 `draw_sequence_diagram`으로 그린다. 어시스턴트는 좌표 없이 참여자, 메시지 차례, 메시지 범위를 덮는
|
|
449
|
+
프레임(`loop`·`opt`·`alt`), 메시지 앞에 놓는 `ref`만 준다. cysUML이 글자에 맞춰 생명선을 띄우고 활성 막대를 그린다. 결과로 검사 결과, 저장한
|
|
450
|
+
파일 경로, 그림을 돌려준다. 배치를 cysUML이 하므로 불합격은 cysUML의 버그다. 그래도 항목마다 입력에서 무엇을 바꾸면
|
|
451
|
+
비켜 가는지(참여자·메시지 차례, 프레임이 덮는 범위, 글자 줄이기, 그림 나누기) 알려 준다.
|
|
452
|
+
- 입력 형식 전체는 도구 설명에 있어 클라이언트가 어시스턴트에게 넘긴다.
|
|
453
|
+
- 그림은 `out_dir`에, 없으면 서버 작업 폴더 아래 `diagrams/`에 저장한다. 같은 `file_name`이면 덮어쓴다. 쓸 수 없는 폴더(`/` 등)에서
|
|
454
|
+
서버를 띄우는 클라이언트도 있는데, 그때는 도구가 오류로 알리므로 `out_dir`을 주면 된다.
|
|
455
|
+
- 돌려주는 그림은 긴 변이 1568px를 넘으면 그 길이로 줄인다. 저장한 파일은 원래 크기다.
|
|
456
|
+
|
|
457
|
+
### 개발
|
|
458
|
+
|
|
459
|
+
`uv sync`로 준비하고 `uv run pytest`로 시험한다. 작업 중인 코드를 Claude Code에서 써 보려면 다른 이름으로 등록한다:
|
|
460
|
+
`claude mcp add cysuml-dev -- uv run --directory /path/to/cysUML cysuml`. 아직 배포하지 않은 `main`의 최신 코드를 써 보려면
|
|
461
|
+
`uvx --from git+https://github.com/yschoi9733/cysUML cysuml`로 띄운다.
|
|
462
|
+
|
|
463
|
+
### 라이선스
|
|
464
|
+
|
|
465
|
+
cysUML은 [MIT 라이선스](https://github.com/yschoi9733/cysUML/blob/main/LICENSE)를 따른다. 함께 넣은 글꼴 Liberation Sans와
|
|
466
|
+
Noto Sans KR은 SIL Open Font License 1.1을 따른다([`src/cysuml/fonts`](https://github.com/yschoi9733/cysUML/tree/main/src/cysuml/fonts)).
|