Lsp Builder

LSP Builder Skill

A step-by-step guide for building Language Server Protocol servers. Reference: LSP 3.17 specification.

When to Use This Skill

Use whenever a user asks to:

• Build a new language server or LSP implementation
• Add language features (hover, completion, go-to-definition, etc.) to an editor via LSP
• Debug or extend an existing LSP server
• Understand how LSP transport, capabilities, or features work

Architecture Overview

An LSP server is a process that communicates with a client (editor) using JSON-RPC messages over a transport layer. The protocol has three layers:

1. Transport — How bytes move between client and server (stdio, sockets, pipes)
2. Base Protocol — JSON-RPC message framing with Content-Length headers
3. Language Protocol — Semantic requests/responses (hover, completion, diagnostics, etc.)

Phase 1: Base Protocol Transport

Read references/specification.md sections on Base Protocol and Header Part.

The wire format is:

Content-Length: <byte-length-of-json>\r\n
\r\n
<json-rpc-message>

Requirements:

• Header is ASCII-encoded, terminated by \r\n
• Content is UTF-8 JSON-RPC 2.0
• Content-Length is mandatory; Content-Type defaults to application/vscode-jsonrpc; charset=utf-8

Implementation steps:

1. Open stdin/stdout (or socket) for bidirectional communication
2. Read headers until \r\n\r\n is found
3. Parse Content-Length value
4. Read exactly that many bytes as the JSON content
5. Parse JSON to determine message type (request, response, or notification)
6. Repeat

Message types:

Reference: Message Transport (Python)

import json
import sys

def read_message():
    """Read one JSON-RPC message from stdin using Content-Length framing."""
    headers = {}
    while True:
        line = sys.stdin.buffer.readline()
        if not line:
            return None  # EOF
        line = line.decode("ascii")
        if line == "\r\n":
            break
        name, value = line.strip().split(": ", 1)
        headers[name.lower()] = value
    content_length = int(headers["content-length"])
    body = sys.stdin.buffer.read(content_length)
    return json.loads(body.decode("utf-8"))

def write_message(msg):
    """Write one JSON-RPC message to stdout using Content-Length framing."""
    body = json.dumps(msg, separators=(",", ":")).encode("utf-8")
    header = f"Content-Length: {len(body)}\r\n\r\n"
    sys.stdout.buffer.write(header.encode("ascii"))
    sys.stdout.buffer.write(body)
    sys.stdout.buffer.flush()

Phase 2: Server Lifecycle

Read references/specification.md sections on Server Lifecycle.

The lifecycle sequence is strictly defined:

Client                          Server
  |                                |
  |--- initialize (request) ----->|
  |<-- initialize (response) -----|
  |--- initialized (notify) ----->|
  |                                |  (server is now ready)
  |                                |
  |  ... normal operation ...      |
  |                                |
  |--- shutdown (request) ------->|
  |<-- shutdown (response) -------|
  |--- exit (notify) ------------>|
  |                                |  (server exits)

initialize Request

Method: initialize

• Client sends capabilities and workspace info
• Server responds with its capabilities
• Must not send other requests/notifications before receiving initialize

InitializeParams (from client):

{
  "processId": 12345,
  "rootUri": "file:///path/to/workspace",
  "capabilities": { ... },
  "clientInfo": { "name": "VSCode", "version": "1.74.0" }
}

InitializeResult (server response):

{
  "capabilities": {
    "textDocumentSync": 1,
    "completionProvider": { "triggerCharacters": [".", ":"] },
    "hoverProvider": true,
    "definitionProvider": true,
    "referencesProvider": true,
    "documentSymbolProvider": true,
    "codeActionProvider": true,
    "documentFormattingProvider": true
  },
  "serverInfo": { "name": "my-lang-server", "version": "0.1.0" }
}

initialized Notification

Method: initialized

• Server can now register capabilities, send window/showMessage, etc.

shutdown and exit

• shutdown: Server returns null result. Must stop processing new requests.
• exit: Server exits with code 0 (success) or 1 (if shutdown wasn't received).

Reference: Lifecycle Dispatch (Python)

def main():
    shutting_down = False
    while True:
        msg = read_message()
        if msg is None:
            break
        method = msg.get("method")
        msg_id = msg.get("id")    # Notifications have NO id
        params = msg.get("params", {})

        if msg_id is None:
            # This is a NOTIFICATION (no response required)
            if method == "exit":
                return 0 if shutting_down else 1
            # Other notifications: "initialized", "textDocument/didOpen", etc.
            handle_notification(method, params)
            continue

        # This is a REQUEST (must send a response)
        if method == "shutdown":
            shutting_down = True
            write_message({"jsonrpc": "2.0", "id": msg_id, "result": None})
            continue
        result = handle_request(method, params)
        write_message({"jsonrpc": "2.0", "id": msg_id, "result": result})

Phase 3: Text Document Synchronization

Read references/specification.md sections on Text Document Synchronization.

The server MUST implement all three or none:

• textDocument/didOpen — Notification from client: document opened
• textDocument/didChange — Notification from client: content changed
• textDocument/didClose — Notification from client: document closed

These are notifications, not requests — they have no id. The server must NOT send responses to them.

Configure via textDocumentSync capability:

{
  "textDocumentSync": {
    "openClose": true,
    "change": 2
  }
}

change values:

• 0 (None): No sync
• 1 (Full): Send entire document content on each change
• 2 (Incremental): Send only changed ranges

Core Types

interface Position {
    line: uinteger;        // 0-indexed
    character: uinteger;   // 0-indexed UTF-16 offset by default
}

interface Range {
    start: Position;
    end: Position;
}

interface TextDocumentIdentifier {
    uri: DocumentUri;      // e.g. "file:///path/to/file.py"
}

interface TextDocumentItem {
    uri: DocumentUri;
    languageId: string;
    version: integer;
    text: string;
}

interface VersionedTextDocumentIdentifier extends TextDocumentIdentifier {
    version: integer | null;
}

Full Sync (change: 1)

The simplest approach. On each didChange, the client sends the entire document text:

{
  "textDocument": { "uri": "file:///foo.py", "version": 2 },
  "contentChanges": [{ "text": "entire document content here" }]
}

Server just stores contentChanges[-1]["text"].

Incremental Sync (change: 2)

The client sends only the changed range. The server must apply these edits to its in-memory copy:

{
  "textDocument": { "uri": "file:///foo.py", "version": 2 },
  "contentChanges": [{
    "range": {
      "start": { "line": 0, "character": 5 },
      "end": { "line": 0, "character": 10 }
    },
    "rangeLength": 5,
    "text": "world"
  }]
}

Reference: Incremental Sync Implementation (Python)

class DocumentStore:
    def __init__(self):
        self._docs = {}  # uri -> text

    def open(self, uri, text):
        self._docs[uri] = text

    def close(self, uri):
        self._docs.pop(uri, None)

    def apply_incremental(self, uri, changes):
        text = self._docs.get(uri, "")
        for change in changes:
            if "range" in change:
                text = self._apply_range(text, change)
            else:
                # Full content replacement
                text = change.get("text", text)
        self._docs[uri] = text

    @staticmethod
    def _apply_range(text, change):
        lines = text.split("\n")
        rng = change["range"]
        s_line = rng["start"]["line"]
        s_char = rng["start"]["character"]
        e_line = rng["end"]["line"]
        e_char = rng["end"]["character"]
        new_text = change.get("text", "")

        before = "\n".join(lines[:s_line])
        if s_line > 0:
            before += "\n"
        prefix = lines[s_line][:s_char] if s_line < len(lines) else ""
        suffix = lines[e_line][e_char:] if e_line < len(lines) else ""
        after = "\n".join(lines[e_line + 1:]) if e_line + 1 < len(lines) else ""

        result = before + prefix + new_text + suffix + after
        return result

    def get(self, uri):
        return self._docs.get(uri)

Position encoding: Lines are 0-indexed. Characters are 0-indexed UTF-16 offsets by default. Since 3.17, you can negotiate UTF-8 or UTF-32 via positionEncoding in capabilities.

Phase 4: Language Features

Each feature requires:

1. Server advertises the capability in initialize response
2. Server implements the handler for the corresponding method

Hover (textDocument/hover)

Return documentation for the symbol at a given position.

Capability: "hoverProvider": true Request: HoverParams with textDocument and position Response: Hover with contents (MarkupContent or MarkedString) and optional range

interface Hover {
    contents: MarkedString | MarkedString[] | MarkupContent;
    range?: Range;
}

interface HoverParams extends TextDocumentPositionParams {
    // textDocument: TextDocumentIdentifier
    // position: Position
}

Completion (textDocument/completion)

Provide code completions at a cursor position.

Capability:

"completionProvider": {
  "triggerCharacters": ["."],
  "resolveProvider": true,
  "completionItem": { "labelDetailsSupport": true }
}

Request: CompletionParams with textDocument, position, context Response: CompletionList with items[] and isIncomplete flag, or CompletionItem[]

Important: Always include triggerCharacters when advertising completionProvider — clients use this to know when to automatically request completions.

interface CompletionItem {
    label: string;
    kind?: CompletionItemKind;  // 1=Text, 2=Method, ..., 14=Keyword, 6=Variable, ...
    detail?: string;
    documentation?: string | MarkupContent;
    deprecated?: boolean;
    preselect?: boolean;
    sortText?: string;
    filterText?: string;
    insertText?: string;
    insertTextFormat?: InsertTextFormat;  // 1=PlainText, 2=Snippet
    textEdit?: TextEdit | InsertReplaceEdit;
    additionalTextEdits?: TextEdit[];
    commitCharacters?: string[];
    command?: Command;
    data?: LSPAny;
}

CompletionItemKind values (common):

Go to Definition (textDocument/definition)

Capability: "definitionProvider": true Request: DefinitionParams Response: Location, Location[], or LocationLink[]

interface Location {
    uri: DocumentUri;
    range: Range;
}

References (textDocument/references)

Capability: "referencesProvider": true Request: ReferenceParams with context.includeDeclaration Response: Location[]

Diagnostics (Push Model)

The server sends diagnostics to the client via textDocument/publishDiagnostics notification. No request is needed — the server pushes whenever diagnostics change.

Notification: PublishDiagnosticsParams with uri, version, and diagnostics[]

interface Diagnostic {
    range: Range;
    severity?: DiagnosticSeverity;  // 1=Error, 2=Warning, 3=Information, 4=Hint
    code?: integer | string;
    codeDescription?: { href: URI };
    source?: string;          // e.g. "my-lang-linter"
    message: string;
    tags?: DiagnosticTag[];   // 1=Unnecessary, 2=Deprecated
    relatedInformation?: DiagnosticRelatedInformation[];
    data?: LSPAny;
}

Document Symbols (textDocument/documentSymbol)

Capability: "documentSymbolProvider": true Response: DocumentSymbol[] (hierarchical) or SymbolInformation[] (flat)

interface DocumentSymbol {
    name: string;
    detail?: string;
    kind: SymbolKind;      // 5=Class, 12=Function, 13=Variable, 14=Constant, ...
    tags?: SymbolTag[];
    deprecated?: boolean;
    range: Range;          // Full range of this symbol (including body)
    selectionRange: Range; // Range that should be selected (the name)
    children?: DocumentSymbol[];
}

SymbolKind values (common):

Formatting (textDocument/formatting)

Capability: "documentFormattingProvider": true Request: DocumentFormattingParams with options (tabSize, insertSpaces, etc.) Response: TextEdit[]

interface TextEdit {
    range: Range;
    newText: string;
}

Code Actions (textDocument/codeAction)

Capability:

"codeActionProvider": {
  "codeActionKinds": ["quickfix", "refactor"]
}

Request: CodeActionParams with textDocument, range, context.diagnostics Response: (Command | CodeAction)[]

Other Features (implement as needed)

Phase 5: Workspace Features

Phase 6: Window Features (Server → Client)

These are notifications the server sends TO the client:

Error Handling

Use ResponseError with standard error codes:

-32700  Parse Error
-32600  Invalid Request
-32601  Method Not Found
-32602  Invalid Params
-32603  Internal Error
-32002  Server Not Initialized
-32800  Request Cancelled
-32801  Content Modified
-32802  Server Cancelled
-32803  Request Failed

Implementation Checklist

When building a server, work through this order:

1. Set up transport (stdio, socket, or pipe)
2. Implement header parsing (Content-Length based message framing)
3. Implement JSON-RPC message dispatch (request/notification/response routing)
4. Implement initialize handler with capabilities
5. Implement initialized handler
6. Implement shutdown and exit handlers
7. Implement text document sync (didOpen, didChange, didClose)
8. Implement at least one language feature (hover is simplest)
9. Implement diagnostics (push via textDocument/publishDiagnostics)
10. Add more language features as needed
11. Implement workspace features if applicable
12. Test with an LSP client (VS Code extension, Emacs lsp-mode, Neovim LSP)

Key References

Read references/specification.md for:

• Complete type definitions for every request/response/notification
• Detailed capability structures
• The full list of features with their client/server capability paths
• Registration options for dynamic capabilities
• Work done progress and partial result progress mechanisms
• Notebook document support (3.17)

Common Pitfalls

• Don't send requests before initialize — Clients will reject them
• Don't notify without being asked — Only send publishDiagnostics after document sync
• Positions are 0-indexed — Both line and character start at 0
• UTF-16 character offsets by default — Unless you negotiate UTF-8/UTF-32 via positionEncoding
• Every request needs a response — Even if returning null
• Notifications must NOT get responses — They have no id field. didOpen, didChange, didClose, initialized, exit are all notifications
• Cancellation returns error, not no response — Use RequestCancelled error code
• Always use Content-Length framing — Never read raw lines from stdin; use binary readline + exact byte reads
• Incremental sync needs careful position math — Convert 0-indexed line/character to string offsets before splicing