Metals v2

What is it all about?

Tomasz Godzik

VirtusLab

Maintainer of multiple Scala tools including Metals, Bloop, Scalameta, Munit, Mdoc and parts of the Scala 3 compiler.

Release officer for Scala LTS versions

Part of the Scala Core team as coordinator and VirtusLab representative

Part of the moderation team

What do I do?

Most prominent Metals issues

01

02

03

04

MBT - Metals Build Tool

Fast IDE features

Improved Java Support

05

Plans

06

Questions

Metals

Metals is a language server protocol server.

Uses Language Server Protocol to provide IDE features in any editor that implements the LSP client

Based on JSON RPC

Widely supported by multiple editors, de facto standard for most languages

Metals LSP Server

Metals is also a model context protocol server.

Model Context Protocol is similar, but it is designed to be used by LLM agents

Provide tools and other resources to improve LLM results.

Metals MCP Server

We talked about it last year

Metals most prominent problems

Worse Java support in mixed Scala/Java projects
IDE features only available after a successful build
Workspace symbol search delegated entirely to BSP — slow, incomplete, brittle
Large monorepo setups can have even worse issues

Most prominent problems

Main Metals v2 goal:

Make the IDE useful from the moment you clone a repo.

Main Metals v2 was worked on in Databricks by Ólafur Páll Geirsson, Iulian Dragos and others in the team.

"How many of you have waited 5+ minutes for IDE features after opening a project?"

Metals Build Tool symbol index
IDE Features available from the start
Better Java Language Support

Main changes

Each feature reinforces the others — together they make Metals viable for large, mixed-language monorepos.

Metals Build Tool

Wait! Another build tool!?

It's not really a build tool

It's about getting the minimal amount of information from the build to somewhere Metals can access it directly.

Symbol search depended on the BSP build server. We needed to connect to the build server (could be different from the build tool)

We had to wait to get all `src/main/scala` etc.

Before (current main)

Editor opened

Build import

(1-5 min)

Build import

Build server start (20s-2min)

Build import

Not imported

Already imported

Indexing

(30s - 3min)

Build import

Ready to serve requests

Build import

Compilation (30s - 10min)

Build import

Future (main-v2)

Self-contained index, zero build dependency. Can work as soon as it's indexed.

Future (main-v2)

Editor opened

Build import

(1-5 min)

Build import

Build server start (20s-2min)

Build import

Not imported

Already imported

Indexing

(30s - 3min)

Build import

Ready to serve requests

Build import

Compilation (30s - 10min)

Build import

How MBT works

git ls-files --stage

~200-300ms

Each file checked if modified by OID

Index each file using existing fast indexers

Create IndexedDocument

Overwrite existing index.mbt on close

Special IndexedDocument

Contains information about all found identifiers added to bloom filters and definitions in a separate collection.

This is enough for navigation.

For references it's used together with the presentation compiler for correctness.

Bloom filters

  Query: "UserSer"
        │
        ├─ File A → MAYBE match → compile it
        ├─ File B → NO match    → skip         
        ├─ File C → NO match    → skip
        └─ File D → MAYBE match → compile it

  Result: only 2 of 4 files opened instead of all 4

Bloom filters

At scale (10k+ files), this means orders of magnitude fewer files scanned.

  Query: "UserSer"
        │
        ├─ File A → MAYBE match → compile it
        ├─ File B → NO match    → skip         
        ├─ File C → NO match    → skip
        └─ File D → MAYBE match → compile it

  Result: only 2 of 4 files opened instead of all 4

MBT features

Feature	How MBT helps
Workspace Symbol	Primary provider
Find References	Pre-filter via Bloom filters → only scan candidates
Find Implementations	Walks inheritance graph (depth ≤ 10) from index
Go to Definition	Fallback when classpath has no entry (pre-build)
Protobuf support	`.proto` files indexed alongside `.scala` and `.java`

Protobuf Support via mbt

No separate Protobuf language server needed.

Very simple indexing in most cases

// ← appears in workspace/symbol
message TextDocuments { 
  // ← go-to-definition soon supported
  repeated TextDocument documents = 1; 
}

message TextDocument {
  reserved 4, 8, 9;
  Schema schema = 1;
  string uri = 2;
}

No startup time IDE - interactive features

git clone

Full IDE:

Hover
Complete
Navigate
References

Build import

Open editor

Ideal scenario

If we don't have anything we put all sources into the presentation compiler.

This means that even in projects with broken build tool you should be able to work on your code.

How does it work?

And it does work in a lot of cases.

How does it work?

With caveats.

How does it work?

And it does work in a lot of cases.

The Scala presentation compiler accepts a `-sourcepath` flag that lets it resolve symbols directly from source files rather than requiring compiled class files on the classpath.

Scala compiler -sourcepath option

The fallback Scala compiler now receives the full source path of the project, including sources from transitive dependencies — not just direct ones.

This means the fallback compiler can resolve most symbols even in a large multi-module project without any compiled output.

Presentation compiler fallbacks

Two improvements make it possible.

Files are pre-parsed to identify the package within each file.
The compiler then asks the created structure when loading symbols.
It uses it to find out which files it needs to compile from a specific package.

Everything is lazy

package org.myorg.core

import org.myorg.util.Helper

object Main {
  Helper.printMessage(
    "Hello London!"
  )
}

package org.myorg.util

import org.myorg.util.Helper

object Helper {
  def printMessage(msg: String): Unit = {
    val message = "<info>" + msg
    println(message)
  }
}

package org.myorg.services

object Service {
  def execute(): Unit = {
    // very complicated code ...
  } 
}

org.myorg.core -> Main.scala

org.myorg.util -> Helper.scala

org.myorg.services -> Service.scala

Everything is lazy

package org.myorg.core

import org.myorg.util.Helper

object Main {
  Helper.printMessage(
    "Hello London!"
  )
}

package org.myorg.util

object Helper {
  def printMessage(msg: String): Unit = {
    val message = "<info>" + msg
    println(message)
  }
}

package org.myorg.services

object Service {
  def execute(): Unit = {
    // very complicated code ...
  } 
}

This file is ignored

This is compiled

When we edit this file

It's even more lazy

If we have explicit types for our methods there is no reason to compile the method itself if we are not in that specific file.

Please use ExplicitResults rules in scalafix, it helps the tools a lot!

Actual compiler view

package org.myorg.core

import org.myorg.util.Helper

object Main {
  Helper.printMessage(
    "Hello London!"
  )
}

package org.myorg.util

object Helper {
  def printMessage(msg: String): Unit = ???
}

Bodies are ignored

When we edit this file

Actual compiler view

package org.myorg.core

import org.myorg.util.Helper

object Main {
  Helper.printMessage(
    "Hello London!"
  )
}

package org.myorg.util

object Helper {
  def printMessage(msg: String): Unit = ???
}

When we edit this file

Bodies are ignored

Sourcepath helps with the current project, but we still need to know what are the dependencies for the project.

This is where another feature of mbt comes in and the reason it's a "build tool"

What about the dependencies

.metals/mbt.json

{
  "dependencyModules": [
    {
      "id": "com.google.guava:guava:30.0-jre",
      "jar": "/path/to/guava-30.0-jre.jar",
      "sources": "/path/to/guava-30.0-jre-sources.jar"
    }
  ]
}

Separate source of information

It's a very simple file format, we have extractors ready for Bazel, Maven and Gradle.

It can be setup for your project and updated similar to lock files.

Will make the experience work faster and better, you might not need a build server sometimes

Separate source of information

BSP dependency modules from the build server
Manually or automatically generated `.metals/mbt.json`
Heuristic scan of `.bloop/` or `.bazelbsp/` cached outputs (disabled by default)

Dependency fallback priority

This approach also works if we do have a full project structure

Results in completions and other features being up to date even with compilation issues

When does it help?

You can experiment with the new options

- workspaceSymbolProvider - mbt, bsp
- definitionProviders - protobuf, mbt
- javaSymbolLoader - javac-sourcepath, turbine-classpath
- javaTurbineRecompileDelay - 1.minute
- referenceProvider - bsp, mbt
- additionalPcChecks - [], [refchecks]
- scalaImportsPlacement - smart, append-last

Better Java support

One of the main goals in Metals 2 to was to make it viable for large mixed codebases.

Hence we needed to step up out Java support as well.

Java support

We decided to implement most of the basic features of LSP for Java.

No complex refactors, since most likely LLM era makes them redundant.

Java support

Feature	Status	Powered by.
Completions	✅	Presentation compiler
Hover	✅	Presentation compiler
Signature Help	✅	Presentation compiler
Diagnostics	✅	Presentation compiler
Semantic Highlighting	✅	Java Semanticdb
Selection Range	✅	Javac AST
Document Symbols	✅	Javac AST
Go to Definition	✅	SemanticDB + mbt
Find References	✅	mbt + Bloom filters

But how to make it efficient in large codebase?

We use google turbine which allows us to define stubs for each file without compiling method bodies.

We get in-memory classfiles which the javac compiler can use as a normal classpath

But how to make it efficient in large codebase?

Caveat: It does not support project Lombok or annotation processors currently.

Google Turbine

example/File.java (edited)

example/Other.java

...

Classfiles stubs: example/Other.class, example/Other2.class

File.java,

Google Turbine

Presentation compiler

Javac outline compiler, compiles the file fully

example/File.java (edited)

example/Other.java

...

Classfiles stubs: example/Other.class, example/Other2.class

File.java

Google Turbine

Presentation compiler

Javac outline compiler, compiles the file fully

Outline compiler, compiles without method bodies

AlsoEdited.java

By default turbine will run every minute, so we are back to classfiles once that completes

Google Turbine

Why not just `-sourcepath`?

Edit Foo.java

javac resolves Bar (from sourcepath)

Bar references Baz → compile Baz too

Baz references Qux → compile Qux...

💥 500 files compiled for one edit

Why not just `-sourcepath`?

Sourcepath will still be used for any broken files and any changed files within last minute.

We still prefer to depend on fully compiled workspace as it's more efficient.

Overall, the approach in Java is very much similar to what we have in Scala.

The main difference is the inclusion of Google Turbine.

Java Support

Plans

Port upstream v1 changes (v1.5.2+) - new features and bugfixes
Scala 3 validation - making sure that Scala 3 works correctly also with sourcepath.
Stabilization - test across all build tools, not just Bazel/Bloop.
Documentation - configuration guide for all new options, make sure config is up to date.

What's left?

A lot was done to improve Bazel support:

- source jar as roots;

- handling large BSP messages;

But a lot of this was done with internal Bazel BSP server inside Databricks.

We're working on our own Scala based inlined inside Metals.

Bazel Improvements

We are happy to work with you to improve your workflow

Via contracts if needed, but usually just happy to help

Summary

Java Support

mostly feature complete
turbine
outline compiler

Fast IDE features

sourcepath fallback
mbt fallback
better crash resilience

MBT Index

bloom filters
protobuf
persists to disk
can use mbt.json

How do I actually use it?

Build from source on main-v2

or

metals.serverVersion : "2.0.0-M8"

Thank You

Tomasz Godzik

Bluesky: @tgodzik.bsky.social

Mastodon: fosstodon.org/@tgodzik

Discord: tgodzik

Metals v2

What do I do?

01

02

03

04

05

06

Metals

Metals is a language server protocol server.

Metals LSP Server

Metals is also a model context protocol server.

Metals MCP Server

We talked about it last year

Metals most prominent problems

Most prominent problems

"How many of you have waited 5+ minutes for IDE features after opening a project?"

Main changes

Metals Build Tool

Wait! Another build tool!?

It's not really a build tool

Before (current main)

Before (current main)

Future (main-v2)

Future (main-v2)

How MBT works

Special IndexedDocument

Bloom filters

Bloom filters

At scale (10k+ files), this means orders of magnitude fewer files scanned.

MBT features

Protobuf Support via mbt

No startup time IDE - interactive features

Ideal scenario

How does it work?

How does it work?

How does it work?

Scala compiler -sourcepath option

Presentation compiler fallbacks

Two improvements make it possible.

Everything is lazy

Everything is lazy

Everything is lazy

It's even more lazy

Actual compiler view

Actual compiler view

What about the dependencies

Separate source of information

Separate source of information

Dependency fallback priority

When does it help?

You can experiment with the new options

Better Java support

Java support

Java support

But how to make it efficient in large codebase?

But how to make it efficient in large codebase?

Google Turbine

Google Turbine

Why not just `-sourcepath`?

Why not just `-sourcepath`?

Java Support

Plans

What's left?

Bazel Improvements

We are happy to work with you to improve your workflow

Via contracts if needed, but usually just happy to help

Summary

How do I actually use it?

Thank You

Tomasz Godzik

tgodzik@virtuslab.com

Some links:

https://www.anthropic.com/engineering/code-execution-with-mcp