A Go library for building Language Server Protocol servers. It handles JSON-RPC framing, message dispatch, and LSP type definitions so you can focus on your language logic.

This library targets LSP 3.17. The table below shows which parts of the specification are currently supported.

go get github.com/owenrumney/go-lsp

Define a handler struct that implements server.LifecycleHandler and any optional interfaces you need, then pass it to NewServer:

package main

import (
	"context"
	"os"

	"github.com/owenrumney/go-lsp/lsp"
	"github.com/owenrumney/go-lsp/server"
)

type Handler struct{}

func (h *Handler) Initialize(ctx context.Context, params *lsp.InitializeParams) (*lsp.InitializeResult, error) {
	return &lsp.InitializeResult{
		Capabilities: lsp.ServerCapabilities{
			HoverProvider: &lsp.HoverOptions{},
		},
	}, nil
}

func (h *Handler) Shutdown(ctx context.Context) error {
	return nil
}

func (h *Handler) Hover(ctx context.Context, params *lsp.HoverParams) (*lsp.Hover, error) {
	return &lsp.Hover{
		Contents: lsp.MarkupContent{
			Kind:  lsp.MarkupKindMarkdown,
			Value: "Hello from the server",
		},
	}, nil
}


func main() {
	srv := server.NewServer(&Handler{})

	if err := srv.Run(context.Background(), server.RunStdio()); err != nil {
		os.Exit(1)
	}
}

The server accepts any io.ReadWriteCloser, so you can use it with stdio, TCP, WebSockets, or anything else:

// Stdio (most common for editors)
srv.Run(ctx, stdRWC{})

// TCP
ln, _ := net.Listen("tcp", ":9999")
conn, _ := ln.Accept()
srv.Run(ctx, conn) // net.Conn implements io.ReadWriteCloser

// WebSocket (using nhooyr.io/websocket)
ws, _ := websocket.Accept(w, r, nil)
srv.Run(ctx, websocket.NetConn(ctx, ws, websocket.MessageText))

The server automatically advertises capabilities based on which interfaces your handler implements. If your handler satisfies HoverHandler, the server tells the client it supports hover -- you don't need to wire that up yourself. You can still set capabilities explicitly in Initialize if you need finer control; explicit values take precedence.

LifecycleHandler is the only required interface. Everything else is opt-in: implement the interface on your handler struct and the server registers the corresponding LSP method automatically.

After the server starts, srv.Client is available for sending notifications and requests back to the editor:

// Publish diagnostics for a file
srv.Client.PublishDiagnostics(ctx, &lsp.PublishDiagnosticsParams{
	URI:         "file:///path/to/file.go",
	Diagnostics: diagnostics,
})

// Show a message popup in the editor
srv.Client.ShowMessage(ctx, &lsp.ShowMessageParams{
	Type:    lsp.MessageTypeInfo,
	Message: "Indexing complete",
})

// Write to the editor's log output
srv.Client.LogMessage(ctx, &lsp.LogMessageParams{
	Type:    lsp.MessageTypeLog,
	Message: "processed 42 files",
})

// Report progress
srv.Client.Progress(ctx, &lsp.ProgressParams{
	Token: "indexing",
	Value: progressValue,
})

// Show a message with action buttons (request/response)
item, err := srv.Client.ShowMessageRequest(ctx, &lsp.ShowMessageRequestParams{
	Type:    lsp.MessageTypeInfo,
	Message: "Restart server?",
	Actions: []lsp.MessageActionItem{{Title: "Yes"}, {Title: "No"}},
})

// Ask the editor to show a document
result, err := srv.Client.ShowDocument(ctx, &lsp.ShowDocumentParams{
	URI: "file:///path/to/file.go",
})

You can register custom JSON-RPC methods and notifications for server-specific extensions:

srv := server.NewServer(&handler{})

// Custom request method
srv.HandleMethod("custom/myMethod", func(ctx context.Context, params json.RawMessage) (any, error) {
	var p MyParams
	if err := json.Unmarshal(params, &p); err != nil {
		return nil, err
	}
	return MyResult{Value: "hello"}, nil
})

// Custom notification
srv.HandleNotification("custom/myNotification", func(ctx context.Context, params json.RawMessage) error {
	// handle notification
	return nil
})

srv.Run(ctx, rwc)

Custom handlers must be registered before calling Run.

The server supports structured logging via log/slog. Pass a logger with the WithLogger option:

srv := server.NewServer(&handler{}, server.WithLogger(slog.Default()))

When enabled, the server logs:

If no logger is set, no logging is performed. Use any slog.Handler — JSON for production, text for development:

// JSON to stderr
logger := slog.New(slog.NewJSONHandler(os.Stderr, nil))
srv := server.NewServer(&handler{}, server.WithLogger(logger))

// Debug-level text output
logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelDebug}))
srv := server.NewServer(&handler{}, server.WithLogger(logger))

The servertest package provides a test harness that simulates an LSP client over in-memory pipes. It handles JSON-RPC framing, initialization, and cleanup automatically:

func TestHover(t *testing.T) {
    h := servertest.New(t, &myHandler{})

    h.DidOpen("file:///test.txt", "plaintext", "hello world")

    hover, err := h.Hover("file:///test.txt", 0, 5)
    if err != nil {
        t.Fatal(err)
    }
    // assert on hover.Contents
}

The harness collects server-to-client notifications (diagnostics, messages) so you can assert on them:

h.DidSave("file:///test.txt")

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

diags, err := h.WaitForDiagnostics(ctx, "file:///test.txt")

See the testing guide for the full API.

The library includes an optional debug UI that captures all LSP traffic and displays it in a web interface. This is useful for inspecting the messages flowing between client and server during development.

Enable it with the WithDebugUI option:

srv := server.NewServer(&Handler{}, server.WithDebugUI(":7100"))
srv.Run(ctx, server.RunStdio())

Then open http://localhost:7100 in a browser. The tap is transparent -- it intercepts LSP frames for display without modifying them.

Real-time view of all JSON-RPC traffic between client and server:

• Request/response pairing -- responses are matched to their originating request with latency displayed inline
• Direction and type filters -- narrow the list to client-to-server, server-to-client, requests, or notifications
• Full-text search across methods and JSON bodies (including paired responses)
• Pretty-printed detail pane -- click any message to see the full JSON with syntax formatting

Aggregated log output with level filtering (error, warning, info, log). window/logMessage notifications are automatically cross-posted here. Supports search and CSV export.

Waterfall view of request latency, grouped by method:

• Each method gets a single row with all its request bars laid out on a time track
• Bars are color-coded: green (<100ms), orange (100ms--1s), red (>1s), animated blue stripes (pending)
• Minimap header with time axis ticks -- click or drag to scroll to a point in time
• Zoom in/out to adjust the time scale
• Click any bar to jump to that message in the Messages tab

Runtime metrics updated every 2 seconds: uptime, heap usage, goroutine count, GC runs, request/response/notification counts, and average latency.

Method sparklines appear below the stats bar once latency data is available, showing an inline SVG chart of the last 50 latency samples per method (top 10 by volume).

• Capabilities panel -- slide-out panel showing which LSP capabilities the server advertised during initialization
• Dark / light theme -- toggle between Catppuccin Mocha (dark) and Catppuccin Latte (light) themes, persisted in localStorage

The library is split into four packages:

• server -- The Server that ties it together: accepts a handler, registers LSP methods based on the interfaces it implements, and manages the connection lifecycle.
• lsp -- Go types for LSP structures (capabilities, params, results, enums). No logic, just data definitions.
• servertest -- Test harness that simulates an LSP client over in-memory pipes for writing unit tests.
• internal/jsonrpc -- JSON-RPC 2.0 framing over an io.ReadWriteCloser, with method and notification dispatch.