@likec4/language-server 1.37.0 → 1.38.1

package/dist/mcp/tools/read-deployment.js

@@ -0,0 +1,130 @@
+import { invariant } from "@likec4/core";
+import z from "zod";
+import { likec4Tool } from "../utils.js";
+import { includedInViews, includedInViewsSchema, locationSchema, mkLocate, projectIdSchema } from "./_common.js";
+export const readDeployment = likec4Tool({
+  name: "read-deployment",
+  description: `
+Read details about a deployment node or a deployed instance in a LikeC4 project.
+
+What it does:
+- Returns metadata about a deployment entity (node or instance), including kind, tags, color/shape, children, which views include it, and its source location.
+
+Inputs:
+- id: string \u2014 Deployment id (FQN)
+- project: string (optional, defaults to "default") \u2014 Project id
+
+Output fields:
+- type: "deployment-node" | "deployed-instance"
+- id: string \u2014 Deployment id (FQN)
+- kind: string \u2014 Deployment node kind, or element kind for deployed instances
+- name: string \u2014 Name of the deployment entity
+- title: string \u2014 Title of the deployment entity
+- description: string|null \u2014 Description text
+- technology: string|null \u2014 Technology info, if any
+- tags: string[] \u2014 Tags assigned to this entity
+- project: string \u2014 Project id
+- metadata: Record<string, string>
+- shape: string \u2014 Rendered shape
+- color: string \u2014 Rendered color
+- children: string[] \u2014 Child deployment ids (empty for instances)
+- includedInViews: View[] \u2014 Views that include this entity
+- instanceof: { id: string, title: string, kind: string } | null \u2014 If type is "deployed-instance", the referenced element
+- sourceLocation: { path: string, range: { start: { line: number, character: number }, end: { line: number, character: number } } } | null
+
+View (object) fields:
+- id: string \u2014 view identifier
+- title: string \u2014 view title
+- type: "element" | "deployment" | "dynamic"
+
+Notes:
+- Read-only, idempotent; does not mutate the model.
+
+Example request:
+{ "id": "k8s.cluster.frontend", "project": "default" }
+
+Example response (deployed instance):
+{
+  "type": "deployed-instance",
+  "id": "k8s.cluster.frontend",
+  "kind": "k8s.pod",
+  "name": "frontend",
+  "title": "Frontend Pod",
+  "description": null,
+  "technology": "Kubernetes",
+  "tags": ["prod"],
+  "project": "default",
+  "metadata": {},
+  "shape": "rectangle",
+  "color": "#2F80ED",
+  "children": [],
+  "includedInViews": [
+    { "id": "runtime-overview", "title": "Runtime Overview", "type": "deployment" }
+  ],
+  "instanceof": { "id": "shop.frontend", "title": "Frontend", "kind": "component" },
+  "sourceLocation": {
+    "path": "/abs/path/project/model.c4",
+    "range": { "start": { "line": 10, "character": 0 }, "end": { "line": 25, "character": 0 } }
+  }
+}
+`,
+  annotations: {
+    readOnlyHint: true,
+    idempotentHint: true,
+    title: "Read deployment entity"
+  },
+  inputSchema: {
+    id: z.string().describe("Deployment id (FQN)"),
+    project: projectIdSchema
+  },
+  outputSchema: {
+    type: z.enum(["deployment-node", "deployed-instance"]),
+    id: z.string().describe("Deployment id (FQN)"),
+    kind: z.string().describe("Deployment node kind, or element kind for deployed instances"),
+    name: z.string(),
+    title: z.string(),
+    description: z.string().nullable(),
+    technology: z.string().nullable(),
+    tags: z.array(z.string()),
+    project: z.string(),
+    metadata: z.record(z.string()),
+    shape: z.string(),
+    color: z.string(),
+    children: z.array(z.string()).describe("Children of this deployment node (Array of Deployment ids)"),
+    includedInViews: includedInViewsSchema.describe("Views that include this deployment node"),
+    instanceof: z.object({
+      id: z.string().describe("Element ID (FQN)"),
+      title: z.string(),
+      kind: z.string()
+    }).nullable().describe('If type is "deployed-instance", the referenced element'),
+    sourceLocation: locationSchema
+  }
+}, async (languageServices, args) => {
+  const projectId = languageServices.projectsManager.ensureProjectId(args.project);
+  const model = await languageServices.computedModel(projectId);
+  const element = model.deployment.findElement(args.id);
+  invariant(element, `Deployment entity "${args.id}" not found in project "${projectId}"`);
+  const locate = mkLocate(languageServices, projectId);
+  return {
+    type: element.isInstance() ? "deployed-instance" : "deployment-node",
+    id: element.id,
+    name: element.name,
+    kind: element.kind,
+    title: element.title,
+    description: element.description.text,
+    technology: element.technology,
+    tags: [...element.tags],
+    project: projectId,
+    metadata: element.getMetadata(),
+    shape: element.shape,
+    color: element.color,
+    children: element.isInstance() ? [] : [...element.children()].map((c) => c.id),
+    includedInViews: includedInViews(element.views()),
+    instanceof: element.isInstance() ? {
+      id: element.element.id,
+      title: element.element.title,
+      kind: element.element.kind
+    } : null,
+    sourceLocation: locate({ deployment: element.id })
+  };
+});

package/dist/mcp/tools/read-element.d.ts

@@ -2,9 +2,10 @@ import z from 'zod';
 export declare const readElement: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
     inputSchema?: {
         id: z.ZodString;
-        project: z.ZodOptional<z.ZodString>;
+        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, ProjectId, string>>>;
     } | undefined;
 }, (args: {
-    id: string;
-    project?: string | undefined;
+    [x: string]: any;
+    id?: unknown;
+    project?: unknown;
 }, extra: import("@modelcontextprotocol/sdk/shared/protocol").RequestHandlerExtra<import("@modelcontextprotocol/sdk/types").ServerRequest, import("@modelcontextprotocol/sdk/types").ServerNotification>) => import("@modelcontextprotocol/sdk/types").CallToolResult | Promise<import("@modelcontextprotocol/sdk/types").CallToolResult>];

package/dist/mcp/tools/read-element.js

@@ -1,92 +1,154 @@
 import { invariant } from "@likec4/core";
 import z from "zod";
-import { safeCall } from "../../utils/index.js";
-import { ProjectsManager } from "../../workspace/index.js";
 import { likec4Tool } from "../utils.js";
-import { locationSchema } from "./_common.js";
+import { includedInViews, includedInViewsSchema, locationSchema, mkLocate, projectIdSchema } from "./_common.js";
 export const readElement = likec4Tool({
   name: "read-element",
   description: `
-Returns information about LikeC4 element, includes:
-- id (FQN)
-- parent id (FQN of the parent element, if this element is a nested)
-- kind (element kind)
-- title, description, technology
-- array of assigned tags
-- project name this element belongs to
-- metadata (key-value pairs)
-- shape
-- children (array of ids of the direct children elements)
-- name of the default view of this element if any
-- array of views that include this element
-- element relationships:
-  - incoming and outgoing
-  - direct and indirect (relationships with the nested elements)
-  (relationships include title, kind, description, technology, tags)
-- array of Deployment FQNs that represent deployed instances of this element
-- source location (where the element is defined, if running in the editor)
-`.trimStart(),
+Read detailed information about a LikeC4 element.
+
+Request:
+- id: string \u2014 element id (FQN)
+- project: string (optional) \u2014 project id. Defaults to "default" if omitted.
+
+Response (JSON object):
+- id: string \u2014 element id (FQN)
+- name: string \u2014 element name
+- kind: string \u2014 element kind
+- title: string \u2014 human-readable title
+- description: string|null \u2014 optional description
+- technology: string|null \u2014 optional technology
+- tags: string[] \u2014 assigned tags
+- project: string \u2014 project id this element belongs to
+- metadata: Record<string, string> \u2014 element metadata
+- shape: string \u2014 rendered shape
+- color: string \u2014 rendered color
+- children: string[] \u2014 ids (FQNs) of direct child elements
+- defaultView: string|null \u2014 default view name if set
+- includedInViews: View[] \u2014 views that include this element
+- relationships: object \u2014 relationships of this element (direct and indirect)
+  - incoming: Array<{ source: { id: string, title: string, kind: string }, kind: string|null, target: string, title: string|null, description: string|null, technology: string|null, tags: string[] }>
+  - outgoing: Array<{ source: string, target: { id: string, title: string, kind: string }, kind: string|null, title: string|null, description: string|null, technology: string|null, tags: string[] }>
+- deployedInstances: string[] \u2014 deployed instance ids (Deployment FQNs)
+- sourceLocation: { path: string, range: { start: { line: number, character: number }, end: { line: number, character: number } } } | null \u2014 source location if available
+
+View (object) fields:
+- id: string \u2014 view identifier
+- title: string \u2014 view title
+- type: "element" | "deployment" | "dynamic"
+
+Notes:
+- Read-only, idempotent, no side effects.
+- Safe to call repeatedly.
+
+Example response:
+{
+  "id": "shop.frontend",
+  "name": "frontend",
+  "kind": "container",
+  "title": "Frontend",
+  "description": "User-facing web app",
+  "technology": "React",
+  "tags": ["public"],
+  "project": "default",
+  "metadata": { "owner": "web" },
+  "shape": "rounded-rectangle",
+  "color": "#2F80ED",
+  "children": ["shop.frontend.auth"],
+  "defaultView": "frontend-overview",
+  "includedInViews": [
+    {
+      "id": "frontend-overview",
+      "title": "Frontend Overview",
+      "type": "element"
+    }
+  ],
+  "relationships": {
+    "incoming": [
+      {
+        "source": { "id": "shop.api", "title": "API", "kind": "container" },
+        "kind": "uses",
+        "target": "shop.frontend",
+        "title": "Calls",
+        "description": null,
+        "technology": "HTTPS",
+        "tags": []
+      }
+    ],
+    "outgoing": []
+  },
+  "deployedInstances": ["k8s.cluster.frontend"],
+  "sourceLocation": {
+    "path": "/abs/path/project/model.c4",
+    "range": { "start": { "line": 10, "character": 0 }, "end": { "line": 25, "character": 0 } }
+  }
+}
+`,
   annotations: {
-    readOnlyHint: true
+    readOnlyHint: true,
+    idempotentHint: true,
+    title: "Read element"
   },
   inputSchema: {
     id: z.string().describe("Element id (FQN)"),
-    project: z.string().optional().describe('Project name (optional, will use "default" if not specified)')
+    project: projectIdSchema
   },
   outputSchema: {
     id: z.string().describe("Element id (FQN)"),
     kind: z.string().describe("Element kind"),
     name: z.string().describe("Element name"),
     title: z.string(),
-    description: z.string().nullish(),
-    technology: z.string().nullish(),
+    description: z.string().nullable(),
+    technology: z.string().nullable(),
     tags: z.array(z.string()),
     project: z.string(),
     metadata: z.record(z.string()),
     shape: z.string(),
+    color: z.string(),
     children: z.array(z.string()).describe("Children of this element (Array of FQNs)"),
-    defaultView: z.string().nullish().describe("Name of the default view of this element"),
-    includedInViews: z.array(z.string()).describe("Views that include this element (Array of view names)"),
+    defaultView: z.string().nullable().describe("Name of the default view of this element"),
+    includedInViews: includedInViewsSchema.describe("Views that include this element"),
     relationships: z.object({
       incoming: z.array(z.object({
         source: z.object({
           id: z.string(),
           title: z.string(),
           kind: z.string()
-        }),
-        kind: z.string().nullish().describe("Relationship kind"),
+        }).describe("Source element of this relationship"),
+        kind: z.string().nullable().describe("Relationship kind"),
         target: z.string().describe(
           "Target element id (FQN), either this element or nested element, if relationship is indirect"
         ),
-        title: z.string().nullish().describe("Relationship title"),
-        description: z.string().nullish().describe("Relationship description"),
-        technology: z.string().nullish().describe("Relationship technology"),
+        title: z.string().nullable().describe("Relationship title"),
+        description: z.string().nullable().describe("Relationship description"),
+        technology: z.string().nullable().describe("Relationship technology"),
         tags: z.array(z.string()).describe("Relationship tags")
-      })),
+      })).describe("Incoming relationships of this element (direct and indirect, incoming to nested elements)"),
       outgoing: z.array(z.object({
-        source: z.string().describe("Source element id (FQN), either this element or nested element"),
+        source: z.string().describe(
+          "Source element id (FQN), either this element or nested element, if relationship is indirect"
+        ),
         target: z.object({
           id: z.string(),
           title: z.string(),
           kind: z.string()
-        }),
-        kind: z.string().nullish().describe("Relationship kind"),
-        title: z.string().nullish().describe("Relationship title"),
-        description: z.string().nullish().describe("Relationship description"),
-        technology: z.string().nullish().describe("Relationship technology"),
+        }).describe("Target element of this relationship"),
+        kind: z.string().nullable().describe("Relationship kind"),
+        title: z.string().nullable().describe("Relationship title"),
+        description: z.string().nullable().describe("Relationship description"),
+        technology: z.string().nullable().describe("Relationship technology"),
         tags: z.array(z.string()).describe("Relationship tags")
-      }))
-    }).describe("Relationships of this element (including indirect, incoming/outgoing to/from nested elements)"),
+      })).describe("Outgoing relationships of this element (direct and indirect, outgoing from nested elements)")
+    }).describe("Relationships of this element"),
     deployedInstances: z.array(z.string()).describe("Deployed instances of this element (Array of Deployment FQNs)"),
-    sourceLocation: locationSchema.nullish()
+    sourceLocation: locationSchema
   }
 }, async (languageServices, args) => {
-  const projectId = args.project ?? ProjectsManager.DefaultProjectId;
-  const project = languageServices.projects().find((p) => p.id === projectId);
-  invariant(project, `Project "${projectId}" not found`);
-  const model = await languageServices.computedModel(project.id);
+  const projectId = languageServices.projectsManager.ensureProjectId(args.project);
+  const model = await languageServices.computedModel(projectId);
   const element = model.findElement(args.id);
   invariant(element, `Element "${args.id}" not found in project "${projectId}"`);
+  const locate = mkLocate(languageServices, projectId);
   return {
     id: element.id,
     name: element.name,
@@ -95,12 +157,13 @@ Returns information about LikeC4 element, includes:
     description: element.description.text,
     technology: element.technology,
     tags: [...element.tags],
-    project: project.id,
+    project: projectId,
     metadata: element.getMetadata(),
     shape: element.shape,
+    color: element.color,
     children: [...element.children()].map((c) => c.id),
-    defaultView: element.defaultView?.id,
-    includedInViews: [...element.views()].map((v) => v.id),
+    defaultView: element.defaultView?.id || null,
+    includedInViews: includedInViews(element.views()),
     relationships: {
       incoming: [...element.incoming()].map((r) => ({
         source: {
@@ -130,6 +193,6 @@ Returns information about LikeC4 element, includes:
       }))
     },
     deployedInstances: [...element.deployments()].map((i) => i.id),
-    sourceLocation: safeCall(() => languageServices.locate({ element: element.id, projectId }))
+    sourceLocation: locate({ element: element.id })
   };
 });

package/dist/mcp/tools/read-project-summary.d.ts

@@ -1,8 +1,9 @@
 import z from 'zod';
 export declare const readProjectSummary: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
     inputSchema?: {
-        project: z.ZodOptional<z.ZodString>;
+        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, ProjectId, string>>>;
     } | undefined;
 }, (args: {
-    project?: string | undefined;
+    [x: string]: any;
+    project?: unknown;
 }, extra: import("@modelcontextprotocol/sdk/shared/protocol").RequestHandlerExtra<import("@modelcontextprotocol/sdk/types").ServerRequest, import("@modelcontextprotocol/sdk/types").ServerNotification>) => import("@modelcontextprotocol/sdk/types").CallToolResult | Promise<import("@modelcontextprotocol/sdk/types").CallToolResult>];

package/dist/mcp/tools/read-project-summary.js

@@ -1,32 +1,93 @@
-import { invariant } from "@likec4/core";
 import { keys } from "remeda";
 import z from "zod";
-import { ProjectsManager } from "../../workspace/index.js";
 import { likec4Tool } from "../utils.js";
-import { locationSchema } from "./_common.js";
+import { projectIdSchema } from "./_common.js";
 export const readProjectSummary = likec4Tool({
   name: "read-project-summary",
   annotations: {
-    readOnlyHint: true
+    readOnlyHint: true,
+    idempotentHint: true,
+    title: "Read project summary"
   },
   description: `
-Searches for LikeC4 project by name in workspace and returns its summary:
-- project human readable title
-- project folder
-- array of the source filenames
-- specification:
-  - all element kinds
-  - all relationship kinds
-  - all deployment kinds
-  - all tags (used and unused)
-  - used metadata keys
-- array of the views, where each view:
-  - name
-  - type ("element", "deployment", "dynamic")
-  - title
+Request:
+- project: string (optional) \u2014 project id. Defaults to "default" if omitted.
+
+Response (JSON object):
+- title: string \u2014 human-readable project title
+- folder: string \u2014 absolute path to the project root
+- sources: string[] \u2014 absolute file paths of model documents
+- specification: object
+  - elementKinds: string[] \u2014 all element kinds
+  - relationshipKinds: string[] \u2014 all relationship kinds
+  - deploymentKinds: string[] \u2014 all deployment kinds
+  - tags: string[] \u2014 all tags
+  - metadataKeys: string[] \u2014 used metadata keys
+- elements: Element[] \u2014 list of elements
+- deployments: Deployment[] \u2014 list of deployment entities
+- views: View[] \u2014 list of views defined in the model
+
+Element (object) fields:
+- id: string \u2014 element id (FQN)
+- kind: string \u2014 element kind
+- title: string \u2014 element title
+- tags: string[] \u2014 element tags
+
+Deployment (object) fields:
+- type = "deployment-node": { id: string, kind: string, title: string, tags: string[] }
+- type = "deployed-instance": { id: string, title: string, tags: string[], referencedElementId: string }
+
+View (object) fields:
+- id: string \u2014 view identifier
+- title: string \u2014 view title
+- type: "element" | "deployment" | "dynamic"
+
+Notes:
+- Read-only, idempotent, no side effects.
+- Safe to call repeatedly.
+
+Example response:
+{
+  "title": "Cloud Boutique",
+  "folder": "/abs/path/to/workspace/examples/cloud-system",
+  "sources": [
+    "/abs/path/to/workspace/examples/cloud-system/model.c4"
+  ],
+  "specification": {
+    "elementKinds": ["system", "container", "component"],
+    "relationshipKinds": ["uses", "depends-on"],
+    "deploymentKinds": ["node", "cluster"],
+    "tags": ["public", "internal"],
+    "metadataKeys": ["owner", "tier"]
+  },
+  "elements": [
+    {
+      "id": "shop.frontend",
+      "kind": "component",
+      "title": "Frontend",
+      "tags": ["public"]
+    }
+  ],
+  "deployments": [
+    {
+      "type": "deployment-node",
+      "id": "k8s.shop.frontend",
+      "kind": "cluster",
+      "title": "Frontend",
+      "tags": []
+    }
+  ],
+  "views": [
+    {
+      "name": "system-overview",
+      "title": "System Overview",
+      "type": "element"
+    }
+  ]
+}
   `,
   inputSchema: {
-    project: z.string().optional().describe('Project name (optional, will use "default" if not specified)')
+    project: projectIdSchema
   },
   outputSchema: {
     title: z.string(),
@@ -39,22 +100,43 @@ Searches for LikeC4 project by name in workspace and returns its summary:
       tags: z.array(z.string()),
       metadataKeys: z.array(z.string())
     }),
+    elements: z.array(z.object({
+      id: z.string(),
+      kind: z.string(),
+      title: z.string(),
+      tags: z.array(z.string())
+    })).describe("List of elements in the project"),
+    deployments: z.array(
+      z.discriminatedUnion("type", [
+        z.object({
+          type: z.literal("deployment-node"),
+          id: z.string().describe("Node ID"),
+          kind: z.string().describe("Deployment node kind"),
+          title: z.string().describe("Node title"),
+          tags: z.array(z.string())
+        }),
+        z.object({
+          type: z.literal("deployed-instance"),
+          id: z.string().describe("Node ID"),
+          title: z.string().describe("Node title"),
+          tags: z.array(z.string()),
+          referencedElementId: z.string().describe("Element ID (FQN)")
+        })
+      ])
+    ).describe("List of deployment nodes and deployed instances in the project"),
     views: z.array(z.object({
-      name: z.string(),
-      title: z.string().nullable(),
-      type: z.enum(["element", "deployment", "dynamic"]),
-      sourceLocation: locationSchema.nullish()
+      id: z.string(),
+      title: z.string(),
+      type: z.enum(["element", "deployment", "dynamic"])
     }))
   }
 }, async (languageServices, args) => {
-  const projectId = args.project ?? ProjectsManager.DefaultProjectId;
-  const project = languageServices.projects().find((p) => p.id === projectId);
-  invariant(project, `Project "${projectId}" not found`);
-  const model = await languageServices.computedModel(project.id);
+  const projectId = languageServices.projectsManager.ensureProjectId(args.project);
+  const project = languageServices.project(projectId);
+  const model = await languageServices.computedModel(projectId);
   return {
     title: project.title,
-    folder: project.folder.toString(),
-    sources: project.documents?.map((d) => d.toString()) ?? [],
+    folder: project.folder.fsPath,
     specification: {
       elementKinds: keys(model.specification.elements),
       relationshipKinds: keys(model.specification.relationships),
@@ -62,10 +144,35 @@ Searches for LikeC4 project by name in workspace and returns its summary:
       tags: [...model.tags],
       metadataKeys: model.specification.metadataKeys ?? []
     },
+    elements: [...model.elements()].filter((e) => !e.imported).map((e) => ({
+      id: e.id,
+      kind: e.kind,
+      title: e.title,
+      tags: [...e.tags]
+    })),
+    deployments: [...model.deployment.elements()].map((d) => {
+      if (d.isInstance()) {
+        return {
+          type: "deployed-instance",
+          id: d.id,
+          title: d.title,
+          tags: [...d.tags],
+          referencedElementId: d.element.id
+        };
+      }
+      return {
+        type: "deployment-node",
+        id: d.id,
+        kind: d.kind,
+        title: d.title,
+        tags: [...d.tags]
+      };
+    }),
     views: [...model.views()].map((v) => ({
-      name: v.id,
-      title: v.title,
+      id: v.id,
+      title: v.titleOrId,
       type: v.$view._type
-    }))
+    })),
+    sources: project.documents?.map((d) => d.fsPath) ?? []
   };
 });

package/dist/mcp/tools/read-view.d.ts

@@ -2,9 +2,10 @@ import z from 'zod';
 export declare const readView: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
     inputSchema?: {
         viewId: z.ZodString;
-        project: z.ZodOptional<z.ZodString>;
+        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, ProjectId, string>>>;
     } | undefined;
 }, (args: {
-    viewId: string;
-    project?: string | undefined;
+    [x: string]: any;
+    viewId?: unknown;
+    project?: unknown;
 }, extra: import("@modelcontextprotocol/sdk/shared/protocol").RequestHandlerExtra<import("@modelcontextprotocol/sdk/types").ServerRequest, import("@modelcontextprotocol/sdk/types").ServerNotification>) => import("@modelcontextprotocol/sdk/types").CallToolResult | Promise<import("@modelcontextprotocol/sdk/types").CallToolResult>];