umtri-mcp 1.4.2 → 1.5.0

package/core/instructions.js

@@ -15,6 +15,6 @@ export const SERVER_INSTRUCTIONS = `Umtri maps a project's structure as a tree (
 
 Umtri never reads git. A commit reaches the ground only because something called create_node / update_node / record_commit — so the tree drifts behind the code unless the repo has a habit that says otherwise. If this repo's own rules file (CLAUDE.md, AGENTS.md, …) has no commit-sync policy, read umtri://rules/commit-sync and offer the human a short one to paste in.
 
-Before creating or reclassifying nodes, read umtri://rules/vocabulary. Opening a season seals the current one, so create_season only acts after the user confirms (umtri://rules/seasons).
+Before creating or reclassifying nodes, read umtri://rules/vocabulary; before creating a trunk or a limb under one, also umtri://rules/trunk-kinds. Opening a season seals the current one, so create_season only acts after the user confirms (umtri://rules/seasons).
 
 If Umtri itself gets in your way — a call rejected for a reason that looks wrong, a capability that is missing, a tool description that misled you — tell the human what happened and offer to file it with send_feedback. Never file it on your own initiative.`;

package/core/policy.js

@@ -24,6 +24,26 @@ const VERB_ENDINGS = ['수정', '적용', '마이그레이션', '분리', '등
 // Trunk naming pattern: <name>-app / <name>-server / single lowercase word (db, www).
 const TRUNK_PATTERN = /^[a-z][a-z0-9-]*(-app|-server|-service|-job|-cdn)$|^[a-z]{2,8}$/;
 
+// Trunk kinds — umtri://rules/trunk-kinds. Recorded in trunk metadata.kind.
+// A trunk that fits none of these keeps kind unset; the agent asks the human whether to
+// suggest a new kind via send_feedback (never files it on its own).
+export const TRUNK_KINDS = ['front', 'server', 'database', 'library', 'device'];
+
+// Suffixes that repeat what the trunk kind already says ("예약 API", "Reservation tables").
+// Matched at the end of a limb label directly under a trunk.
+const KIND_SUFFIX_PATTERN = /(\s|·)?(api|apis|응답|테이블|table|tables|관리|admin|management|endpoints?|엔드포인트)$/i;
+
+// Technical-layer limb names — how code is arranged, not what the system is made of.
+// Whole-label match (after trimming) so "상태 관리 화면" or "Store locator" don't trip it.
+const LAYER_LIMB_LABELS = [
+  'state', 'state management', 'store', 'stores', 'utils', 'util', 'utilities', 'helpers',
+  'hooks', 'routes', 'routing', 'router', 'middleware', 'middlewares', 'models',
+  'services', 'controllers', 'components', 'handlers', 'lib', 'core', 'http routes',
+  'data store', 'app bootstrap', 'bootstrap',
+  '상태 관리', '상태', '유틸', '유틸리티', '헬퍼', '훅', '라우트', '라우팅', '미들웨어',
+  '모델', '서비스', '컨트롤러', '컴포넌트', '핸들러',
+];
+
 // Promotion signals — when a twig's description contains these, it might belong at limb level.
 // Derived from sidebar/auth/ui-system limb promotions on 2026-05-21.
 const PROMOTION_KEYWORDS = [
@@ -100,6 +120,71 @@ export function trunkNamingCheck(type, label) {
   };
 }
 
+// trunk에 kind가 없거나 다섯 유형 밖이면 알린다. 거부하지 않는다 — 기존 나무가 대부분 kind 없이 있다.
+export function trunkKindCheck(type, metadata) {
+  if (type !== 'trunk') return null;
+  const kind = metadata?.kind;
+  const fallback = 'If none of the five fits, leave kind unset, tell the human which trunk did not fit and why, and offer to suggest a new kind with send_feedback (kind "improvement") — do not file it on your own. See umtri://rules/trunk-kinds.';
+  if (kind == null || kind === '') {
+    return {
+      rule: 'trunk-kind-missing',
+      severity: 'info',
+      message: `Trunk has no metadata.kind. Set one of ${TRUNK_KINDS.join(' / ')} — the kind decides how its limbs split. ${fallback}`,
+    };
+  }
+  if (!TRUNK_KINDS.includes(kind)) {
+    return {
+      rule: 'trunk-kind-unknown',
+      severity: 'info',
+      message: `metadata.kind "${kind}" is not one of ${TRUNK_KINDS.join(' / ')}. ${fallback}`,
+    };
+  }
+  return null;
+}
+
+// trunk 바로 아래 limb의 이름 규칙 — 접미사 금지, 레이어 이름 금지, 공통 limb는 하나.
+// parentKind: 부모 trunk의 metadata.kind(없으면 null). siblingCommonCount: 같은 trunk 아래
+// 이 노드를 뺀 metadata.common=true limb 수.
+export function limbUnderTrunkChecks({ type, label, parentType, parentKind, metadata, siblingCommonCount = 0 }) {
+  const out = [];
+  if (type !== 'limb' || parentType !== 'trunk' || !label) return out;
+  const trimmed = label.trim();
+
+  const isLayer = LAYER_LIMB_LABELS.includes(trimmed.toLowerCase());
+  // 레이어 이름("상태 관리")은 접미사 문제가 아니라 축 문제라 layer 경고 하나만 낸다.
+  if (!isLayer && KIND_SUFFIX_PATTERN.test(trimmed) && trimmed.replace(KIND_SUFFIX_PATTERN, '').trim()) {
+    out.push({
+      rule: 'limb-domain-suffix',
+      severity: 'info',
+      message: `Limb "${label}" ends in a kind suffix. Name the domain alone ("${trimmed.replace(KIND_SUFFIX_PATTERN, '').trim()}") and reuse the exact label other trunks use for it — the trunk already says what kind of thing it is. See umtri://rules/trunk-kinds.`,
+    });
+  }
+
+  if (isLayer) {
+    const axis = {
+      front: 'user-facing features or flows (or pages for a public site)',
+      server: 'domains / resources',
+      database: 'domains, named like the server',
+      library: 'capabilities or concepts',
+      device: 'physical parts or screen regions',
+    }[parentKind] ?? "the trunk kind's axis (umtri://rules/trunk-kinds)";
+    out.push({
+      rule: 'limb-layer-axis',
+      severity: 'warn',
+      message: `Limb "${label}" names a technical layer. Split this trunk by ${axis}; put what this would hold into the feature/domain limb it serves, or into the trunk's one common limb.`,
+    });
+  }
+
+  if (metadata?.common === true && siblingCommonCount > 0) {
+    out.push({
+      rule: 'common-limb-duplicate',
+      severity: 'warn',
+      message: 'This trunk already has a common limb (metadata.common=true). Keep one per trunk — make this a twig of that limb, or a real feature/domain limb.',
+    });
+  }
+  return out;
+}
+
 export function leafVsVeinCheck(type, label) {
   if (!label) return null;
   if (type !== 'leaf' && type !== 'vein') return null;
@@ -356,7 +441,7 @@ export function hierarchyCheck(parentType, childType) {
 // phase: 'create' enables dormancy hint (irrelevant on update where children may already exist).
 // siblingLeafCount: # of active leaf siblings already under the resolved parent (for parallel-leaves rule).
 // metadata: this node's metadata (for missing-implements rule).
-export function validateNode({ type, label, parentType, description, metadata, siblingLeafCount, siblingLeafLabels, phase = 'create' }) {
+export function validateNode({ type, label, parentType, parentKind = null, siblingCommonCount = 0, description, metadata, siblingLeafCount, siblingLeafLabels, phase = 'create' }) {
   const warnings = [];
   let rejectReason = null;
 
@@ -366,12 +451,26 @@ export function validateNode({ type, label, parentType, description, metadata, s
     else warnings.push(h);
   }
 
-  const r = reservedDomainCheck(label);
+  let r = reservedDomainCheck(label);
+  // 유형이 정해진 trunk 바로 아래 limb는 도메인 이름이다 — Umtri 자신의 server·db에는 "버그" 도메인이
+  // 있다. 그 코드 영역을 가리키는 거라면 정당하니 info로 낮추고 그 뜻을 말해 준다.
+  if (r?.rule === 'reserved-domain' && type === 'limb' && parentType === 'trunk' && TRUNK_KINDS.includes(parentKind)) {
+    r = {
+      rule: 'reserved-domain',
+      severity: 'info',
+      message: `"${label}" is also a first-class record (bugs/apis/seasons/edges). As a limb under a ${parentKind} trunk it is fine if it names the code that handles that domain — not individual records.`,
+    };
+  }
   if (r) warnings.push(r);
 
   const t = trunkNamingCheck(type, label);
   if (t) warnings.push(t);
 
+  const tk = trunkKindCheck(type, metadata);
+  if (tk) warnings.push(tk);
+
+  warnings.push(...limbUnderTrunkChecks({ type, label, parentType, parentKind, metadata, siblingCommonCount }));
+
   const l = leafVsVeinCheck(type, label);
   if (l) warnings.push(l);
 

package/core/resources/system-structure.md

@@ -79,6 +79,10 @@ users* vs *read by us*.
 - `trunk` = a big domain (e.g. `www`, `server`, `db`). Pick stable,
   long-lived names — usually matching a top-level code area.
 - `limb` = a category inside a trunk (e.g. `graph`, `table`, `dashboard`).
+  How a trunk splits into limbs depends on its kind (`metadata.kind`): features
+  for a front, domains for a server and its database (same names, no suffix),
+  capabilities for a library, parts for a device — one common limb per trunk.
+  See `umtri://rules/trunk-kinds`.
 - Do **not** create one limb per time period. Time is expressed through
   `season` and `created_at`, not by carving the tree into temporal slices.
 - Infrastructure (servers, DNS) is *not* a trunk — it is the environment the
@@ -106,6 +110,8 @@ questions about a ground.
 | `role_change_at`     | type-changed nodes                  | `string` — ISO date                                |
 | `role_change_reason` | type-changed nodes                  | `string` — short prose explaining the shift        |
 | `placeholder`        | intentionally-empty structure       | `true` — opts out of dormant cleanup suggestions   |
+| `kind`               | trunks                              | `front` \| `server` \| `database` \| `library` \| `device` |
+| `common`             | the one shared limb of a trunk      | `true` — see `umtri://rules/trunk-kinds`           |
 
 ## One file, multiple nodes
 

package/core/resources/trunk-kinds.md

@@ -0,0 +1,92 @@
+# Trunk Kinds — How Each Kind of Trunk Branches
+
+Every trunk is one of five kinds, and each kind has its own rule for what its
+limbs are. Recording the kind lets the same domain line up across trunks —
+`Reservations` as a screen area, as endpoints, and as tables — instead of each
+trunk being carved along a different axis.
+
+## Record the kind
+
+Set `metadata.kind` on the trunk. Do not leave it to be guessed from the
+label: the kind is what the MCP reads to check the limbs under it.
+
+| kind | What it is | Limbs split by | The common limb holds | Leaves are |
+| --- | --- | --- | --- | --- |
+| `front` | Something people use on a screen — app, web app, admin, static site | User-facing feature or flow (Reservations, My page). A public site splits by page | App shell (layout, routing, boot), design system, shared components | Screens, components |
+| `server` | A service that takes requests — API, webhooks, jobs | Domain / resource. Non-domain consumers (external integrations, inbound webhooks) get their own limb | Request handling — authentication, authorization, errors, boot | Endpoint groups (`metadata.endpoints`) |
+| `database` | A data store — relational DB, document DB, cache | Domain, **with the same names as the server** | Tables shared by many domains (sessions, audit log) | Tables (`metadata.columns`), labelled by their logical name |
+| `library` | Shared code or a package that other trunks import | Capability or concept (Money, Signal pipeline) | Shared types and constants | Modules |
+| `device` | Physical hardware, an embedded screen, an enclosure | Physical part or screen region | Device-wide parts (power, communication) | Parts, screen elements |
+
+Static sites and admin panels are `front`. A monorepo package that apps import
+is `library`.
+
+### When none of the five fits
+
+Do not force it. Leave `metadata.kind` unset, tell the human which trunk did
+not fit and why, and **offer** to report it with `send_feedback` (kind
+`improvement`) so the kind can be added. Never file that feedback on your own
+initiative — the human decides.
+
+## One common limb per trunk
+
+Each trunk has **at most one** common limb, marked `metadata.common: true`.
+Its name is free (`Common`, `Shell`, `공통`, `요청 처리` …); what it holds is
+defined by the kind (table above). Anything that belongs to no single feature
+or domain goes there — as twigs if it grows.
+
+If a second common limb seems necessary, it is either a real feature/domain
+limb or a twig of the existing common limb.
+
+**Never split a trunk by technical layer.** `State`, `Utils`, `Hooks`,
+`Routes`, `Middleware`, `Store`, `Models`, `Services`, `Components`
+(`상태 관리`, `유틸`, `훅`, `라우트`, `미들웨어`, `모델` …) are how the code is
+arranged, not what the system is made of. Their contents belong in the feature
+or domain limb they serve, or in the common limb.
+
+## Same domain, same name — no suffixes
+
+A domain is named the same in every trunk, without a suffix:
+
+| ✅ | ❌ |
+| --- | --- |
+| `Reservations` (front) · `Reservations` (server) · `Reservations` (database) | `Reservations API`, `Reservation tables`, `Reservation admin` |
+| `예약` · `예약` · `예약` | `예약 API`, `예약 응답`, `예약 테이블`, `예약 관리` |
+
+The trunk already says what kind of thing it is, so a suffix repeats it — and
+suffixes drift (`API` in one ground, `응답` in another), which breaks the
+alignment the shared name is for. An admin `front` names its limbs by the
+resource too: `Members`, not `Member management`.
+
+When adding a limb, look at the other trunks first. If the domain already
+exists there, reuse its exact label.
+
+## Connections between kinds
+
+| From → to | Record as |
+| --- | --- |
+| front screen → server endpoint | api (`create_api`, caller → callee) |
+| server endpoint → database table | edge `data_flow` (writes) or `dependency` (reads) |
+| table → table (foreign key) | edge `dependency` (referencing → referenced) |
+| any trunk → library module | edge `dependency` |
+
+## Warnings
+
+`create_node` and `update_node` never reject on these — they come back in
+`warnings[]`:
+
+| Rule | Meaning |
+| --- | --- |
+| `trunk-kind-missing` | A trunk has no `metadata.kind`. Pick one of the five, or follow "When none of the five fits". |
+| `trunk-kind-unknown` | `metadata.kind` is not one of the five. Same advice. |
+| `limb-domain-suffix` | A limb directly under a trunk ends in a kind suffix (`API`, `응답`, `테이블`, `관리`, `Table(s)`, `Admin`, `Management`). Drop it and reuse the domain name. |
+| `limb-layer-axis` | A limb is named after a technical layer. Split by the trunk kind's axis instead. |
+| `common-limb-duplicate` | The trunk already has a limb with `metadata.common: true`. |
+
+## Reshaping an existing tree
+
+Grounds built before these rules exist. Bring them in line one node at a
+time: set each trunk's `kind`, then rename or regroup limbs with the label
+change visible, recording `reparented_*` when nodes move (see
+`umtri://rules/system-structure`). Ask the human before a large regrouping —
+the shape of their tree is theirs to approve.

package/core/resources/vocabulary-detailed.md

@@ -32,6 +32,10 @@ Domains or feature areas (auth, payments, reservations, dashboard, …) are
 that spans the user-app and admin trunks" — fine. "Authentication is a
 trunk" — no.
 
+Record which of the five kinds the trunk is in `metadata.kind` (`front`,
+`server`, `database`, `library`, `device`). The kind decides how its limbs
+split — see `umtri://rules/trunk-kinds`.
+
 Naming convention (recommended, not enforced):
 - Apps: `<name>-app` (e.g. `user-app`, `kiosk-app`)
 - Servers: `<name>-server` (e.g. `api-server`, `iot-server`)

package/core/resources/vocabulary.md

@@ -24,8 +24,8 @@ guideline; see `umtri://rules/system-structure`.
 
 | Type    | Role      | What it represents                                                 |
 | ------- | --------- | ------------------------------------------------------------------ |
-| `trunk` | structure | A deployable system or independent service (app, server, DB).       |
-| `limb`  | structure | A domain or feature area inside a trunk (auth, payments, dashboard).|
+| `trunk` | structure | A deployable system or independent service (app, server, DB). Carries `metadata.kind` — see `umtri://rules/trunk-kinds`. |
+| `limb`  | structure | A domain or feature area inside a trunk (auth, payments, dashboard) — the axis depends on the trunk's kind. |
 | `twig`  | structure | A cluster of related leaves (a module, a feature group).            |
 | `leaf`  | object    | The thing itself — class, component, screen, entity. Noun phrase.   |
 | `vein`  | action    | A capability the object performs — a method/function that exists now. Verb phrase. NOT a task or a change that was made. |
@@ -172,9 +172,14 @@ If you see one of these in the response, read it before proceeding:
 | `structure-without-children`  | New limb/twig will render dormant until a leaf/vein appears.      |
 | `twig-promotion-candidate`    | Twig description suggests it should be a sibling limb.            |
 | `redundant-child`             | A twig and its only leaf duplicate the same concept.              |
+| `trunk-kind-missing` / `trunk-kind-unknown` | Trunk has no / an unknown `metadata.kind` (front, server, database, library, device). |
+| `limb-domain-suffix`          | Limb under a trunk ends in `API`/`응답`/`테이블`/`관리`… — name the domain alone. |
+| `limb-layer-axis`             | Limb is a technical layer (State, Utils, Routes, Middleware…).     |
+| `common-limb-duplicate`       | The trunk already has its one common limb (`metadata.common`).    |
 
 ## Further reading (read only when relevant)
 
+- `umtri://rules/trunk-kinds` — the five trunk kinds and how each splits into limbs
 - `umtri://rules/system-structure` — metadata key conventions, file→leaf mapping
 - `umtri://rules/vocabulary-detailed` — promotion signals, reclassification
   policy, twig-vs-leaf decision matrix, redundant-child antipattern details

package/core/resources.js

@@ -22,6 +22,13 @@ const RESOURCES = [
     title: 'Umtri vocabulary — detailed guidance',
     description: 'Reclassification policy, twig vs leaf decision matrix, twig promotion signals, redundant-child antipattern, Korean label heuristics. Read only when restructuring an existing tree or wrestling with a borderline classification.',
   },
+  {
+    name: 'trunk-kinds',
+    uri: 'umtri://rules/trunk-kinds',
+    file: 'trunk-kinds.md',
+    title: 'Trunk kinds — how each kind of trunk branches',
+    description: 'Five trunk kinds (front, server, database, library, device) recorded in metadata.kind, the limb axis for each, one common limb per trunk (metadata.common), the same domain name across trunks with no suffix, and how kinds connect. Read before creating a trunk or a limb directly under one, and when restructuring.',
+  },
   {
     name: 'seasons',
     uri: 'umtri://rules/seasons',

package/core/tools.js

@@ -666,6 +666,7 @@ export function registerTools(server, { api }) {
         'parent ∈ existing node id; omit to create a root-level node.',
         'season ∈ existing season id; omit to use the active "now" season. Past seasons are normally rejected, but allowed while the ground is transplanting (project.transplanting=true) — nodes added then are auto-stamped metadata.transplanted=true for audit. See umtri://rules/transplant.',
         'The tool validates against protocol policies. Hierarchy violations are rejected. Soft issues (reserved-domain labels, leaf↔vein heuristic, trunk naming) come back as warnings in the response — reconsider before continuing if warnings appear.',
+        'A trunk carries metadata.kind ∈ front · server · database · library · device, and its limbs follow that kind\'s axis: same domain name across trunks with no suffix ("예약", not "예약 API"), no technical-layer limbs, and at most one common limb (metadata.common=true). Read umtri://rules/trunk-kinds before creating a trunk or a limb under one.',
         'After creating a leaf/vein, consider its connections: if it calls/feeds another node add an api (create_api), if it depends on/is built on another add an edge (create_edge). The response carries a connectionCheck reminder. See umtri://rules/system-structure (Connections).',
         'Do not open a new season just because none fits — attach to the now-season, or ask the user. create_season needs their confirmation (umtri://rules/seasons).',
         'When realizing a human-drawn plan brief, any detail nodes you add should carry metadata.plan=true and the realized node needs metadata.implements — see umtri://rules/plan. A trunk is never plan: metadata.plan on a trunk is rejected.',
@@ -685,19 +686,25 @@ export function registerTools(server, { api }) {
     async ({ slug, type, label, parent, season, description, tags, metadata, sproutedAt }) => {
       try {
         let parentType = null;
+        let parentKind = null;
+        let siblingCommonCount = 0;
         let siblingLeafLabels;
         if (parent) {
           const graph = await api.get(`/api/projects/${encodeURIComponent(slug)}/graph`);
           const parentNode = (graph.nodes || []).find(n => n.id === parent);
           if (!parentNode) throw new Error(`Parent node "${parent}" not found in ground "${slug}".`);
           parentType = parentNode.type;
+          // trunk 유형별 limb 규칙(umtri://rules/trunk-kinds)에 쓰는 부모 kind와 공통 limb 수.
+          parentKind = parentNode.metadata?.kind ?? null;
+          siblingCommonCount = (graph.nodes || [])
+            .filter(n => n.parent === parent && n.type === 'limb' && n.metadata?.common === true).length;
           siblingLeafLabels = (graph.nodes || [])
             .filter(n => n.parent === parent && n.type === 'leaf')
             .map(n => n.label);
         }
 
         const { ok, rejectReason, warnings } = validateNode({
-          type, label, parentType, description, metadata, siblingLeafLabels,
+          type, label, parentType, parentKind, siblingCommonCount, description, metadata, siblingLeafLabels,
         });
         if (!ok) throw new Error(`Rejected by protocol: ${rejectReason}`);
 
@@ -749,7 +756,9 @@ export function registerTools(server, { api }) {
         warnings = warnings.concat(patchResult.warnings);
         warnings = warnings.concat(toolMarkupCheck({ description: patch.description }));
 
-        if (patch.type !== undefined || patch.parent !== undefined || patch.label !== undefined) {
+        // metadata.kind·common이 바뀌면 trunk 유형 경고도 다시 본다.
+        const kindTouched = patch.metadata && ('kind' in patch.metadata || 'common' in patch.metadata);
+        if (patch.type !== undefined || patch.parent !== undefined || patch.label !== undefined || kindTouched) {
           const graph = await api.get(`/api/projects/${encodeURIComponent(slug)}/graph`);
           const current = (graph.nodes || []).find(n => n.id === id);
           if (!current) throw new Error(`Node "${id}" not found in ground "${slug}".`);
@@ -761,14 +770,20 @@ export function registerTools(server, { api }) {
           const newMetadata = patch.metadata !== undefined
             ? Object.fromEntries(Object.entries({ ...(current.metadata || {}), ...patch.metadata }).filter(([, v]) => v !== null))
             : current.metadata;
-          const parentType = newParentId
-            ? (graph.nodes || []).find(n => n.id === newParentId)?.type ?? null
-            : null;
+          const parentNode = newParentId ? (graph.nodes || []).find(n => n.id === newParentId) : null;
+          const parentType = parentNode?.type ?? null;
+          const parentKind = parentNode?.metadata?.kind ?? null;
+          const siblingCommonCount = newParentId
+            ? (graph.nodes || []).filter(n => n.parent === newParentId && n.id !== id
+                && n.type === 'limb' && n.metadata?.common === true).length
+            : 0;
 
           const result = validateNode({
             type: newType,
             label: newLabel,
             parentType,
+            parentKind,
+            siblingCommonCount,
             description: newDescription,
             metadata: newMetadata,
             phase: 'update',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umtri-mcp",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "MCP server for Umtri — give your AI coding agent a persistent map of your project's structure, dependencies, and bugs.",
   "mcpName": "io.umtri/umtri",
   "keywords": [