koder-design-lsp — KDS editor + AI integration server

  • Area: Developer SDK
  • Path: engines/sdk/koder-design-lsp
  • Kind: Go (no-CGO, ~3 MB static) LSP + MCP server
  • Ticket prefix: DESIGN-LSP
  • Spec contract: meta/docs/stack/specs/develop/ide-integration.kmd

Role in the stack

koder-design-lsp is the read/assist edge of the Koder Design System inside developer tools. One binary, two protocols:

  • LSP (over stdio) — hover, completion, drift diagnostics, code

    actions, code lenses, go-to-definition, and document symbols for Koder Design references in any LSP-aware editor (VSCode, Zed, JetBrains, Vim).

  • MCP (Model Context Protocol; stdio or streamable-http) — lets AI

    coding agents (Claude Code, Cursor, Windsurf, Continue) discover and query KDS without scraping HTML.

It is a pure consumer of tools/design-gen's output: the live token catalogue (kds.koder.dev/api/v1/tokens.json) and the MCP descriptor (kds.koder.dev/<locale>/mcp/descriptor.json). It holds no state of its own beyond a token cache.

What it provides

Surface Method / endpoint Notes
Hover textDocument/hover Koder<Component> + KoderTokens.* / --kds-color-*; mutable via hoverPreview
Completion textDocument/completion Token autocomplete per languageId (DartCSSTS-JSKotlinSwift)
Drift diagnostics textDocument/publishDiagnostics Hardcoded color literals exceeding a ΔE2000 threshold; koder:ignore-drift markers
Quick fixes textDocument/codeAction "Replace with KoderTokens.…" / var(--kds-color-…)
Code lens textDocument/codeLens Per-drift-hit informational lens (v0.6.0)
Definition textDocument/definition Returns the kds.koder.dev URL Location
Document symbols textDocument/documentSymbol Outline / Ctrl+Shift+O — components (Class) + tokens (Constant); v0.7.0 (#010)
Live settings workspace/didChangeConfiguration + workspace/executeCommand koder.design.reloadTokens force-refresh
MCP tools tools/list + tools/call 6 tools: getcomponent, findtoken, listpatterns, getspec, search, querybykind
MCP resources resources/list + resources/read Each catalog item as kds://spec/<kind>/<slug>
Ops /healthz, /metrics Readiness probe (v0.7.0 #009) + opt-in Prometheus (#004)

Pipeline

  kds.koder.dev/api/v1/tokens.json        kds.koder.dev/<locale>/mcp/descriptor.json
            |  (24h TTL cache,                       |  (--mcp-descriptor)
            |   bundled-seed fallback)               |
            v                                        v
  internal/tokens (live catalogue)         internal/mcp (tools + resources)
            |                                        |
            +--------> koder-design-lsp binary <-----+
                          |            |
              LSP over stdio        MCP over stdio  OR  streamable-http
              (editor subprocess)   (AI agent)          (kds.koder.dev/mcp/)

Deploy

  • LSP: per-editor subprocess — each extension installs the binary and

    spawns koder-design-lsp (no rollout window; ephemeral).

  • MCP streamable-http: deployed at kds.koder.dev/mcp/ (systemd unit

    on the jet container, Koder Jet vhost; #005/#007). Serves anonymously (public read-only docs, stack-RFC-002 §Auth carve-out). v0.7.0 added graceful drain on SIGTERM (--mcp-drain, default 30s) + a /healthz readiness probe per always-on.kmd R4.2/R4.3 (#009).

Primary couplings

Relationship Detail
tools/design-gen Consumes api/v1/tokens.json (live, 24h TTL) + mcp/descriptor.json; design-gen is the write half, this is the read/assist half
engines/sdk/koder-design-vscode / -zed / -jetbrains Editor extensions that spawn the binary
infra/net/jet Serves the kds.koder.dev/mcp/ vhost
AI agents Claude Code / Cursor / Windsurf via MCP (claude mcp add koder-design …)

Test infrastructure

Every internal/ package carries unit tests (codelens, completion, config, definition, drift, hover, jsonrpc, lsp, mcp, metrics, tokens): recognizer + range correctness (hoverdefinitiondocumentSymbol share one recognizer, hover.Symbols), ΔE2000 math, drift scan, MCP tool/resource dispatch, HTTP transport + /healthz readiness + graceful-shutdown lifecycle, token fetch/cache fallback.

RFCs / specs

  • design-RFC-010 — MCP server (this module hosts the runtime; the static

    descriptor + .well-known/mcp.json discovery are emitted by design-gen)

  • specs/develop/ide-integration.kmd — LSP contract
  • policies/always-on.kmd — R4.2 (healthz) + R4.3 (graceful shutdown)

Backlog topology

  • Component backlog: engines/sdk/koder-design-lsp/backlog/ — 11 done

    (001–007 the LSP+MCP arc; 008–011 the 2026-05-29 k-evolve round: koder.toml, MCP HTTP lifecycle, documentSymbol, README sync).

See also

  • engines/sdk/koder-design-lsp/README.md — developer how-to
  • engines/sdk/koder-design-lsp/koder.toml — Stack-convention metadata
  • meta/docs/stack/modules/design-gen.md — the write half of KDS