@likec4/language-server 1.36.1 → 1.38.0

package/dist/mcp/server/StreamableLikeC4MCPServer.js

@@ -0,0 +1,156 @@
+import { serve } from "@hono/node-server";
+import { loggable } from "@likec4/log";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { toFetchResponse, toReqRes } from "fetch-to-node";
+import { Hono } from "hono";
+import { createServer } from "node:http";
+import { logger } from "../utils.js";
+export class StreamableLikeC4MCPServer {
+  constructor(services) {
+    this.services = services;
+  }
+  // Store transports by session ID to send notifications
+  server = void 0;
+  _port = 33335;
+  get mcp() {
+    throw new Error("StreamableLikeC4MCPServer has access to McpServer only during the request");
+  }
+  get isStarted() {
+    return this.server?.listening === true;
+  }
+  get port() {
+    return this._port;
+  }
+  async dispose() {
+    await this.stop();
+  }
+  async start(port = 33335) {
+    if (this.server) {
+      if (this.port === port) {
+        return;
+      }
+      await this.stop();
+    }
+    logger.info("Starting MCP server on port {port}", { port });
+    this._port = port;
+    const app = new Hono().post("/mcp", async (c) => {
+      const { req, res } = toReqRes(c.req.raw);
+      const server = this.services.mcp.ServerFactory.create();
+      try {
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: void 0
+        });
+        transport.onerror = (err) => {
+          logger.error(loggable(err));
+        };
+        await server.connect(transport);
+        await transport.handleRequest(req, res, await c.req.json());
+        res.on("close", () => {
+          logger.debug("Request closed");
+          transport.close();
+          server.close();
+        });
+        return toFetchResponse(res);
+      } catch (e) {
+        logger.error(loggable(e));
+        return c.json(
+          {
+            jsonrpc: "2.0",
+            error: {
+              code: -32603,
+              message: "Internal server error"
+            },
+            id: null
+          },
+          { status: 500 }
+        );
+      }
+    }).get("/mcp", async (c) => {
+      logger.debug("Received GET MCP request");
+      return c.json(
+        {
+          jsonrpc: "2.0",
+          error: {
+            code: -32e3,
+            message: "Method not allowed."
+          },
+          id: null
+        },
+        { status: 405 }
+      );
+    }).delete("/mcp", async (c) => {
+      logger.debug("Received DELETE MCP request");
+      return c.json(
+        {
+          jsonrpc: "2.0",
+          error: {
+            code: -32e3,
+            message: "Method not allowed."
+          },
+          id: null
+        },
+        { status: 405 }
+      );
+    }).notFound((c) => {
+      logger.debug(`${c.req.method} ${c.req.url} not found`);
+      return c.json(
+        {
+          jsonrpc: "2.0",
+          error: {
+            code: -32e3,
+            message: "Method not found."
+          },
+          id: null
+        },
+        { status: 404 }
+      );
+    }).onError((e, c) => {
+      logger.error(loggable(e));
+      return c.json(
+        {
+          jsonrpc: "2.0",
+          error: {
+            code: -32603,
+            message: "Internal server error"
+          },
+          id: null
+        },
+        { status: 500 }
+      );
+    });
+    return new Promise((resolve, reject) => {
+      try {
+        this.server = serve(
+          {
+            fetch: app.fetch,
+            port: this._port,
+            createServer
+          },
+          (info) => {
+            logger.info("MCP server listening on port {port}", { port: info.port });
+            resolve();
+          }
+        );
+      } catch (err) {
+        reject(err);
+      }
+    });
+  }
+  async stop() {
+    const server = this.server;
+    if (!server) {
+      return;
+    }
+    logger.info("Stopping MCP server");
+    this.server = void 0;
+    return new Promise((resolve) => {
+      server.close((err) => {
+        if (err) {
+          logger.error("Failed to stop MCP server", { err });
+        }
+        logger.info("MCP server stopped");
+        resolve();
+      });
+    });
+  }
+}

package/dist/mcp/server/WithMCPServer.d.ts

@@ -0,0 +1,2 @@
+import type { LikeC4MCPServerModuleContext } from '../interfaces';
+export declare const WithMCPServer: (type?: "stdio" | "sse") => LikeC4MCPServerModuleContext;

package/dist/mcp/server/WithMCPServer.js

@@ -0,0 +1,57 @@
+import { loggable } from "@likec4/log";
+import { isError } from "remeda";
+import { logger } from "../../logger.js";
+import { StdioLikeC4MCPServer } from "./StdioLikeC4MCPServer.js";
+import { StreamableLikeC4MCPServer } from "./StreamableLikeC4MCPServer.js";
+const streamableLikeC4MCPServer = (services) => {
+  logger.debug("Creating StreamableLikeC4MCPServer");
+  const server = new StreamableLikeC4MCPServer(services);
+  const langId = services.LanguageMetaData.languageId;
+  const connection = services.shared.lsp.Connection;
+  services.shared.workspace.ConfigurationProvider.onConfigurationSectionUpdate((update) => {
+    if (update.section !== langId) {
+      logger.warn("Unexpected configuration update: {update}", { update });
+      return;
+    }
+    logger.debug("Configuration update: {update}", { update });
+    const {
+      enabled = false,
+      port = 33335
+    } = update.configuration.mcp;
+    if (!enabled) {
+      server.stop();
+      return;
+    }
+    Promise.resolve().then(() => server.start(port)).then(() => {
+      connection?.telemetry?.logEvent({
+        eventName: "mcp-server-started",
+        mcpPort: port
+      });
+    }).catch((err) => {
+      const message = isError(err) ? err.message : void 0;
+      connection?.telemetry?.logEvent({
+        eventName: "mcp-server-start-failed",
+        mcpPort: port,
+        ...message && { message }
+      });
+      logger.error("Failed to start LikeC4 MCP Server", { err });
+      if (connection) {
+        connection.window.showErrorMessage(`LikeC4: Failed to start MCP Server
+
+${loggable(err)}`);
+      }
+    });
+  });
+  return server;
+};
+const stdioLikeC4MCPServer = (services) => {
+  return new StdioLikeC4MCPServer(services);
+};
+export const WithMCPServer = (type = "sse") => ({
+  mcpServer: (services) => {
+    if (type === "stdio") {
+      return stdioLikeC4MCPServer(services);
+    }
+    return streamableLikeC4MCPServer(services);
+  }
+});

package/dist/mcp/tools/_common.d.ts

@@ -1,6 +1,9 @@
+import type { LikeC4ViewModel } from '@likec4/core/model';
 import z from 'zod';
-export declare const locationSchema: z.ZodObject<{
-    uri: z.ZodString;
+import type { LikeC4LanguageServices } from '../../LikeC4LanguageServices';
+import type { Locate } from '../../protocol';
+export declare const locationSchema: z.ZodNullable<z.ZodObject<{
+    path: z.ZodString;
     range: z.ZodObject<{
         start: z.ZodObject<{
             line: z.ZodNumber;
@@ -42,7 +45,6 @@ export declare const locationSchema: z.ZodObject<{
         };
     }>;
 }, "strip", z.ZodTypeAny, {
-    uri: string;
     range: {
         start: {
             line: number;
@@ -53,8 +55,8 @@ export declare const locationSchema: z.ZodObject<{
             character: number;
         };
     };
+    path: string;
 }, {
-    uri: string;
     range: {
         start: {
             line: number;
@@ -65,4 +67,21 @@ export declare const locationSchema: z.ZodObject<{
             character: number;
         };
     };
-}>;
+    path: string;
+}>>;
+export declare const projectIdSchema: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, ProjectId, string>>>;
+export declare const includedInViewsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodEnum<["element", "deployment", "dynamic"]>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    id: string;
+    type: "deployment" | "dynamic" | "element";
+}, {
+    title: string;
+    id: string;
+    type: "deployment" | "dynamic" | "element";
+}>, "many">;
+export declare const includedInViews: (views: Iterable<LikeC4ViewModel>) => z.infer<typeof includedInViewsSchema>;
+export declare const mkLocate: (languageServices: LikeC4LanguageServices, projectId: string) => (params: Locate.Params) => z.infer<typeof locationSchema>;

package/dist/mcp/tools/_common.js

@@ -1,6 +1,9 @@
+import { URI } from "vscode-uri";
 import z from "zod";
+import { ProjectsManager } from "../../workspace/index.js";
+import { logger } from "../utils.js";
 export const locationSchema = z.object({
-  uri: z.string(),
+  path: z.string().describe("Path to the file"),
   range: z.object({
     start: z.object({
       line: z.number(),
@@ -10,5 +13,30 @@ export const locationSchema = z.object({
       line: z.number(),
       character: z.number()
     })
-  })
-});
+  }).describe("Range in the file")
+}).nullable();
+export const projectIdSchema = z.string().refine((v) => true).optional().default(ProjectsManager.DefaultProjectId).describe('Project id (optional, will use "default" if not specified)');
+export const includedInViewsSchema = z.array(z.object({
+  id: z.string().describe("View id"),
+  title: z.string().describe("View title"),
+  type: z.enum(["element", "deployment", "dynamic"]).describe("View type")
+}));
+export const includedInViews = (views) => {
+  return [...views].map((v) => ({
+    id: v.id,
+    title: v.titleOrId,
+    type: v.$view._type
+  }));
+};
+export const mkLocate = (languageServices, projectId) => (params) => {
+  try {
+    const loc = languageServices.locate({ projectId, ...params });
+    return loc ? {
+      path: URI.parse(loc.uri).fsPath,
+      range: loc.range
+    } : null;
+  } catch (e) {
+    logger.debug(`Failed to locate ${params}`, { error: e });
+    return null;
+  }
+};

package/dist/mcp/tools/find-relationships.d.ts

@@ -0,0 +1,13 @@
+import z from 'zod';
+export declare const findRelationships: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
+    inputSchema?: {
+        element1: z.ZodString;
+        element2: z.ZodString;
+        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, ProjectId, string>>>;
+    } | undefined;
+}, (args: {
+    [x: string]: any;
+    element1?: unknown;
+    element2?: 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/find-relationships.js

@@ -0,0 +1,151 @@
+import { modelConnection } from "@likec4/core/model";
+import { invariant, isSameHierarchy } from "@likec4/core/utils";
+import z from "zod";
+import { likec4Tool } from "../utils.js";
+import { includedInViews, includedInViewsSchema, locationSchema, mkLocate, projectIdSchema } from "./_common.js";
+const endpointSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  kind: z.string()
+});
+const searchResultSchema = z.object({
+  type: z.enum(["direct", "indirect"]).describe(
+    'Type of relationship, "direct" for direct relationships, "indirect" for relationships through nested elements'
+  ),
+  source: endpointSchema,
+  target: endpointSchema,
+  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"),
+  includedInViews: includedInViewsSchema.describe("Views that include this relationship"),
+  sourceLocation: locationSchema
+});
+export const findRelationships = likec4Tool({
+  name: "find-relationships",
+  annotations: {
+    readOnlyHint: true,
+    idempotentHint: true,
+    title: "Find relationships between two elements"
+  },
+  description: `
+Find relationships between two LikeC4 elements within a project.
+
+What it does:
+- Finds both direct relationships (element1 \u2194 element2) and indirect ones that arise via containment (e.g. via nested elements).
+- Returns rich metadata for each relationship and where it appears in views.
+
+Inputs:
+- element1: string \u2014 Element ID (FQN)
+- element2: string \u2014 Element ID (FQN)
+- project: string (optional, defaults to "default") \u2014 Project id
+
+Output:
+- found: Relationship[]
+
+Relationship (object) fields:
+- type: "direct" | "indirect" \u2014 direct is between the specified endpoints; indirect is via nested elements
+- source: Endpoint
+- target: Endpoint
+- kind: string|null \u2014 relationship kind from the model
+- title: string|null \u2014 relationship title if provided
+- description: string|null \u2014 relationship description text
+- technology: string|null \u2014 relationship technology
+- tags: string[] \u2014 relationship tags
+- includedInViews: View[] \u2014 views where this relationship appears
+- sourceLocation: { path: string, range: { start: { line: number, character: number }, end: { line: number, character: number } } } | null
+
+Endpoint (object) fields:
+- id: string \u2014 Element ID (FQN)
+- title: string \u2014 element title
+- kind: string \u2014 element kind
+
+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. May trigger UI navigation in supporting clients.
+- The order of results is not guaranteed.
+
+Example:
+Request:
+{
+  "element1": "shop.frontend",
+  "element2": "shop.backend",
+  "project": "default"
+}
+
+Response:
+{
+  "found": [
+    {
+      "type": "direct",
+      "source": { "id": "shop.frontend", "title": "Frontend", "kind": "component" },
+      "target": { "id": "shop.backend", "title": "Backend", "kind": "component" },
+      "kind": "sync",
+      "title": "Calls",
+      "description": "Frontend calls Backend",
+      "technology": "HTTP",
+      "tags": ["public"],
+      "includedInViews": [
+        { "id": "system-overview", "title": "System Overview", "type": "element" }
+      ],
+      "sourceLocation": {
+        "path": "/abs/path/project/model.c4",
+        "range": { "start": { "line": 12, "character": 0 }, "end": { "line": 14, "character": 0 } }
+      }
+    }
+  ]
+}
+`,
+  inputSchema: {
+    element1: z.string().describe("Element ID (FQN)"),
+    element2: z.string().describe("Element ID (FQN)"),
+    project: projectIdSchema
+  },
+  outputSchema: {
+    found: z.array(searchResultSchema)
+  }
+}, async (languageServices, args) => {
+  const projectId = languageServices.projectsManager.ensureProjectId(args.project);
+  if (isSameHierarchy(args.element1, args.element2)) {
+    throw new Error("No relationships possible between parent-child");
+  }
+  const found = [];
+  const model = await languageServices.computedModel(projectId);
+  const el1 = model.findElement(args.element1);
+  invariant(el1, `Element "${args.element1}" not found in project "${projectId}"`);
+  const el2 = model.findElement(args.element2);
+  invariant(el2, `Element "${args.element2}" not found in project "${projectId}"`);
+  const locate = mkLocate(languageServices, projectId);
+  const relationships = modelConnection.findConnection(el1, el2, "both").flatMap((c) => [...c.relations]);
+  for (const relationship of relationships) {
+    const isDirect = relationship.source === el1 && relationship.target === el2 || relationship.source === el2 && relationship.target === el1;
+    found.push({
+      type: isDirect ? "direct" : "indirect",
+      source: {
+        id: relationship.source.id,
+        title: relationship.source.title,
+        kind: relationship.source.kind
+      },
+      target: {
+        id: relationship.target.id,
+        title: relationship.target.title,
+        kind: relationship.target.kind
+      },
+      kind: relationship.kind,
+      title: relationship.title,
+      description: relationship.description.text,
+      technology: relationship.technology,
+      tags: [...relationship.tags],
+      includedInViews: includedInViews(relationship.views()),
+      sourceLocation: locate({ relation: relationship.id })
+    });
+  }
+  return {
+    found
+  };
+});

package/dist/mcp/tools/list-projects.js

@@ -3,32 +3,60 @@ import { likec4Tool } from "../utils.js";
 export const listProjects = likec4Tool({
   name: "list-projects",
   description: `
-Lists all available LikeC4 projects in the workspace.
-Returns array of projects with:
-- name: project name (project id)
-- title: human readable title
-- folder: project folder
-- sources: array of project sources
+List LikeC4 projects discoverable in the current workspace.
+
+Request:
+- No input parameters.
+
+Response (JSON object):
+- projects: Project[]
+
+Project (object) fields:
+- id: string \u2014 stable project identifier
+- title: string \u2014 human-readable project title
+- folder: string \u2014 absolute path to the project root
+- sources: string[] \u2014 absolute file paths of related documents
+
+Notes:
+- Read-only, idempotent, no side effects.
+- Safe to call repeatedly.
+
+Example response:
+{
+  "projects": [
+    {
+      "id": "docs",
+      "title": "Documentation",
+      "folder": "/abs/path/to/workspace/docs",
+      "sources": [
+        "/abs/path/to/workspace/docs/model/contexts.likec4",
+        "/abs/path/to/workspace/docs/model/relations.likec4"
+      ]
+    }
+  ]
+}
 `,
   annotations: {
-    readOnlyHint: true
+    readOnlyHint: true,
+    idempotentHint: true,
+    title: "List projects"
   },
   outputSchema: {
     projects: z.array(z.object({
-      name: z.string(),
-      title: z.string().optional(),
+      id: z.string(),
+      title: z.string(),
       folder: z.string(),
       sources: z.array(z.string())
     }))
   }
 }, async (languageServices) => {
-  const projects = await languageServices.projects();
+  const projects = languageServices.projects();
   return {
     projects: projects.map((p) => ({
-      name: p.id,
-      title: p.config?.title,
-      folder: p.folder.toString(),
-      sources: p.documents?.map((d) => d.toString()) ?? []
+      id: p.id,
+      title: p.title,
+      folder: p.folder.fsPath,
+      sources: p.documents.map((d) => d.fsPath)
     }))
   };
 });

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

@@ -2,9 +2,10 @@ import z from 'zod';
 export declare const openView: (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>];

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

@@ -1,29 +1,52 @@
-import { invariant } from "@likec4/core";
 import z from "zod";
-import { ProjectsManager } from "../../workspace/index.js";
 import { likec4Tool } from "../utils.js";
+import { locationSchema, mkLocate, projectIdSchema } from "./_common.js";
 export const openView = likec4Tool({
   name: "open-view",
   description: `
-Opens the panel with the LikeC4 view in the editor.
-Only one view can be opened at a time.
-`.trimStart(),
+Open a LikeC4 view in the editor's preview panel.
+
+Request:
+- viewId: string \u2014 view id (name)
+- project: string (optional) \u2014 project id. Defaults to "default" if omitted.
+
+Response (JSON object):
+- location: { path: string, range: { start: { line: number, character: number }, end: { line: number, character: number } } } | null \u2014 source location of the view if available
+
+Notes:
+- Read-only and idempotent with respect to the project model. Triggers a UI action in the editor.
+- Only one preview panel can be open at a time.
+
+Example response:
+{
+  "location": {
+    "path": "/abs/path/project/model.c4",
+    "range": { "start": { "line": 10, "character": 0 }, "end": { "line": 30, "character": 0 } }
+  }
+}
+`,
   annotations: {
-    readOnlyHint: true
+    readOnlyHint: true,
+    idempotentHint: true,
+    title: "Open view in preview panel"
   },
   inputSchema: {
     viewId: z.string().describe("View id (name)"),
-    project: z.string().optional().describe('Project name (optional, will use "default" if not specified)')
+    project: projectIdSchema
+  },
+  outputSchema: {
+    location: 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 view = model.findView(args.viewId);
   if (!view) {
-    throw new Error(`View with ID '${args.viewId}' not found in project ${project.id}`);
+    throw new Error(`View with ID '${args.viewId}' not found in project ${projectId}`);
   }
-  await languageServices.views.openView(view.id, project.id);
-  return `Command was sent to the editor to open the view "${view.id}"`;
+  await languageServices.views.openView(view.id, projectId);
+  const locate = mkLocate(languageServices, projectId);
+  return {
+    location: locate({ view: view.id })
+  };
 });

package/dist/mcp/tools/{read-project-elements.d.ts → read-deployment.d.ts}

@@ -1,8 +1,11 @@
 import z from 'zod';
-export declare const readProjectElements: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
+export declare const readDeployment: (languageServices: import("../..").LikeC4LanguageServices) => [string, {
     inputSchema?: {
-        project: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        project: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodString, ProjectId, string>>>;
     } | undefined;
 }, (args: {
-    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>];