@tera-system/core 0.2.9 → 0.2.11
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.
- package/MANIFEST.json +7 -7
- package/RELEASES.md +24 -0
- package/agents/domain-research-agent.md +25 -4
- package/assets/architecture/README.md +30 -0
- package/assets/structurizr-mcp/README.md +134 -0
- package/assets/structurizr-mcp/pyproject.toml +19 -0
- package/assets/structurizr-mcp/src/structurizr_mcp/__init__.py +0 -0
- package/assets/structurizr-mcp/src/structurizr_mcp/config.py +59 -0
- package/assets/structurizr-mcp/src/structurizr_mcp/server.py +101 -0
- package/assets/structurizr-mcp/src/structurizr_mcp/tools/__init__.py +0 -0
- package/assets/structurizr-mcp/src/structurizr_mcp/tools/api.py +63 -0
- package/assets/structurizr-mcp/src/structurizr_mcp/tools/dsl.py +36 -0
- package/assets/structurizr-mcp/src/structurizr_mcp/tools/export.py +258 -0
- package/assets/structurizr-mcp/src/structurizr_mcp/tools/validate.py +43 -0
- package/assets/structurizr-mcp/uv.lock +770 -0
- package/core/tera-system/AGENT_PERMISSION_MODEL.md +13 -3
- package/core/tera-system/TERA_DISTRIBUTION_POLICY.md +26 -5
- package/core/tera-system/TOOLING_AND_MCP_POLICY.md +22 -0
- package/core/tera-system/TeraArchitectureMap.md +2 -1
- package/core/tera-system/TeraPolicyMap.md +4 -2
- package/core/tera-system/TeraSystemMaintenanceChecklist.md +8 -0
- package/core/tera-system/runtime/DOMAIN_INTELLIGENCE_PROTOCOL.md +42 -0
- package/opencode.tera.example.json +3 -3
- package/package.json +1 -1
- package/tools/tera-tooling.ps1 +128 -0
package/MANIFEST.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tera-system/core",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.11",
|
|
4
4
|
"description": "Build manifest for the Tera System OpenCode Plugin component.",
|
|
5
5
|
"compatibleEnvironments": [
|
|
6
6
|
"opencode"
|
|
@@ -12,15 +12,15 @@
|
|
|
12
12
|
"coreFiles": 111,
|
|
13
13
|
"tools": 7,
|
|
14
14
|
"projectControlTemplates": 1,
|
|
15
|
-
"assets":
|
|
15
|
+
"assets": 49
|
|
16
16
|
},
|
|
17
17
|
"sha256": {
|
|
18
|
-
"agents": "
|
|
18
|
+
"agents": "0e4bd044c89ebaf35b35c4ccc838e0565aa1d4a4617293cb46098fa4571349ff",
|
|
19
19
|
"commands": "a2520ceef3a3f4e9cec2e4c070aeecd41a215ed12438f81d45111e6c801f9ec2",
|
|
20
|
-
"core/tera-system": "
|
|
21
|
-
"tools": "
|
|
20
|
+
"core/tera-system": "7e936e3478fc4d3283c910f6a42b629cee6038b87e8e8dc738f59d012b87f927",
|
|
21
|
+
"tools": "86ec41d886f42ae0faf0ee341abf73ab6abd29380c59246dedc47bcdbb1e7358",
|
|
22
22
|
"core/project-control": "cb979181d50e54c9b9b9173ffc890ca021bfaefe9678b1cad4a2f67ceac3dfdd",
|
|
23
|
-
"assets": "
|
|
23
|
+
"assets": "307e660c8156ceda8da5e53460d3f5c82a91c04085dddb648494da57bf8f2072"
|
|
24
24
|
},
|
|
25
|
-
"builtAt": "2026-08-
|
|
25
|
+
"builtAt": "2026-08-31"
|
|
26
26
|
}
|
package/RELEASES.md
CHANGED
|
@@ -4,6 +4,30 @@
|
|
|
4
4
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
+
## 0.2.11 (2026-08-31)
|
|
8
|
+
|
|
9
|
+
### Research library + package/website info persistence (SCP-2026-08-31-001/002/003)
|
|
10
|
+
|
|
11
|
+
**ما تغيّر:**
|
|
12
|
+
- **Reusable Research Library (SCP-2026-08-31-001)** — `domain-research-agent` يطبّق Reuse-First (فحص `../Teranoo-Research/00_INDEX.md` قبل أي websearch) + بوابة تقييم إلزامية من 4 أسئلة (Score≥3 → حفظ DRAFT في مستودع `Teranoo-Research` الخاص؛ الترقية DRAFT→READY بيد Majed فقط). المكتبة مستودع خاص مستقل **خارج الحزمة** — لا تُوزَّع.
|
|
13
|
+
- **تثبيت معلومات الحزم والموقع (SCP-2026-08-31-002/003)** — `TERA_DISTRIBUTION_POLICY.md` يوثق الآن: الحزم الرسمية (`@tera-system/core`, `@tera-system/pro`)، المستودع الأصلي `https://github.com/Alabasi1980/Teranoo-System`، مستودع الموقع `https://github.com/Alabasi1980/TeraWebsite`، ولوحة النشر `https://coolify.teranoo.com/`. تصحيح `RepositoryUrl` الخاطئ + تذكير bump في الـ Checklist.
|
|
14
|
+
|
|
15
|
+
## 0.2.10 (2026-08-29)
|
|
16
|
+
|
|
17
|
+
### ضمان الأداة الخماسية في كل مستودع — Tooling Provisioning (SCP-2026-08-29-012)
|
|
18
|
+
|
|
19
|
+
**ما تغيّر:**
|
|
20
|
+
- **`tools/tera-tooling.ps1` جديد** — سكربت تزويد/تحقق موحّد للأدوات الخمس: Playwright (MCP)، Semgrep (MCP+CLI)، Structurizr (MCP)، Gitleaks (CLI)، Trivy (CLI) — وضع Report أو `-Install` (winget/pip/npx) + جدول حالة + exit code
|
|
21
|
+
- **تفعيل Structurizr MCP** في `opencode.tera.example.json` (`enabled: true`) + تصحيح `STRUCTURIZR_WORKSPACE_DIR` → `architecture` (كان `../architecture` خارج المستودع)
|
|
22
|
+
- **شحن `structurizr-mcp/` (12 ملفاً) + `architecture/` (starter)** في الأصول → يُثبَّتان في جذر أي مستودع (assets 36→49)
|
|
23
|
+
- **السياسة §3.6** — المعيار الخماسي + قاعدة: لا `SKIPPED (tool not installed)` صامت بعد التزويد
|
|
24
|
+
|
|
25
|
+
**لماذا هذا التحديث:**
|
|
26
|
+
- الأدوات الخمس معتمدة في البوابات (SEMGREP_SANITY_CHECK، Trivy/Gitleaks قبل التسليم) لكن توفرها كان "إن وُجد" — السكربت يحوّلها إلى مضمونة بأمر واحد
|
|
27
|
+
- Structurizr كان معطلاً لأن خادمه لا يصل للمستودعات — الآن يُشحن مع الحزمة
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
7
31
|
## 0.2.9 (2026-08-29)
|
|
8
32
|
|
|
9
33
|
### إعادة تصميم محتوى سندات القبض والصرف وتحديث الترويسة
|
|
@@ -89,7 +89,8 @@ Before any action, you MUST read and pass:
|
|
|
89
89
|
```text
|
|
90
90
|
[إلزامي] Domain Research Brief — السؤال البحثي والحدود
|
|
91
91
|
[إلزامي] task description — الـ Objective والـ Mode من المستدعي
|
|
92
|
-
[إلزامي] `tera-system/runtime/DOMAIN_INTELLIGENCE_PROTOCOL.md` — القواعد الحاكمة للبحث، No-Guessing Rule، Source Policy
|
|
92
|
+
[إلزامي] `tera-system/runtime/DOMAIN_INTELLIGENCE_PROTOCOL.md` — القواعد الحاكمة للبحث، No-Guessing Rule، Source Policy، Reusable Research Library Protocol
|
|
93
|
+
[إلزامي قبل أي websearch] `../Teranoo-Research/00_INDEX.md` — فحص Reuse-First (إذا المسار غير موجود → تجاوز)
|
|
93
94
|
[حسب الحاجة] PROJECT_RULES.md — عند الحاجة لفهم قواعد المشروع
|
|
94
95
|
[حسب الحاجة] ملفات التحضير المرتبطة بالموديول الحالي
|
|
95
96
|
[حسب الحاجة] Domain Research Reports سابقة — عند طلب تحديث أو توسيع
|
|
@@ -167,9 +168,16 @@ All recommendations are advisory until confirmed by Majed.
|
|
|
167
168
|
| `mode: consulting` أو ذكر "استشاري"، "دراسة"، "consulting" | **Consulting Mode** — يكتب في `client-engagement/`، المخرجات للمستشار |
|
|
168
169
|
| `mode: software` أو لم يذكر mode | **Software Mode** — يكتب في `project-preparation/` أو `project-control/` حسب تعليمات المستدعي |
|
|
169
170
|
|
|
170
|
-
### 6.2 البحث خطوة بخطوة — البحث
|
|
171
|
+
### 6.2 البحث خطوة بخطوة — Reuse-First ثم البحث ثم التقييم
|
|
171
172
|
|
|
172
173
|
```
|
|
174
|
+
الخطوة 0: Reuse-First — افحص المكتبة أولاً (إلزامي)
|
|
175
|
+
← اقرأ ../Teranoo-Research/00_INDEX.md (الفهرس المركزي)
|
|
176
|
+
← إذا وجد بحث مطابق (نفس Topic + Status READY + غير منتهي Expiry + Tier1/2) → استخدمه مباشرة
|
|
177
|
+
← زد ReuseCount في الفهرس (إن أمكن) + سلّم التقرير الموجود للمستدعي
|
|
178
|
+
← إذا لم يوجد أو DEPRECATED أو DRAFT فقط → تابع للخطوة 1
|
|
179
|
+
← إذا المسار غير موجود محلياً → تجاوز الخطوة 0 وتابع للخطوة 1 (لا تفشل)
|
|
180
|
+
|
|
173
181
|
الخطوة 1: افهم السؤال البحثي
|
|
174
182
|
← اقرأ الـ Objective و Domain Research Brief
|
|
175
183
|
← حدد الكلمات المفتاحية للبحث
|
|
@@ -197,6 +205,19 @@ All recommendations are advisory until confirmed by Majed.
|
|
|
197
205
|
← استخدم قالب Domain Research Report
|
|
198
206
|
← كل معلومة تحمل [Research Hint]
|
|
199
207
|
← اكتب في المسار الذي حدده المستدعي (Allowed Write Targets)
|
|
208
|
+
|
|
209
|
+
الخطوة 7: تقييم قابلية إعادة الاستخدام — هل يُحفظ في المكتبة؟ (إلزامي بعد كل بحث)
|
|
210
|
+
← قيّم 4 أسئلة (نعم=1):
|
|
211
|
+
1) قابل للاستخدام في مشروعين مختلفين على الأقل؟
|
|
212
|
+
2) المصادر Tier1 أو Tier2؟
|
|
213
|
+
3) معلومة عامة وليست سر زبون؟
|
|
214
|
+
4) بحث مكتمل (ليس Gap Notice)؟
|
|
215
|
+
← Score ≥3 → احفظ تلقائياً كـ DRAFT في Teranoo-Research/{domain}/YYYY-MM-DD_Topic_TierX.md
|
|
216
|
+
+ استخدم قالب _templates/RESEARCH_ENTRY_TEMPLATE.md
|
|
217
|
+
+ سجل في 00_INDEX.md (Status DRAFT, Expiry +6-12 شهر, Score, ReuseCount 0)
|
|
218
|
+
+ التسمية: YYYY-MM-DD_Topic_TierX.md — التصنيف من قائمة مغلقة في 00_INDEX.md
|
|
219
|
+
+ إذا دومين جديد → ضع وسم [New Domain Proposal] ولا تنشئ مجلداً دون موافقة Majed
|
|
220
|
+
← Score ≤2 → لا تحفظ في المكتبة (يبقى في project-preparation/ فقط)
|
|
200
221
|
```
|
|
201
222
|
|
|
202
223
|
### 6.3 Source Classification — 3 Tiers
|
|
@@ -298,8 +319,8 @@ All recommendations are advisory until confirmed by Majed.
|
|
|
298
319
|
| الصلاحية | القيمة |
|
|
299
320
|
|:---------|:-------|
|
|
300
321
|
| **المستوى الافتراضي** | `READ_ONLY` |
|
|
301
|
-
| **قراءة الملفات** | ✅ جميع ملفات التحضير + التقارير البحثية |
|
|
302
|
-
| **كتابة الملفات** | ✅ Domain Research Report
|
|
322
|
+
| **قراءة الملفات** | ✅ جميع ملفات التحضير + التقارير البحثية + `../Teranoo-Research/00_INDEX.md` (Reuse-First) |
|
|
323
|
+
| **كتابة الملفات** | ✅ Domain Research Report في المسار المحدد + حفظ DRAFT في `../Teranoo-Research/{domain}/` عند Score≥3 |
|
|
303
324
|
| **التحكم (project-control)** | ❌ لا |
|
|
304
325
|
| **كتابة كود** | ❌ لا |
|
|
305
326
|
| **تشغيل شل** | ❌ لا |
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
<!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
|
|
2
|
+
|
|
3
|
+
# architecture/ — نمذجة C4 المعمارية (Structurizr)
|
|
4
|
+
|
|
5
|
+
## الغرض من المجلد
|
|
6
|
+
|
|
7
|
+
هذا المجلد مخصص لنماذج **C4 Architecture** الخاصة بمنظومة Tera نفسها عبر أداة
|
|
8
|
+
[Structurizr](https://structurizr.com) (DSL نصي = مصدر الحقيقة، والرسوم مخرجات مشتقة).
|
|
9
|
+
|
|
10
|
+
- **مصدر الحقيقة للطبقات والبنية:** `tera-system/TeraArchitectureMap.md` (نصي)
|
|
11
|
+
- **أداة النمذجة:** `structurizr-mcp/` (خادم MCP) + أمر Docker في
|
|
12
|
+
`tera-system/TOOLING_AND_MCP_POLICY.md`
|
|
13
|
+
|
|
14
|
+
## الحالة الحالية
|
|
15
|
+
|
|
16
|
+
> **قيد الإنشاء — لا يوجد نموذج C4 حقيقي بعد (2026-08-15).**
|
|
17
|
+
> كانت العيّنة الافتراضية (workspace "Name" "Description") موجودة هنا سابقاً
|
|
18
|
+
> وأُزيلت في SCP-2026-08-15-006 لأنها مضللة — لا تمثل بنية Tera الفعلية.
|
|
19
|
+
> النموذج الحقيقي (Context → Container → Component) يُبنى في جلسة معمارية
|
|
20
|
+
> مخصصة عند الحاجة، بالاعتماد على الطبقات الـ13 في `TeraArchitectureMap.md`.
|
|
21
|
+
|
|
22
|
+
## التشغيل (عند الحاجة)
|
|
23
|
+
|
|
24
|
+
من جذر المستودع (يتطلب Docker + uv):
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
docker run -d --rm -p 8081:8080 -v "%CD%\architecture:/usr/local/structurizr" structurizr/structurizr local
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
ثم فعّل MCP `structurizr` في `.opencode/opencode.json` (`enabled: true`).
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# structurizr-mcp
|
|
2
|
+
|
|
3
|
+
An MCP server that lets Claude read, write, validate, and export [Structurizr](https://structurizr.com) architecture models. Works with the [Structurizr local tool](https://docs.structurizr.com/local) (`structurizr/structurizr`) — the successor to Structurizr Lite.
|
|
4
|
+
|
|
5
|
+
> **Note:** Structurizr Lite (`structurizr/lite`) was discontinued in early 2026. The replacement is the unified `structurizr/structurizr` Docker image run in `local` mode. The DSL is unchanged.
|
|
6
|
+
|
|
7
|
+
**The only runtime dependency is Docker.** Validate and most export formats run via `structurizr/structurizr`. SVG/PNG export additionally uses `mcr.microsoft.com/playwright` to capture diagrams exactly as they appear in the Structurizr web UI — both images are pulled automatically on first use.
|
|
8
|
+
|
|
9
|
+
## What it does
|
|
10
|
+
|
|
11
|
+
| Tool | Description |
|
|
12
|
+
|---|---|
|
|
13
|
+
| `read_dsl` | Read a `.dsl` workspace file |
|
|
14
|
+
| `write_dsl` | Create or update a `.dsl` file |
|
|
15
|
+
| `list_dsl` | List `.dsl` files in a directory |
|
|
16
|
+
| `validate` | Validate a DSL file via Docker |
|
|
17
|
+
| `export` | Export diagrams to Mermaid, SVG, PNG, PlantUML, JSON |
|
|
18
|
+
| `workspace_json` | Fetch the full architecture model from the Structurizr REST API |
|
|
19
|
+
| `structurizr_status` | Check if Structurizr is running |
|
|
20
|
+
|
|
21
|
+
## Prerequisites
|
|
22
|
+
|
|
23
|
+
### 1. Docker
|
|
24
|
+
|
|
25
|
+
Both the Structurizr viewer and the validate/export tools run via Docker. No other tools need to be installed.
|
|
26
|
+
|
|
27
|
+
Start Structurizr pointing at your architecture directory:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
docker run -it --rm -p 8080:8080 \
|
|
31
|
+
-v $PWD/<project-name>:/usr/local/structurizr \
|
|
32
|
+
structurizr/structurizr local
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Open http://localhost:8080 in your browser to view diagrams.
|
|
36
|
+
|
|
37
|
+
> **SVG and PNG exports** require Structurizr to be running and use a Playwright headless browser (`mcr.microsoft.com/playwright`) to capture diagrams exactly as they appear in the web UI. All other export formats (Mermaid, PlantUML, JSON, etc.) work without a running server.
|
|
38
|
+
|
|
39
|
+
### 2. uv
|
|
40
|
+
|
|
41
|
+
Install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Installation
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
git clone https://github.com/ksgit/structurizr-mcp
|
|
51
|
+
cd structurizr-mcp
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
No separate install step — `uv` handles the Python environment automatically on first run.
|
|
55
|
+
|
|
56
|
+
## Connecting to Claude Code
|
|
57
|
+
|
|
58
|
+
Add to your project's `.claude/settings.json` (or your global `~/.claude/settings.json`):
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"mcpServers": {
|
|
63
|
+
"structurizr": {
|
|
64
|
+
"command": "uv",
|
|
65
|
+
"args": ["run", "--directory", "/path/to/structurizr-mcp", "structurizr-mcp"],
|
|
66
|
+
"env": {
|
|
67
|
+
"STRUCTURIZR_WORKSPACE_DIR": "./architecture"
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Replace `/path/to/structurizr-mcp` with the actual path where you cloned this repo,
|
|
75
|
+
and `./architecture` with the path to your Structurizr data directory (the same directory
|
|
76
|
+
you mount into Docker with `-v`).
|
|
77
|
+
|
|
78
|
+
Or use the CLI shortcut:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
claude mcp add structurizr -- uv run --directory /path/to/structurizr-mcp structurizr-mcp
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Configuration
|
|
85
|
+
|
|
86
|
+
All configuration is via environment variables:
|
|
87
|
+
|
|
88
|
+
| Variable | Default | Description |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| `STRUCTURIZR_WORKSPACE_DIR` | `.` | Base directory that bounds all file access (the sandbox root) |
|
|
91
|
+
| `STRUCTURIZR_DEFAULT_WORKSPACE` | _(none)_ | Sub-directory under the base used when a tool call omits `workspace` |
|
|
92
|
+
| `STRUCTURIZR_URL` | `http://localhost:8080` | Structurizr base URL (used for SVG/PNG export and API tools) |
|
|
93
|
+
| `STRUCTURIZR_WORKSPACE_ID` | `1` | Workspace ID (local mode always uses `1`) |
|
|
94
|
+
| `STRUCTURIZR_API_KEY` | _(none)_ | API key for HMAC authentication (optional in local mode) |
|
|
95
|
+
| `STRUCTURIZR_API_SECRET` | _(none)_ | API secret for HMAC authentication (optional in local mode) |
|
|
96
|
+
|
|
97
|
+
Authentication is only required if you have configured API credentials in Structurizr. For local mode with no credentials configured, leave `STRUCTURIZR_API_KEY` and `STRUCTURIZR_API_SECRET` unset.
|
|
98
|
+
|
|
99
|
+
### Multiple workspaces
|
|
100
|
+
|
|
101
|
+
When several Structurizr workspaces live side by side (e.g. `repo/projectA/workspace.dsl` and
|
|
102
|
+
`repo/projectB/workspace.dsl`), point `STRUCTURIZR_WORKSPACE_DIR` at their **common parent** and
|
|
103
|
+
select one per call with the `workspace` argument that `read_dsl`, `write_dsl`, `list_dsl`,
|
|
104
|
+
`validate`, and `export` all accept:
|
|
105
|
+
|
|
106
|
+
```jsonc
|
|
107
|
+
"env": {
|
|
108
|
+
"STRUCTURIZR_WORKSPACE_DIR": "/path/to/repo",
|
|
109
|
+
"STRUCTURIZR_DEFAULT_WORKSPACE": "projectA" // used when `workspace` is omitted
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
- `validate(path="workspace.dsl")` → validates `projectA/workspace.dsl` (the default)
|
|
114
|
+
- `validate(path="workspace.dsl", workspace="projectB")` → validates `projectB/workspace.dsl`
|
|
115
|
+
- `export(path="workspace.dsl", format="svg", output_dir="diagrams/svg", workspace="projectB")`
|
|
116
|
+
writes into `projectB/diagrams/svg/`
|
|
117
|
+
|
|
118
|
+
`path`, `output_dir`, and `workspace` are all resolved under the base and may not escape it.
|
|
119
|
+
For SVG/PNG, the running `structurizr local` container must be serving the same workspace you
|
|
120
|
+
target (its `-v` mount selects which workspace the web UI renders).
|
|
121
|
+
|
|
122
|
+
## Example usage
|
|
123
|
+
|
|
124
|
+
Once connected, you can ask Claude things like:
|
|
125
|
+
|
|
126
|
+
- "Read the current workspace.dsl and explain the architecture"
|
|
127
|
+
- "Add a new microservice called PaymentService to the architecture"
|
|
128
|
+
- "Export all diagrams as SVG and save them to diagrams/svg/"
|
|
129
|
+
- "Validate the workspace and fix any errors"
|
|
130
|
+
- "What containers exist in the current workspace?"
|
|
131
|
+
|
|
132
|
+
## License
|
|
133
|
+
|
|
134
|
+
MIT
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "structurizr-mcp"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "MCP server for Structurizr Lite — read/write DSL, validate, export diagrams"
|
|
9
|
+
requires-python = ">=3.11"
|
|
10
|
+
dependencies = [
|
|
11
|
+
"mcp[cli]>=1.0.0",
|
|
12
|
+
"httpx>=0.27.0",
|
|
13
|
+
]
|
|
14
|
+
|
|
15
|
+
[project.scripts]
|
|
16
|
+
structurizr-mcp = "structurizr_mcp.server:main"
|
|
17
|
+
|
|
18
|
+
[tool.hatch.build.targets.wheel]
|
|
19
|
+
packages = ["src/structurizr_mcp"]
|
|
File without changes
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import hashlib
|
|
2
|
+
import hmac
|
|
3
|
+
import base64
|
|
4
|
+
import os
|
|
5
|
+
import time
|
|
6
|
+
from dataclasses import dataclass, field
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclass
|
|
10
|
+
class Config:
|
|
11
|
+
structurizr_url: str = field(default_factory=lambda: os.environ.get("STRUCTURIZR_URL", "http://localhost:8080"))
|
|
12
|
+
api_key: str | None = field(default_factory=lambda: os.environ.get("STRUCTURIZR_API_KEY"))
|
|
13
|
+
api_secret: str | None = field(default_factory=lambda: os.environ.get("STRUCTURIZR_API_SECRET"))
|
|
14
|
+
workspace_id: str = field(default_factory=lambda: os.environ.get("STRUCTURIZR_WORKSPACE_ID", "1"))
|
|
15
|
+
# Base directory that bounds all file access (the sandbox root). When several workspaces
|
|
16
|
+
# live side by side, point this at their common parent and select one per call via the
|
|
17
|
+
# `workspace` tool argument (or the STRUCTURIZR_DEFAULT_WORKSPACE fallback below).
|
|
18
|
+
workspace_dir: str = field(default_factory=lambda: os.environ.get("STRUCTURIZR_WORKSPACE_DIR", "."))
|
|
19
|
+
# Optional sub-directory under workspace_dir used when a tool call omits `workspace`.
|
|
20
|
+
default_workspace: str | None = field(default_factory=lambda: os.environ.get("STRUCTURIZR_DEFAULT_WORKSPACE") or None)
|
|
21
|
+
|
|
22
|
+
def effective_workspace_dir(self, workspace: str | None = None) -> "Path":
|
|
23
|
+
"""
|
|
24
|
+
Resolve the working directory for a call: workspace_dir / (workspace or default_workspace).
|
|
25
|
+
|
|
26
|
+
Returns workspace_dir itself when neither is set. Raises if the result escapes
|
|
27
|
+
workspace_dir, so a caller can never reach outside the configured base.
|
|
28
|
+
"""
|
|
29
|
+
from pathlib import Path
|
|
30
|
+
base = Path(self.workspace_dir).resolve()
|
|
31
|
+
ws = workspace if workspace is not None else self.default_workspace
|
|
32
|
+
if ws:
|
|
33
|
+
resolved = (base / ws).resolve()
|
|
34
|
+
if not str(resolved).startswith(str(base)):
|
|
35
|
+
raise ValueError(f"Workspace '{ws}' escapes the base directory {base}")
|
|
36
|
+
return resolved
|
|
37
|
+
return base
|
|
38
|
+
|
|
39
|
+
def hmac_headers(self, method: str, path: str, body: bytes = b"") -> dict[str, str]:
|
|
40
|
+
"""
|
|
41
|
+
Build X-Authorization / Nonce headers for the Structurizr vNext REST API.
|
|
42
|
+
Returns an empty dict if no API key is configured (local mode with no auth).
|
|
43
|
+
"""
|
|
44
|
+
if not self.api_key or not self.api_secret:
|
|
45
|
+
return {}
|
|
46
|
+
content_type = "application/json"
|
|
47
|
+
nonce = str(int(time.time() * 1000))
|
|
48
|
+
md5 = hashlib.md5(body).hexdigest()
|
|
49
|
+
message = f"{method}\n{content_type}\n{md5}\n{nonce}\n{path}\n"
|
|
50
|
+
signature = base64.b64encode(
|
|
51
|
+
hmac.new(self.api_secret.encode(), message.encode(), hashlib.sha256).digest()
|
|
52
|
+
).decode()
|
|
53
|
+
return {
|
|
54
|
+
"X-Authorization": f"{self.api_key}:{signature}",
|
|
55
|
+
"Nonce": nonce,
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
config = Config()
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
from mcp.server.fastmcp import FastMCP
|
|
2
|
+
from structurizr_mcp.tools.dsl import read_dsl_file, write_dsl_file, list_dsl_files
|
|
3
|
+
from structurizr_mcp.tools.validate import validate_workspace
|
|
4
|
+
from structurizr_mcp.tools.export import export_diagrams, SUPPORTED_FORMATS
|
|
5
|
+
from structurizr_mcp.tools.api import get_workspace_json, get_structurizr_status
|
|
6
|
+
|
|
7
|
+
mcp = FastMCP("structurizr")
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
@mcp.tool()
|
|
11
|
+
def read_dsl(path: str, workspace: str | None = None) -> str:
|
|
12
|
+
"""
|
|
13
|
+
Read a Structurizr DSL file. Path is relative to the selected workspace.
|
|
14
|
+
`workspace` selects a sub-directory under STRUCTURIZR_WORKSPACE_DIR (defaults to
|
|
15
|
+
STRUCTURIZR_DEFAULT_WORKSPACE, then to the base directory).
|
|
16
|
+
"""
|
|
17
|
+
return read_dsl_file(path, workspace)
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@mcp.tool()
|
|
21
|
+
def write_dsl(path: str, content: str, workspace: str | None = None) -> str:
|
|
22
|
+
"""
|
|
23
|
+
Write or overwrite a Structurizr DSL file. Path is relative to the selected workspace.
|
|
24
|
+
Creates parent directories as needed. Structurizr will pick up the change automatically
|
|
25
|
+
if it is currently running. `workspace` selects a sub-directory under
|
|
26
|
+
STRUCTURIZR_WORKSPACE_DIR (defaults to STRUCTURIZR_DEFAULT_WORKSPACE, then to the base).
|
|
27
|
+
"""
|
|
28
|
+
return write_dsl_file(path, content, workspace)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
@mcp.tool()
|
|
32
|
+
def list_dsl(directory: str = ".", workspace: str | None = None) -> list[str]:
|
|
33
|
+
"""
|
|
34
|
+
List all .dsl files under a directory. Path is relative to the selected workspace.
|
|
35
|
+
Returns paths relative to that workspace. `workspace` selects a sub-directory under
|
|
36
|
+
STRUCTURIZR_WORKSPACE_DIR (defaults to STRUCTURIZR_DEFAULT_WORKSPACE, then to the base).
|
|
37
|
+
"""
|
|
38
|
+
return list_dsl_files(directory, workspace)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@mcp.tool()
|
|
42
|
+
def validate(path: str, workspace: str | None = None) -> dict:
|
|
43
|
+
"""
|
|
44
|
+
Validate a Structurizr DSL file via Docker (structurizr/structurizr validate).
|
|
45
|
+
Returns {valid: bool, errors: [str], output: str}.
|
|
46
|
+
`workspace` selects a sub-directory under STRUCTURIZR_WORKSPACE_DIR (defaults to
|
|
47
|
+
STRUCTURIZR_DEFAULT_WORKSPACE, then to the base directory).
|
|
48
|
+
Requires Docker to be running.
|
|
49
|
+
"""
|
|
50
|
+
return validate_workspace(path, workspace)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
@mcp.tool()
|
|
54
|
+
def export(path: str, format: str = "mermaid", output_dir: str | None = None, workspace: str | None = None) -> dict:
|
|
55
|
+
"""
|
|
56
|
+
Export diagrams from a DSL file via Docker.
|
|
57
|
+
|
|
58
|
+
Args:
|
|
59
|
+
path: Path to the .dsl file (relative to the selected workspace).
|
|
60
|
+
format: Output format. One of: mermaid (default), plantuml, svg, png,
|
|
61
|
+
json, static, websequencediagrams.
|
|
62
|
+
SVG and PNG capture diagrams exactly as they appear in the Structurizr
|
|
63
|
+
web UI using a Playwright headless browser — requires Structurizr to be
|
|
64
|
+
running at STRUCTURIZR_URL and the playwright Docker image to be available.
|
|
65
|
+
All other formats work without a running server.
|
|
66
|
+
output_dir: Where to write exported files (relative to the selected workspace).
|
|
67
|
+
Defaults to the same directory as the DSL file.
|
|
68
|
+
workspace: Sub-directory under STRUCTURIZR_WORKSPACE_DIR to target. Defaults to
|
|
69
|
+
STRUCTURIZR_DEFAULT_WORKSPACE, then to the base directory.
|
|
70
|
+
|
|
71
|
+
Returns {files: [str], output: str}.
|
|
72
|
+
Requires Docker to be running.
|
|
73
|
+
"""
|
|
74
|
+
return export_diagrams(path, format, output_dir, workspace)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
@mcp.tool()
|
|
78
|
+
def workspace_json() -> dict:
|
|
79
|
+
"""
|
|
80
|
+
Fetch the current workspace model from Structurizr's REST API (GET /api/workspace).
|
|
81
|
+
Returns the full architecture model as JSON: all elements, relationships, and views.
|
|
82
|
+
Requires Structurizr to be running (STRUCTURIZR_URL, default http://localhost:8080).
|
|
83
|
+
"""
|
|
84
|
+
return get_workspace_json()
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
@mcp.tool()
|
|
88
|
+
def structurizr_status() -> dict:
|
|
89
|
+
"""
|
|
90
|
+
Check whether Structurizr is reachable at the configured URL.
|
|
91
|
+
Returns {reachable: bool, url: str, message: str}.
|
|
92
|
+
"""
|
|
93
|
+
return get_structurizr_status()
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def main():
|
|
97
|
+
mcp.run()
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
if __name__ == "__main__":
|
|
101
|
+
main()
|
|
File without changes
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import httpx
|
|
2
|
+
from structurizr_mcp.config import config
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
def _workspace_url() -> str:
|
|
6
|
+
return f"{config.structurizr_url.rstrip('/')}/api/workspace/{config.workspace_id}"
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def get_workspace_json() -> dict:
|
|
10
|
+
"""
|
|
11
|
+
Fetch the current workspace model from the Structurizr REST API.
|
|
12
|
+
|
|
13
|
+
Returns the full workspace as a parsed JSON dict, including all elements,
|
|
14
|
+
relationships, and views.
|
|
15
|
+
|
|
16
|
+
Works with structurizr/structurizr (local mode) — the successor to Structurizr Lite.
|
|
17
|
+
"""
|
|
18
|
+
path = f"/api/workspace/{config.workspace_id}"
|
|
19
|
+
headers = config.hmac_headers("GET", path)
|
|
20
|
+
try:
|
|
21
|
+
response = httpx.get(_workspace_url(), headers=headers, timeout=10.0)
|
|
22
|
+
response.raise_for_status()
|
|
23
|
+
return response.json()
|
|
24
|
+
except httpx.ConnectError:
|
|
25
|
+
raise RuntimeError(
|
|
26
|
+
f"Cannot connect to Structurizr at {config.structurizr_url}. "
|
|
27
|
+
"Is the Docker container running? "
|
|
28
|
+
"Start it with: docker run -it --rm -p 8080:8080 "
|
|
29
|
+
"-v $PWD/architecture:/usr/local/structurizr structurizr/structurizr local"
|
|
30
|
+
)
|
|
31
|
+
except httpx.HTTPStatusError as e:
|
|
32
|
+
raise RuntimeError(f"Structurizr API returned {e.response.status_code}: {e.response.text}")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def get_structurizr_status() -> dict:
|
|
36
|
+
"""
|
|
37
|
+
Check whether Structurizr is reachable at the configured URL.
|
|
38
|
+
|
|
39
|
+
Returns a dict with 'reachable' (bool), 'url' (str), and 'message' (str).
|
|
40
|
+
"""
|
|
41
|
+
base_url = config.structurizr_url.rstrip("/")
|
|
42
|
+
path = f"/api/workspace/{config.workspace_id}"
|
|
43
|
+
headers = config.hmac_headers("GET", path)
|
|
44
|
+
try:
|
|
45
|
+
response = httpx.get(f"{base_url}{path}", headers=headers, timeout=5.0)
|
|
46
|
+
reachable = response.status_code < 500
|
|
47
|
+
return {
|
|
48
|
+
"reachable": reachable,
|
|
49
|
+
"url": base_url,
|
|
50
|
+
"message": f"HTTP {response.status_code}",
|
|
51
|
+
}
|
|
52
|
+
except httpx.ConnectError:
|
|
53
|
+
return {
|
|
54
|
+
"reachable": False,
|
|
55
|
+
"url": base_url,
|
|
56
|
+
"message": "Connection refused — is the Docker container running?",
|
|
57
|
+
}
|
|
58
|
+
except httpx.TimeoutException:
|
|
59
|
+
return {
|
|
60
|
+
"reachable": False,
|
|
61
|
+
"url": base_url,
|
|
62
|
+
"message": "Connection timed out",
|
|
63
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
from pathlib import Path
|
|
2
|
+
from structurizr_mcp.config import config
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
def _resolve(path: str, workspace: str | None = None) -> Path:
|
|
6
|
+
"""Resolve path relative to the (optionally workspace-scoped) base; reject traversal attempts."""
|
|
7
|
+
base = config.effective_workspace_dir(workspace)
|
|
8
|
+
resolved = (base / path).resolve()
|
|
9
|
+
if not str(resolved).startswith(str(base)):
|
|
10
|
+
raise ValueError(f"Path '{path}' escapes the workspace directory")
|
|
11
|
+
return resolved
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def read_dsl_file(path: str, workspace: str | None = None) -> str:
|
|
15
|
+
"""Read a Structurizr DSL file and return its contents."""
|
|
16
|
+
resolved = _resolve(path, workspace)
|
|
17
|
+
if not resolved.exists():
|
|
18
|
+
raise FileNotFoundError(f"File not found: {resolved}")
|
|
19
|
+
return resolved.read_text(encoding="utf-8")
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def write_dsl_file(path: str, content: str, workspace: str | None = None) -> str:
|
|
23
|
+
"""Write content to a DSL file, creating parent directories as needed."""
|
|
24
|
+
resolved = _resolve(path, workspace)
|
|
25
|
+
resolved.parent.mkdir(parents=True, exist_ok=True)
|
|
26
|
+
resolved.write_text(content, encoding="utf-8")
|
|
27
|
+
return f"Written to {resolved}"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def list_dsl_files(directory: str = ".", workspace: str | None = None) -> list[str]:
|
|
31
|
+
"""List all .dsl files under a directory (relative to the workspace)."""
|
|
32
|
+
resolved = _resolve(directory, workspace)
|
|
33
|
+
if not resolved.is_dir():
|
|
34
|
+
raise NotADirectoryError(f"Not a directory: {resolved}")
|
|
35
|
+
base = config.effective_workspace_dir(workspace)
|
|
36
|
+
return [str(p.relative_to(base)) for p in sorted(resolved.rglob("*.dsl"))]
|