@tera-system/core 0.2.8 → 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.
Files changed (32) hide show
  1. package/MANIFEST.json +7 -7
  2. package/RELEASES.md +37 -0
  3. package/agents/domain-research-agent.md +25 -4
  4. package/assets/architecture/README.md +30 -0
  5. package/assets/structurizr-mcp/README.md +134 -0
  6. package/assets/structurizr-mcp/pyproject.toml +19 -0
  7. package/assets/structurizr-mcp/src/structurizr_mcp/__init__.py +0 -0
  8. package/assets/structurizr-mcp/src/structurizr_mcp/config.py +59 -0
  9. package/assets/structurizr-mcp/src/structurizr_mcp/server.py +101 -0
  10. package/assets/structurizr-mcp/src/structurizr_mcp/tools/__init__.py +0 -0
  11. package/assets/structurizr-mcp/src/structurizr_mcp/tools/api.py +63 -0
  12. package/assets/structurizr-mcp/src/structurizr_mcp/tools/dsl.py +36 -0
  13. package/assets/structurizr-mcp/src/structurizr_mcp/tools/export.py +258 -0
  14. package/assets/structurizr-mcp/src/structurizr_mcp/tools/validate.py +43 -0
  15. package/assets/structurizr-mcp/uv.lock +770 -0
  16. package/assets/tera-workshop/client-templates/financial/MySign.png +0 -0
  17. package/assets/tera-workshop/client-templates/financial/V1.png +0 -0
  18. package/assets/tera-workshop/client-templates/financial/V2.png +0 -0
  19. package/assets/tera-workshop/client-templates/financial/VOUCHER_DESIGN_SPEC.md +12 -12
  20. package/assets/tera-workshop/client-templates/financial/VOUCHER_HEADER_PROMPT.md +79 -0
  21. package/assets/tera-workshop/client-templates/financial/VOUCHER_PAYMENT_TEMPLATE.html +76 -172
  22. package/assets/tera-workshop/client-templates/financial/VOUCHER_RECEIPT_TEMPLATE.html +76 -175
  23. package/core/tera-system/AGENT_PERMISSION_MODEL.md +13 -3
  24. package/core/tera-system/TERA_DISTRIBUTION_POLICY.md +26 -5
  25. package/core/tera-system/TOOLING_AND_MCP_POLICY.md +22 -0
  26. package/core/tera-system/TeraArchitectureMap.md +2 -1
  27. package/core/tera-system/TeraPolicyMap.md +4 -2
  28. package/core/tera-system/TeraSystemMaintenanceChecklist.md +8 -0
  29. package/core/tera-system/runtime/DOMAIN_INTELLIGENCE_PROTOCOL.md +42 -0
  30. package/opencode.tera.example.json +3 -3
  31. package/package.json +1 -1
  32. 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.8",
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": 32
15
+ "assets": 49
16
16
  },
17
17
  "sha256": {
18
- "agents": "627368c85eb5ab840986b6e8a60b08977803b73c52c698662bc6cc68a1254b7c",
18
+ "agents": "0e4bd044c89ebaf35b35c4ccc838e0565aa1d4a4617293cb46098fa4571349ff",
19
19
  "commands": "a2520ceef3a3f4e9cec2e4c070aeecd41a215ed12438f81d45111e6c801f9ec2",
20
- "core/tera-system": "f4615ea0737c9e0a96810d25a3acc232ec8a928be4ebfc0b2fae0c353129fbd8",
21
- "tools": "1f96a2de662c50c5c0a4c62d27ec583671c690163a0b35add036bfdd2b3a1f1a",
20
+ "core/tera-system": "7e936e3478fc4d3283c910f6a42b629cee6038b87e8e8dc738f59d012b87f927",
21
+ "tools": "86ec41d886f42ae0faf0ee341abf73ab6abd29380c59246dedc47bcdbb1e7358",
22
22
  "core/project-control": "cb979181d50e54c9b9b9173ffc890ca021bfaefe9678b1cad4a2f67ceac3dfdd",
23
- "assets": "fe9adf3e7566c47c14f2a1c44cc9a164bb146e304e0304a9beb3c3727b665c83"
23
+ "assets": "307e660c8156ceda8da5e53460d3f5c82a91c04085dddb648494da57bf8f2072"
24
24
  },
25
- "builtAt": "2026-08-29"
25
+ "builtAt": "2026-08-31"
26
26
  }
package/RELEASES.md CHANGED
@@ -4,6 +4,43 @@
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
+
31
+ ## 0.2.9 (2026-08-29)
32
+
33
+ ### إعادة تصميم محتوى سندات القبض والصرف وتحديث الترويسة
34
+
35
+ **التحديث:**
36
+ - اعتماد بنية المحتوى المعاد تصميمها: بطاقات رقم السند والتاريخ، بطاقات المبلغ كتابةً ورقماً، حقول المرجع والغرض، خيارات الدفع، والتوقيعات.
37
+ - سند واحد فقط في كل ملف HTML.
38
+ - استخدام `V2.png` لسند القبض و`V1.png` لسند الصرف بعرض 210مم.
39
+ - تضمين جميع أصول مجلد `financial` المطلوبة للتثبيت، بما فيها صور الترويسة.
40
+ - تحديث مقاس السند إلى 210×156مم.
41
+
42
+ ---
43
+
7
44
  ## 0.2.8 (2026-08-29)
8
45
 
9
46
  ### سندات القبض والصرف — استخدام شعار Teranoo الرسمي
@@ -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"]
@@ -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()
@@ -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"))]