企业官网建设流程全解析

LikeC4 MCP 服务器接入指南：用模型上下文协议查询与可视化软件架构

【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4

@likec4/mcp是 LikeC4 官方提供的 Model Context Protocol（MCP）服务器，它把工作区内的 LikeC4 项目（DSL 模型、部署节点与视图）以只读工具的形式暴露给支持 MCP 的 AI 客户端（编辑器、聊天助手等），让 Agent 可以直接搜索元素、查询关系图、读取视图，甚至在聊天内渲染交互式架构图。读完本文，你将掌握如何配置启动该服务器（stdio / HTTP 两种传输方式）、理解它提供的 20 余个只读工具与能力边界，并能在 VS Code、Claude 等宿主中把 LikeC4 模型变成可被 AI 检索和引用的架构知识源。

什么是@likec4/mcp

LikeC4 的核心理念是“用代码描述软件架构”，模型与视图都定义在.c4DSL 文件中。@likec4/mcp则把这一套模型能力接入 MCP 生态：它通过 Model Context Protocol 的stdio（标准输入输出）或 streamable HTTP 传输方式启动一个 MCP 服务器，向客户端暴露经过解析的已解析 LikeC4 模型（resolved model），包括元素、部署节点、关系、视图等。

在仓库中，该包的实现位于 packages/mcp，package.json声明其bin为likec4-mcp，依赖@likec4/language-server、@likec4/language-services、@likec4/core等核心包，并基于@modelcontextprotocol/sdk与@hono/mcp构建。

需要特别注意的是 MCP 与 CLI 的能力边界（原文明确说明，packages/mcp/README.md 亦如此）：

MCP 工具暴露的是工作区内已解析的 LikeC4 模型（搜索、图查询、视图），不会生成@likec4/leanix-bridge产物、执行 LeanIX 同步，也不会导出带leanixprofile 的 Draw.io。这类能力请使用 CLI（likec4 gen leanix …、likec4 sync leanix …、likec4 export drawio --profile leanix）以及仓库中的 Agent Skill 参考文档 skills/likec4-dsl/references/bridge-leanix-drawio.md。

快速开始：在客户端中配置 MCP 服务器

@likec4/mcp通过 npm 分发，最常见的接入方式是在支持 MCP 的客户端（如 VS Code、Claude Desktop 等）的mcpServers配置中声明它。README 给出的标准配置如下：

{ "mcpServers": { "likec4": { "command": "npx", "args": [ "-y", "@likec4/mcp" ], "env": { "LIKEC4_WORKSPACE": "${workspaceFolder}" } } } }

配置要点：

• command与args：使用npx -y @likec4/mcp，-y表示自动安装，无需预先全局安装。
• env.LIKEC4_WORKSPACE：指定要解析的 LikeC4 工作区目录。若未设置该环境变量，服务器会以当前目录作为工作区（见 packages/mcp/README.md）。
• 该包默认使用stdio传输（transport）启动 MCP 服务器。

以 CLI 方式使用

也可以全局安装后以 CLI 方式运行：

npm install -g @likec4/mcp likec4-mcp -h

CLI 帮助输出（对应 src/cli.ts 中基于citty定义的参数）：

USAGE `likec4-mcp [OPTIONS] [WORKSPACE]` ARGUMENTS `WORKSPACE="."` change workspace, defaults to current directory, can be set by LIKEC4_WORKSPACE env <directory> OPTIONS `--stdio` use stdio transport (this is default) `--http` use streamable http transport `--port=<number>` change http port (default: 33335) `--no-watch` disable watch for changes (consume less resources if you have static workspace)

除了 README 中列出的参数，从 cli.ts 的源码还可以看到两个补充选项：

• --graphviz=<binary|wasm>：选择用二进制dot还是 WebAssembly 版 Graphviz 做布局，默认wasm（免安装依赖）；
• --watch：默认开启文件监听；使用--no-watch可关闭监听以节省资源（适合静态工作区）。

CLI 内部对参数做了约束：--stdio与--http/--port互斥（setup阶段会抛出stdio and http are mutually exclusive）。同时注意node >= 22.22.3是运行该包的版本要求（见 package.json）。

两种传输方式：stdio 与 streamable HTTP

stdio（默认）

默认情况下 MCP 服务器通过标准输入/输出与宿主进程通信，这也是绝大多数桌面客户端的接入方式。实现位于 src/server/StdioLikeC4MCPServer.ts：它基于StdioServerTransport连接McpServer，并监听 stdin 的end/close事件在输入关闭时自动清理服务器（见 src/index.ts 中startLikeC4MCP的生命周期管理）。

HTTP（streamable）

通过--http或指定--port可切换到 streamable HTTP 传输。实现位于 src/server/StreamableLikeC4MCPServer.ts，要点：

• 基于 Hono 构建 HTTP 应用，默认端口 33335（--port可改）；
• 提供GET /health健康检查端点；
• MCP 协议端点位于POST/GET /mcp，使用StreamableHTTPTransport+MemoryEventStore维护会话；
• 默认开启全源 CORS（origin: '*'），便于远程客户端或浏览器环境接入；
• 绑定0.0.0.0，可从外部访问。

服务器内部架构与生命周期

从源码看，@likec4/mcp的启动链路清晰：

1. startLikeC4MCP（src/index.ts）→initLikeC4MCP：
   • 用defu合并默认配置（mcp: 'stdio'、graphviz: 'wasm'、watch: true等）；
   • 调用@likec4/language-services的fromWorkspace(workspace, {...})加载工作区（开启manualLayouts: true）；
   • 将语言服务实例注入全局上下文（setLanguageServicesCtx，见 src/ctx.ts）；
   • 按传输方式实例化StdioLikeC4MCPServer或StreamableLikeC4MCPServer。
2. 服务器启动后调用createMCPServer（src/server/createMCPServer.ts）创建McpServer：
   • 服务器名LikeC4，版本号取自package.json；
   • 声明 capabilities：tools、prompts、resources、logging、completions；
   • 通过函数式 pipe 依次注册全部工具、prompt 与资源；
   • instructions中内置给 LLM 的使用约定：所有工具只读且幂等；project参数可选、默认"default"；优先用search-element/read-project-summary/list-projects定位项目。
3. 日志：stdio 模式下日志写入 stderr（避免污染协议通道），HTTP 模式下使用彩色输出，见configureLanguageServerLogger({ useStdErr: opts.mcp === 'stdio', ... })。

集成测试 src/tests/createMCPServer.int.spec.ts 验证了服务器身份（name=LikeC4、version 为语义化版本）、tools/prompts/resources/logging 能力声明、工具描述与输入 schema 完整性，以及 JSON Schema 2020-12 方言声明等契约。

可用工具一览

服务器共注册 20 个工具。集成测试EXPECTED_TOOLS（见 src/tests/createMCPServer.int.spec.ts）对全部工具做了精确断言，按功能可分为四类：

发现与导航

关系与图查询

标签与元数据过滤

聚合、比较与渲染

注：createMCPServer中注册的工具实际为 20 个，除上表外还包含apply-semantic-layout（通过 LLM 采样为视图应用语义布局，属于改写型工具，见 src/tools/apply-semantic-layout.ts），以及apply_semantic_layoutprompt（src/prompts/applySemanticLayout.ts）。

工具的通用行为与约定

只读、幂等、JSON Schema 2020-12

所有工具声明了readOnlyHint: true与idempotentHint: true注解（open-view的注解为"对项目模型只读且幂等，但会触发编辑器 UI 动作"）。参数与输出统一用 Zod 定义，并由 src/utils.ts 中的likec4Tool帮助函数包装注册：

• 输入/输出 schema 均声明为 JSON Schema 2020-12（mcpToolSchema添加$schema元数据），MCP SDK 1.x 默认会生成 draft-07 方言，因此直接注册的工具必须使用该帮助函数（见 utils.ts）；
• 字符串返回被包装为content: [{ type: 'text', text }]；
• 有outputSchema的工具返回structuredContent（结构化内容）；
• 异常统一转换为isError: true的CallToolResult，带文本错误信息。

协议层行为由测试 src/tests/tool-protocol.int.spec.ts 验证：正常路径返回structuredContent；不存在的元素、非法参数类型、未知工具名都会返回isError: true。

project 参数与默认值

绝大多数工具都接受可选的project参数，默认"default"（projectIdSchema，见 src/tools/_common.ts）。工作区可以同时包含多个项目（参考仓库examples/multi-project目录的配置），因此推荐先用list-projects明确目标项目 id。

sourceLocation 与编辑器跳转

read-element、read-view、read-deployment、find-relationships、batch-read-elements等工具会通过语言服务的locate能力返回sourceLocation（path+range）。服务器 instructions 明确建议：响应中出现sourceLocation时，应把该位置作为链接提供给用户，方便在编辑器中直接跳转到 DSL 源文件。

关键工具深入解析

search-element：带查询语法的元素搜索

src/tools/search-element.ts 实现了大小写不敏感的检索，支持前缀查询语法：

• kind:<value>：按 kind 精确过滤；
• shape:<value>：按 shape 过滤；
• meta:<key>：按是否拥有某 metadata 键过滤；
• #<value>：按标签包含匹配；
• 其他文本：匹配元素 id（FQN）或标题的包含关系。

搜索至少需要 2 个字符，结果返回total与found（最多 20 条），每条含type（element/deployment-node）判别、项目 id、includedInViews 等，可直接作为其他工具的输入。实现上通过languageServices.computedModel(project.id)遍历所有项目，并对元素与部署节点分别过滤。

query-graph：七种图查询

src/tools/query-graph.ts 提供ancestors、descendants、siblings、children、parent、incomers、outgoers七种查询类型：

• 层级类查询直接使用元素模型的关系方法（element.ancestors()、element.descendants()等），includeIndirect对层级查询无效；
• incomers/outgoers为单跳查询，includeIndirect=true（默认）时包含经由嵌套元素产生的间接关系；
• 结果上限 100 条，超出时truncated: true；
• 根元素的parent查询返回空数组。

递归图遍历：incomers / outgoers / relationship-paths

• query-incomers-graph.ts 与 query-outgoers-graph.ts 共用_common.ts中的traverseGraphBFS 实现，支持maxDepth（默认 10，上限 50）与maxNodes（默认 200，上限 2000）双重限界，内置 visited 集合做环检测，返回带depth、邻居（含关系标签与技术栈）的完整子图。典型场景：数据库元素的上游写入者全链路、API 服务的下游消费方与变更影响面（blast radius）分析。
• find-relationship-paths.ts 在两点之间做 BFS 路径发现，每条路径记录有序的 relationship 步骤（kind/title/description/technology/tags），结果按长度升序排列；拒绝 source 与 target 相同。

render-view与preview-view：把图带进对话

这两个工具面向支持MCP Apps（模型上下文协议扩展应用）的宿主，能在聊天内渲染交互式架构图：

• render-view（src/tools/render-view.ts）：给定viewId渲染已有视图，支持fullModel（是否附带完整模型数据，默认按视图裁剪）、render.size（compact/standard/large，默认standard）、render.fitView（默认 true）、render.initialZoom（覆盖 fitView）。实现上使用languageServices.layoutedModel获取布局后的视图，再通过buildRenderPayload（src/tools/_common.ts）构建view+model载荷；默认按视图裁剪模型，只包含该视图涉及的节点、祖先、关系与部署实体，避免超大响应；本地 SVG 图标会被内联为 data URI。
• preview-view（src/tools/preview-view.ts）：接受一段view <id> ... { ... }DSL 文本，视图 id 必须全新（已存在则报错并提示改用render-view）。实现上从现有项目文档构造虚拟源码，加上新视图 DSL 后调用fromSources构建隔离的临时实例完成解析、校验与布局，全程不落盘。集成测试 src/tests/preview-view.int.spec.ts 验证了"预览不持久化"：预览后调用render-view渲染该 id 会失败。注意事项：预览样式可能与真实项目不完全一致（自定义主题/样式扩展不作用于预览），且仅识别view <id>（element view）声明，dynamic view/deployment view会报通用错误。

查询类的边界与性能设计

为了不让响应体积失控，聚合类工具都设置了明确上限：query-by-metadata/query-by-tags/query-by-tag-pattern最多 50 条；subgraph-summary最多 200 条（maxDepth默认 10、上限 20，可用metadataKeys裁剪返回的 metadata）；find-relationship-paths最多 100 条路径；query-graph最多 100 条。batch-read-elements单次最多 50 个 id，未找到的 id 放入notFound数组而非报错，适合作为"多元素摘要"的批量替代（其返回的links与sourceLocation与read-element一致，仅当还需要关系、部署实例、defaultView 时才必须用read-element）。

element-diff：对比两个元素的差异

src/tools/element-diff.ts 对两个同项目元素做并排对比：属性（kind/title/description/technology/shape/color）的逐项 diff、标签的三分（仅 A / 仅 B / 共有）、metadata 的四分（仅 A / 仅 B / 值不同 / 相同）、以及关系数量的三类统计（入边/出边的独有与共享计数）。适合排查"两个相似节点为何配置不同"之类的模型审查场景。

资源与提示词（Resources / Prompts）

除工具外，服务器还提供 MCP 资源与提示词（在 createMCPServer.ts 中声明 capabilities）：

• 项目资源likec4://project/{projectId}（src/resource/project.ts）：以application/json返回项目的 id、title、folder，并支持列出与参数补全（completion）。测试 src/tests/resources.int.spec.ts 验证了likec4://project/default的读写往返与未知项目返回空 contents 的行为。
• 渲染 UI 资源ui://likec4/render-view.html（src/resource/render-view.ts）：向 MCP Apps 宿主提供渲染render-view的 HTML 客户端（脚本与样式来自构建产物dist/app/render-view-client.js/.css，见 src/appAssets.ts）。
• 提示词apply_semantic_layout（src/prompts/applySemanticLayout.ts）：生成调用apply-semantic-layout工具的引导消息，projectId/viewId均支持服务端补全。

与 CLI / LeanIX / Draw.io 的分工

一句话总结能力边界：MCP 负责"读"与"聊"，CLI 负责"写"与"导出"。

• 需要向 AI 暴露模型供检索、提问、渲染视图 → 用@likec4/mcp；
• 需要生成@likec4/leanix-bridge产物、执行 LeanIX 同步、或导出带leanixprofile 的 Draw.io 文件 → 用 CLI（likec4 gen leanix …、likec4 sync leanix …、likec4 export drawio --profile leanix），详细流程参见仓库的 skills/likec4-dsl/references/bridge-leanix-drawio.md；
• 模型与视图的 DSL 语法、include 谓词、部署视图等细节，可查阅 skills/likec4-dsl/references 下的参考文档（model.md、views.md、deployment.md、predicates.md 等）。

常见排查与进阶建议

1. 启动后无输出 / 客户端连不上：确认LIKEC4_WORKSPACE指向包含*.c4与可选likec4.config.*的目录；stdio 模式下日志走 stderr，不要与协议流混用。
2. search-element查不到结果：检查搜索串是否至少 2 个字符、是否用了kind:/shape:/meta:/#前缀语法；先用list-projects与read-project-summary确认项目与元素存在。
3. 响应过大：render-view/preview-view默认裁剪模型（fullModel: false）；图查询收紧maxDepth/maxNodes；subgraph-summary用metadataKeys裁剪 metadata。
4. 调试与测试：仓库提供了完整的集成测试套件（src/tests），覆盖协议往返、预览不落盘、资源读取、stdio 生命周期与打包冒烟测试，可作为理解服务器行为的第一手参考。
5. 版本要求：运行@likec4/mcp需要 Node.js ≥ 22.22.3（见 packages/mcp/package.json）。

小结

@likec4/mcp把 LikeC4 的"代码即架构"能力接入 MCP 生态：通过 20 个只读工具、一个渲染类工具、一个语义布局工具、若干资源与提示词，AI 助手可以在不触碰 DSL 文件的前提下完成元素定位、关系溯源、影响面分析、视图渲染与视图草稿预览。接入只需一行npx -y @likec4/mcp的配置，配合LIKEC4_WORKSPACE指定工作区即可。对于需要 LeanIX 同步与 Draw.io 导出等写操作场景，则应交由 CLI 与 Agent Skill 处理——两者正好互补，共同构成 LikeC4 的自动化架构治理闭环。

【免费下载链接】likec4Visualize, collaborate, and evolve the software architecture with always actual and live diagrams from your code项目地址: https://gitcode.com/GitHub_Trending/li/likec4