Skip to main content

Metals v1.6.6 - Osmium

· 15 min read
Tomasz Godzik
Tomasz Godzik

We're happy to announce the release of Metals v1.6.6, which brings a standalone MCP server for AI-powered workflows, support for Play's Twirl templates, easier access to compiler explain output, and an option to shut down the build server when closing your editor.

Commits since last release72
Merged PRs72
Contributors8
Closed issues14
New features5

For full details: https://github.com/scalameta/metals/milestone/85?closed=1

Metals is a language server for Scala that works with VS Code, Cursor, Vim, Emacs, Zed, Helix and Sublime Text. Metals is developed at the Scala Center and VirtusLab with the help from contributors from the community.

TL;DR​

Check out https://scalameta.org/metals/, and give Metals a try!

Allow users to get the output of -explain​

When the Scala compiler suggests using the -explain option to get more detailed error messages, it isn't exactly easy to do so. You would have to change your build configuration, which might require rebuilding the entire project.

Metals now offers two ways to access explain output:

  • With virtual documents support: When your editor supports virtual documents, Metals replaces the code description with a link that invokes a command to get diagnostics from the presentation compiler with -explain enabled.

explain-diagnostic

  • Without virtual documents: If your editor doesn't support virtual documents, Metals shows a code action that, when invoked, creates a new document in the .metals/explained-diagnostics directory with the full diagnostic output from -explain. Some editors might not open the new file automatically.

explain-diagnostic2

Standalone MCP server​

Metals now includes a standalone MCP (Model Context Protocol) server that can run independently of your editor. This allows AI-powered tools like Cursor, Claude Code, or other MCP clients to interact with your Scala project without needing the full Metals language server running inside an IDE.

The standalone server runs over HTTP and automatically imports the workspace when a project is detected. Several improvements make it easier to configure:

A standalone MCP (Model Context Protocol) server for Scala projects.

Usage:
  metals-mcp --workspace <path> [options]

Options:
  --workspace <path>      Path to the Scala project (required)
  --port <number>         HTTP port to listen on (default: auto-assign)
  --transport <type>      Transport type: http (default) or stdio (reserved for future use)
  --client <name>         Client to generate config for: Visual Studio Code, Visual Studio Code - Insiders, VSCodium, vscode, VSCodium - Insiders, Kilo, kilo, Cursor, cursor, claude, Claude Code, claude-code
  --<key> [value]         UserConfiguration override. Use kebab-case (e.g. --java-home /path, --bloop-version 1.4.0).
                          For boolean options, value is optional: omit for true, or use --key true/false.
  --help, -h              Show this help message
  --version, -v           Show version information

Examples:
  # Start MCP server for a project
  metals-mcp --workspace /path/to/project

  # Start with specific port
  metals-mcp --workspace /path/to/project --port 8080

  # Override Java home and enable default BSP to build tool (boolean, omit = true)
  metals-mcp --workspace /path/to/project --java-home /path/to/jdk --default-bsp-to-build-tool

  # Generate config for Cursor editor
  metals-mcp --workspace /path/to/project --client Cursor

  • Client configuration: When you specify --client (e.g. --client cursor), Metals generates the appropriate MCP configuration for supported clients, making setup straightforward for command-line tools.
  • User configuration in CLI: You can pass Metals configuration options directly via the command line using --<key> <value> syntax, including nested keys and boolean flags. This lets you customize the MCP server behavior independently of your editor.

You should be able to install the standalone MCP server using Coursier:

cs install metals-mcp

or Homebrew:

brew install metals

Add an option to shutdown Bloop build server​

A long-standing request was to terminate the Bloop process when closing the editor, so you don't end up with leftover build server processes running in the background if you didn't need it anymore.

Metals now provides the build-disconnect-and-shutdown LSP command. When invoked, it disconnects from the build server and shuts it down so the process exits. Visual Studio Code will use this command if you set the metals.shutdownBloopOnEditorClose configuration option to true. It will try to track the number of open VS Code instances and only exit if there are no more open instances.

It's important to note that this doesn't work with any other BSP server other than Bloop.

Thanks to thomasGuerin3 for implementing this feature!

Support for Play's Twirl templates​

Metals now has LSP support for Play Framework's Twirl template files (.scala.html, .scala.txt, .scala.xml, .scala.js). This work was done as part of Google Summer of Code 2025.

The IDE features for Twirl templates include:

  • Hover: See documentation and type information when hovering over symbols
  • Completions: Get code completions for Scala expressions within templates
  • Go to definition: Navigate from template code to Scala definitions
  • Auto-import: Automatically add imports when using completions
  • Rename: Rename symbols with proper updates across the template
  • Document highlighting: See all occurrences of the symbol currently under the cursor in a single file

twirl

Metals compiles Twirl templates in-memory and maps positions between the template source and the generated Scala code, so all these features should work correctly within the template syntax.

Thanks to ajafri2001 for implementing this feature and to zielinsky for finishing the work!

New File Improvements​

When using "New Scala File" or "New Java File" commands, Metals will now automatically strip extensions from the file name if they are provided. Additionally, there is a new type of new file which will take the current copied snippet and insert it into the new file with the suggested name.

new-file

As this requires access to the clipboard, it's only available in the Visual Studio Code extension, which implements the new clipboard API.

Miscellaneous​

  • fix: reduce presentation compiler memory usage (#6967) krrish175-byte
  • improvement: Properly set minimum Bloop version instead of using newest to avoid unnecessary bloop server restart messages tgodzik
  • feat(mcp): Add smart fallback and module parameter for inspect, get-docs, get-usages li-nkSN
  • fix: Recompile worksheet on changes even if didFocus is not supported krrish175-byte
  • improvement: Add message on timeouts to simplify debugging for users tgodzik
  • bugfix: Make sure that cs or coursier is a coursier binary tgodzik
  • improvement: Add KiloCodeEditor client configuration cheleb

Contributors​

Big thanks to everybody who contributed to this release or reported an issue!

$ git shortlog -sn --no-merges v1.6.5..v1.6.6
    28	scalameta-bot
    23	Tomasz Godzik
     7	dependabot[bot]
     2	Krrish Biswas
     1	Olivier NOUGUIER
     1	Prince
     1	li-nkSN
     1	thomasGuerin3

Merged PRs​

v1.6.6 (2026-02-27)​

Full Changelog

Merged pull requests: