Build Server Protocol (BSP) is an Apache-2.0 protocol that lets IDEs and build tools communicate about compile, run, test and debug operations, and it is aimed at tooling developers who build editors, language servers and build tools rather than at end users who want a finished application.

What it is

Build Server Protocol is a specification and a set of support libraries, written primarily in Scala and built on JSON-RPC, that defines how a language server or editor talks to a build tool. The effort is led by the Scala Center together with tooling developers in the Scala ecosystem and beyond, with current maintainers Adrien Piquerez of the Scala Center and Łukasz Wawrzyk of VirtusLab, and former maintainers drawn from JetBrains, Lunatech and the Scala Center. The specification text, the documentation and the support libraries for some supported languages are automatically generated from a Smithy model held in the repository at spec/src/main/resources/META-INF/smithy/bsp/bsp.smithy.

The concrete problem it solves is the integration gap between editors and build tools. Before BSP, every editor or language server that wanted to know a project's source layout, compile a target, run a test suite or attach a debugger had to reach its own agreement with each build tool, producing duplicated and divergent integrations. BSP replaces those bespoke, point-to-point integrations with one protocol in which a build server exposes targets, sources, compile, test and run operations, and any conforming client can consume them. Although the protocol currently focuses on Scala developer tools, its design is explicitly language-agnostic, and the repository has begun adding extensions for other ecosystems.

Key capabilities

• A JSON-RPC protocol covering compile, run, test and debug operations between build tools and language servers or editors.
• Specification, docs and per-language support libraries generated from the Smithy model at spec/src/main/resources/META-INF/smithy/bsp/bsp.smithy.
• Optional environment variable and working directory parameters on buildTarget/run and buildTarget/test requests, replacing the argument and environment lists previously carried on ScalaMainClass and ScalaTestSuites.
• A buildToolParams field added to compile, test and run requests.
• Streaming output and input notifications in the unreleased 2.2.0 changelog: run/printStdout, run/printStderr and run/readStdin.
• An originId field on TaskStartParams, TaskProgressParams and TaskFinishParams, with deprecation of the same field in CompileReport and TestReport, so clients can distinguish multiple reports for one target.
• Protocol extensions for Rust and for cargo, plus diagnostic structures updated to match LSP 3.17.
• An optional data field on SourceItem.

Who uses it and how

• Editor and IDE plugin developers who need their client to query a build tool for targets, sources and classpath without writing a separate integration per build tool.
• Language server authors in the Scala ecosystem, where the protocol's current tooling and support libraries are most developed.
• Build tool authors who implement BSP on the server side and expose compile, test and run operations through a single JSON-RPC endpoint.
• Tooling teams spanning organisations, as shown by the maintainer history across the Scala Center, VirtusLab, JetBrains and Lunatech.
• Rust and cargo tooling developers, following the newer protocol extensions.

Getting started

The entry point is the published specification at https://build-server-protocol.github.io/docs/specification, which is generated from the Smithy model. Contributors are directed to CONTRIBUTING.md and to the project's Discord server for discussion.

How it compares

BSP sits alongside the Language Server Protocol rather than competing with it: LSP carries editor-facing features such as diagnostics, which BSP aligns with in LSP 3.17, while BSP carries the build knowledge that LSP does not model. Both protocols share a JSON-RPC foundation, so a client already speaking LSP will recognise the transport and message shapes. Editors generally need both, with BSP supplying targets, compiles, tests and runs to the language server that LSP drives.

When to use it — and when not to

Adopt BSP when building an editor, language server or build tool that must exchange compile, test, run and debug information in a tool-agnostic way; the cost is implementing or consuming a JSON-RPC protocol whose specification is machine-generated from a Smithy model. It is the wrong choice for anyone who wants a ready-made build tool or IDE feature out of the box, because the project ships a specification, generated docs and support libraries rather than an installed product. Note also that version 2.2.0 is still marked unreleased in the changelog, the current focus remains Scala tooling despite the language-agnostic design, and the repository carries 40 open issues.