You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -67,6 +72,8 @@ Concern texts are normalized (strip, lowercase, collapse whitespace) and hashed
67
72
3.`get_viewpoint_concepts(...)` → full concept details (~3 KB, only when model decides it needs them)
68
73
4.`get_concept("Operational Context Role")` → specific concept deep-dive (~1 KB)
69
74
5.`get_viewpoint_concerns(...)` → concerns with rationales (~2 KB)
75
+
6.`get_concept_stereotypes("Conceptual System Context")` → what stereotypes realize this concept (~0.5 KB)
76
+
7.`get_stereotype("SAF_ConceptualSystem")` → drill into stereotype details (~1 KB)
70
77
71
78
vs monolithic: step 1 alone returns 5-15 KB regardless of what the model needs.
72
79
@@ -134,6 +141,89 @@ Returns a stakeholder's full profile: documentation, and all their concerns with
134
141
135
142
Returns a concern's details: the question it frames, its owner, and which viewpoints address it.
136
143
144
+
### 12. `get_stereotype`
145
+
146
+
Returns a stereotype's full details: documentation, which SAF concepts it realizes, and which special implementations (typing, containment, attribute) involve it. Use this to drill into a specific stereotype. To trace from a concept forward, use `get_concept_stereotypes`.
147
+
148
+
```json
149
+
{
150
+
"name": "SAF_ConceptualSystem",
151
+
"id": "_19_0_1_26f0132_...",
152
+
"documentation": "...",
153
+
"realized_concepts": [
154
+
{
155
+
"concept_name": "Conceptual System",
156
+
"concept_id": "...",
157
+
"concept_type": "Class",
158
+
"concept_documentation": "..."
159
+
}
160
+
]
161
+
}
162
+
```
163
+
164
+
### 13. `get_concept_stereotypes`
165
+
166
+
Returns all stereotypes that realize a given SAF concept — including both **direct realizations** (from `realizeconcept.json`) and **indirect UML metaclass mappings** via special implementations (SCM_TypedBy, SCM_ContainedIn, SCM_Attribute). This is the single entry point for full concept→stereotype→UML traceability. Use `get_stereotype` to drill into a specific stereotype for full detail.
Lists all stereotypes with their name and the concepts they realize. Useful for browsing the full catalog.
207
+
208
+
### 15. `get_special_implementations`
209
+
210
+
Returns special implementation relations (`SCM_TypedBy`, `SCM_ContainedIn`, `SCM_Attribute`) that link UML/SysML metaclasses to SAF stereotypes. Optionally filter by `stereotype_name` to see all special implementations involving a specific stereotype (as client or supplier). Use this to understand how UML/SysML elements are mapped to SAF stereotypes at the metamodel level.
**Deciders:** SAF designer, MCP server implementer
6
+
7
+
## Context
8
+
9
+
The SAF ontology MCP server exposes tools that let an LLM query the relationship between abstract SAF concepts and their UML/SysML stereotype implementations. This traceability spans two data sources:
10
+
11
+
1.**realizeconcept.json** — Direct mapping: `SAF Concept → SAF Stereotype` (e.g., `Conceptual Exchange Type → SAF_ConceptualExchangeType`).
12
+
2.**special-implementations.json** — Metamodel-level relations (`SCM_TypedBy`, `SCM_ContainedIn`, `SCM_Attribute`) linking UML/SysML metaclasses (e.g., `FlowProperty`, `ProxyPort`) to SAF stereotypes.
13
+
14
+
A third data source, **stereotypes.json**, provides documentation for each stereotype but does not encode traceability edges itself.
15
+
16
+
An LLM in a fresh session cannot know, without being told, that it needs to:
17
+
18
+
- Call `get_concept_stereotypes` for direct realizations.
19
+
- Call `get_special_implementations` for indirect UML-metaclass links.
20
+
- Then mentally join the two results to see the full picture.
21
+
- Interpret generic terms like "client" and "supplier" differently depending on the relation stereotype.
22
+
23
+
## Decision
24
+
25
+
We will merge the two traceability paths into a single tool output and use semantically transparent role labels.
26
+
27
+
### 1. Single entry point for traceability
28
+
29
+
`get_concept_stereotypes` returns **both**:
30
+
- Direct `realizeconcept.json` realizations (stereotype → concept).
The `get_special_implementations` tool (retained as a secondary filter) uses the same labels.
69
+
70
+
### 3. Cross-reference hints in tool descriptions
71
+
72
+
Every tool description explicitly mentions the chain so an LLM can navigate:
73
+
74
+
-`get_concept_stereotypes`: "Returns both direct stereotype realizations and indirect UML metaclass mappings via special implementations. Each entry includes `realized_concepts` and `special_implementations` (SCM_TypedBy, SCM_ContainedIn, SCM_Attribute). Use `get_stereotype` to drill into a specific stereotype for full detail."
75
+
-`get_stereotype`: "Shows which concepts this stereotype realizes and which special implementations involve it (as typed_element, container, etc.). To trace from a concept forward, use `get_concept_stereotypes`."
76
+
-`get_special_implementations`: "Filter view of UML↔SAF mapping relations. Typically reached via `get_concept_stereotypes` or `get_stereotype` which already resolve these."
77
+
78
+
## Consequences
79
+
80
+
**Good:**
81
+
- LLM gets the full trace in one call — no manual joining.
82
+
- Role labels are self-documenting; an LLM can read `typed_element: "FlowProperty"` without knowing the special-implementations model.
83
+
- Tool descriptions form a navigable graph; an LLM can discover the chain by reading tool names and descriptions alone.
84
+
- Backward compatible: the old `client`/`supplier` fields are replaced, not appended to, so an LLM always sees the better shape.
85
+
86
+
**Risks:**
87
+
- Increased payload size per `get_concept_stereotypes` call (more data returned). Mitigated by the fact that most SAF concepts have few special-implementations; the 44 entries across all concepts average well under 1 per concept.
88
+
89
+
**Non-goals:**
90
+
- Removing the `get_special_implementations` standalone tool — it remains useful for ad-hoc queries (e.g., "show me all `SCM_ContainedIn` relations involving `StateMachine`").
0 commit comments