@likec4/language-server 1.42.1 → 1.44.0

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

@@ -0,0 +1,194 @@
+import { invariant } from '@likec4/core';
+import * as z from 'zod/v3';
+import { likec4Tool } from '../utils';
+import { includedInViews, includedInViewsSchema, locationSchema, mkLocate, projectIdSchema } from './_common';
+export const readElement = likec4Tool({
+    name: 'read-element',
+    description: `
+Read detailed information about a LikeC4 element.
+
+Request:
+- id: string — element id (FQN)
+- project: string (optional) — project id. Defaults to "default" if omitted.
+
+Response (JSON object):
+- id: string — element id (FQN)
+- name: string — element name
+- kind: string — element kind
+- title: string — human-readable title
+- description: string|null — optional description
+- technology: string|null — optional technology
+- tags: string[] — assigned tags
+- project: string — project id this element belongs to
+- metadata: Record<string, string> — element metadata
+- shape: string — rendered shape
+- color: string — rendered color
+- children: string[] — ids (FQNs) of direct child elements
+- defaultView: string|null — default view name if set
+- includedInViews: View[] — views that include this element
+- relationships: object — 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[] — deployed instance ids (Deployment FQNs)
+- sourceLocation: { path: string, range: { start: { line: number, character: number }, end: { line: number, character: number } } } | null — source location if available
+
+View (object) fields:
+- id: string — view identifier
+- title: string — 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,
+        idempotentHint: true,
+        title: 'Read element',
+    },
+    inputSchema: {
+        id: z.string().describe('Element id (FQN)'),
+        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().nullable(),
+        technology: z.string().nullable(),
+        tags: z.array(z.string()),
+        project: z.string(),
+        metadata: z.record(z.union([z.string(), z.array(z.string())])),
+        shape: z.string(),
+        color: z.string(),
+        children: z.array(z.string()).describe('Children of this element (Array of FQNs)'),
+        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(),
+                }).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().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, if relationship is indirect'),
+                target: z.object({
+                    id: z.string(),
+                    title: z.string(),
+                    kind: z.string(),
+                }).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('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,
+    },
+}, async (languageServices, args) => {
+    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,
+        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.children()].map(c => c.id),
+        defaultView: element.defaultView?.id || null,
+        includedInViews: includedInViews(element.views()),
+        relationships: {
+            incoming: [...element.incoming()].map(r => ({
+                source: {
+                    id: r.source.id,
+                    title: r.source.title,
+                    kind: r.source.kind,
+                },
+                kind: r.kind,
+                target: r.target.id,
+                title: r.title,
+                description: r.description.text,
+                technology: r.technology,
+                tags: [...r.tags],
+            })),
+            outgoing: [...element.outgoing()].map(r => ({
+                source: r.source.id,
+                target: {
+                    id: r.target.id,
+                    title: r.target.title,
+                    kind: r.target.kind,
+                },
+                kind: r.kind,
+                title: r.title,
+                description: r.description.text,
+                technology: r.technology,
+                tags: [...r.tags],
+            })),
+        },
+        deployedInstances: [...element.deployments()].map(i => i.id),
+        sourceLocation: locate({ element: element.id }),
+    };
+});

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

@@ -1,9 +1,8 @@
-import z from 'zod';
+import * as z from 'zod/v3';
 export declare const readProjectSummary: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
     inputSchema?: {
-        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, ProjectId, string>>>;
-    } | undefined;
+        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, import("@likec4/core").ProjectId, string>>>;
+    };
 }, (args: {
-    [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>];
+    project: string & import("type-fest/source/tagged").Tag<"ProjectID", never>;
+}, extra: import("@modelcontextprotocol/sdk/shared/protocol.js").RequestHandlerExtra<import("@modelcontextprotocol/sdk/types.js").ServerRequest, import("@modelcontextprotocol/sdk/types.js").ServerNotification>) => import("@modelcontextprotocol/sdk/types.js").CallToolResult | Promise<import("@modelcontextprotocol/sdk/types.js").CallToolResult>];

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

@@ -0,0 +1,176 @@
+import { keys } from 'remeda';
+import * as z from 'zod/v3';
+import { likec4Tool } from '../utils';
+import { projectIdSchema } from './_common';
+export const readProjectSummary = likec4Tool({
+    name: 'read-project-summary',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        title: 'Read project summary',
+    },
+    description: `
+Request:
+- project: string (optional) — project id. Defaults to "default" if omitted.
+
+Response (JSON object):
+- title: string — human-readable project title
+- folder: string — absolute path to the project root
+- sources: string[] — absolute file paths of model documents
+- specification: object
+  - elementKinds: string[] — all element kinds
+  - relationshipKinds: string[] — all relationship kinds
+  - deploymentKinds: string[] — all deployment kinds
+  - tags: string[] — all tags
+  - metadataKeys: string[] — used metadata keys
+- elements: Element[] — list of elements
+- deployments: Deployment[] — list of deployment entities
+- views: View[] — list of views defined in the model
+
+Element (object) fields:
+- id: string — element id (FQN)
+- kind: string — element kind
+- title: string — element title
+- tags: string[] — 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 — view identifier
+- title: string — 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: projectIdSchema,
+    },
+    outputSchema: {
+        title: z.string(),
+        folder: z.string(),
+        sources: z.array(z.string()),
+        specification: z.object({
+            elementKinds: z.array(z.string()),
+            relationshipKinds: z.array(z.string()),
+            deploymentKinds: z.array(z.string()),
+            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({
+            id: z.string(),
+            title: z.string(),
+            type: z.enum(['element', 'deployment', 'dynamic']),
+        })),
+    },
+}, async (languageServices, args) => {
+    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.fsPath,
+        specification: {
+            elementKinds: keys(model.specification.elements),
+            relationshipKinds: keys(model.specification.relationships),
+            deploymentKinds: keys(model.specification.deployments),
+            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 => ({
+            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

@@ -1,11 +1,10 @@
-import z from 'zod';
+import * as z from 'zod/v3';
 export declare const readView: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
     inputSchema?: {
         viewId: z.ZodString;
-        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, ProjectId, string>>>;
-    } | undefined;
+        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, import("@likec4/core").ProjectId, string>>>;
+    };
 }, (args: {
-    [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>];
+    project: string & import("type-fest/source/tagged").Tag<"ProjectID", never>;
+    viewId: string;
+}, extra: import("@modelcontextprotocol/sdk/shared/protocol.js").RequestHandlerExtra<import("@modelcontextprotocol/sdk/types.js").ServerRequest, import("@modelcontextprotocol/sdk/types.js").ServerNotification>) => import("@modelcontextprotocol/sdk/types.js").CallToolResult | Promise<import("@modelcontextprotocol/sdk/types.js").CallToolResult>];

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

@@ -0,0 +1,203 @@
+import * as z from 'zod/v3';
+import { likec4Tool } from '../utils';
+import { locationSchema, mkLocate, projectIdSchema } from './_common';
+const modelRef = (node) => {
+    if (node.hasElement()) {
+        return node.element.id;
+    }
+    if (node.hasDeployment()) {
+        return node.deployment.id;
+    }
+    return null;
+};
+const nodeSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('element'),
+        id: z.string().describe('Node ID'),
+        elementId: z.string().describe('Element ID (FQN)'),
+        kind: z.string().describe('Element kind'),
+        title: z.string().describe('Node title'),
+        description: z.string().nullable(),
+        technology: z.string().nullable(),
+        children: z.array(z.string()).describe('Children nodes, array of node IDs'),
+        shape: z.string().describe('Rendered shape'),
+        color: z.string().describe('Rendered color'),
+        tags: z.array(z.string()),
+    }),
+    z.object({
+        type: z.literal('deployment-node'),
+        id: z.string().describe('Node ID'),
+        deploymentId: z.string().describe('Deployment entity ID (FQN)'),
+        kind: z.string().describe('Deployment kind'),
+        title: z.string().describe('Node title'),
+        description: z.string().nullable(),
+        technology: z.string().nullable(),
+        children: z.array(z.string()).describe('Children nodes, array of node IDs'),
+        shape: z.string().describe('Rendered shape'),
+        color: z.string().describe('Rendered color'),
+        tags: z.array(z.string()),
+    }),
+    z.object({
+        type: z.literal('deployed-instance'),
+        id: z.string().describe('Node ID'),
+        deploymentId: z.string().describe('Deployment entity ID (FQN)'),
+        title: z.string().describe('Node title'),
+        description: z.string().nullable(),
+        technology: z.string().nullable(),
+        referencedElement: z.object({
+            id: z.string().describe('Element ID (FQN)'),
+            kind: z.string().describe('Element kind'),
+            title: z.string().describe('Element title'),
+        }),
+        shape: z.string().describe('Rendered shape'),
+        color: z.string().describe('Rendered color'),
+        tags: z.array(z.string()),
+    }),
+]);
+export const readView = likec4Tool({
+    name: 'read-view',
+    description: `
+Read detailed information about a LikeC4 view.
+
+Request:
+- viewId: string — view id (name)
+- project: string (optional) — project id. Defaults to "default" if omitted.
+
+Response (JSON object):
+- id: string — view id
+- type: "element" | "deployment" | "dynamic" — view type
+- title: string — view title (falls back to id if not set)
+- description: string|null — optional description
+- tags: string[] — view tags
+- project: string — project id this view belongs to
+- nodes: Node[] — nodes included in the view
+- edges: Edge[] — relationships between nodes
+- sourceLocation: { path: string, range: { start: { line: number, character: number }, end: { line: number, character: number } } } | null — source location if available
+
+Node (discriminated union by "type"):
+- type = "element": { id: string, elementId: string, kind: string, title: string, description: string|null, technology: string|null, children: string[], shape: string, color: string, tags: string[] }
+- type = "deployment-node": { id: string, deploymentId: string, kind: string, title: string, description: string|null, technology: string|null, children: string[], shape: string, color: string, tags: string[] }
+- type = "deployed-instance": { id: string, deploymentId: string, title: string, description: string|null, technology: string|null, referencedElement: { id: string, kind: string, title: string }, shape: string, color: string, tags: string[] }
+
+Edge object:
+- { source: string, target: string, label: string|null, description: string|null, technology: string|null, tags: string[] }
+
+Notes:
+- Read-only, idempotent, no side effects.
+
+Example response:
+{
+  "id": "system-overview",
+  "type": "element",
+  "title": "System Overview",
+  "description": null,
+  "tags": [],
+  "project": "default",
+  "nodes": [
+    { "type": "logical", "id": "n1", "elementId": "shop.frontend", "kind": "container", "title": "Frontend", "description": null, "technology": "React", "children": [], "shape": "rounded-rectangle", "color": "#2F80ED", "tags": [] }
+  ],
+  "edges": [
+    { "source": "n1", "target": "n2", "label": "calls", "description": null, "technology": "HTTPS", "tags": [] }
+  ],
+  "sourceLocation": {
+    "path": "/abs/path/project/model.c4",
+    "range": { "start": { "line": 10, "character": 0 }, "end": { "line": 30, "character": 0 } }
+  }
+}
+`,
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        title: 'Read view',
+    },
+    inputSchema: {
+        viewId: z.string().describe('View id (name)'),
+        project: projectIdSchema,
+    },
+    outputSchema: {
+        id: z.string(),
+        type: z.enum(['element', 'deployment', 'dynamic']).describe('View type'),
+        title: z.string(),
+        description: z.string().nullable(),
+        tags: z.array(z.string()),
+        project: z.string(),
+        nodes: z.array(nodeSchema),
+        edges: z.array(z.object({
+            source: z.string().describe('Source node'),
+            target: z.string().describe('Target node'),
+            label: z.string().nullable(),
+            description: z.string().nullable(),
+            technology: z.string().nullable(),
+            tags: z.array(z.string()),
+        })).describe('Edge represents relationship between nodes'),
+        sourceLocation: locationSchema,
+    },
+}, async (languageServices, args) => {
+    const projectId = languageServices.projectsManager.ensureProjectId(args.project);
+    const project = languageServices.project(projectId);
+    const model = await languageServices.computedModel(projectId);
+    const view = model.findView(args.viewId);
+    if (!view) {
+        throw new Error(`View with ID '${args.viewId}' not found in project ${project.id}`);
+    }
+    const locate = mkLocate(languageServices, project.id);
+    return {
+        id: view.id,
+        type: view.$view._type,
+        title: view.title ?? view.id,
+        description: view.description.text,
+        tags: [...view.tags],
+        project: project.id,
+        nodes: [...view.nodes()].flatMap((node) => {
+            const base = {
+                id: node.id,
+                title: node.title,
+                description: node.description.text,
+                technology: node.technology,
+                shape: node.shape,
+                color: node.color,
+                tags: [...node.tags],
+            };
+            if (node.hasDeployedInstance()) {
+                return {
+                    ...base,
+                    type: 'deployed-instance',
+                    deploymentId: node.deployment.id,
+                    referencedElement: {
+                        id: node.deployment.element.id,
+                        kind: node.deployment.element.kind,
+                        title: node.deployment.element.title,
+                    },
+                };
+            }
+            if (node.hasDeployment()) {
+                return {
+                    ...base,
+                    type: 'deployment-node',
+                    kind: node.deployment.kind,
+                    deploymentId: node.deployment.id,
+                    children: [...node.children()].map(c => c.id),
+                };
+            }
+            if (node.hasElement()) {
+                return {
+                    ...base,
+                    type: 'element',
+                    elementId: node.element.id,
+                    kind: node.element.kind,
+                    children: [...node.children()].flatMap(c => modelRef(c) ?? []),
+                };
+            }
+            return [];
+        }),
+        edges: [...view.edges()].map(r => ({
+            source: r.source.id,
+            target: r.target.id,
+            label: r.label,
+            description: r.description.text,
+            technology: r.technology,
+            tags: [...r.tags],
+        })),
+        sourceLocation: locate({ view: view.id }),
+    };
+});

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

@@ -1,8 +1,8 @@
-import z from 'zod';
+import * as z from 'zod/v3';
 export declare const searchElement: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
     inputSchema?: {
         search: z.ZodString;
-    } | undefined;
+    };
 }, (args: {
     search: string;
-}, 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>];
+}, extra: import("@modelcontextprotocol/sdk/shared/protocol.js").RequestHandlerExtra<import("@modelcontextprotocol/sdk/types.js").ServerRequest, import("@modelcontextprotocol/sdk/types.js").ServerNotification>) => import("@modelcontextprotocol/sdk/types.js").CallToolResult | Promise<import("@modelcontextprotocol/sdk/types.js").CallToolResult>];