# Metals, the Scala language server whose front page explains none of it

> Metals is the Scala language server built from Scalameta's Meta and the Language Server protocol, an LSP backend split across four mtags modules plus a metals-mcp/ module the README never mentions. Its front page documents no install command and delegates every mechanic to the project website.

**scalameta/metals** — Scala language server with rich IDE features 🚀 

- Repository: https://github.com/scalameta/metals
- Website: https://scalameta.org/metals/
- Stars: 2,335 · Forks: 448
- Language: Scala
- License: Apache-2.0
- Published: 2026-10-14 · Updated: 2026-10-14 · Language: en
- Canonical page: https://hysenlabs.com/projects/scalameta-metals

## A language server named for two halves of Scalameta

The name is the argument. Metals is Meta from Scalameta plus LS from Language Server, and the repository description calls the project a Scala language server with rich IDE features. The code sits between an editor and the Scala toolchain rather than inside one vendor product, which is why the repository's own topic list carries lsp and language-server next to ide, scala and scalameta. The primary language is Scala, the default branch is main, and the homepage is scalameta.org/metals/.

The audience is a team that writes Scala and wants to pick its own editor. The front page narrows that no further and widens it no further either. There is no support matrix, no list of editors with a client, and no statement of which Scala versions are covered. One audience does get addressed directly, and it is not the users: contributors, through the regular online events the README calls the Scala Tooling Spree and a contributing guide hosted on the project site. No commercial support path is named, which is the sort of gap that matters most for a tool teams are asked to depend on daily.

## The README is a link directory and the manual is elsewhere

The whole Documentation section is one line: see the website. The same pattern repeats twice more. The contributing guide sits at scalameta.org/metals/docs/contributors/getting-started.html, and maintainers, sponsors and acknowledgements sit on a third address under the same domain. Take the section headings in order and the front page offers documentation, contributing, acknowledgements, alternatives and a two-line etymology. Not one of them contains a configuration key, a protocol flow or a file layout.

The repository carries a second documentation surface that the front page never mentions. At the top level sit docs/, metals-docs/ and website/, next to architecture.md, CONTRIBUTING.md and AGENTS.md. The README does point at architecture.md and tells you to skim it, because that file explains the high-level layout of the source code, and saying so makes the gap sharper rather than softer. The one file in the repository that explains how the code is arranged is recommended inside a README that hands documentation to the website. A contributor who works offline, or a reviewer checking a pull request, has to reconstruct the design from the source tree instead.

## The tree splits into four mtags modules and four metals modules

Layout is where Metals stops being a description and becomes a codebase. The top level divides into a family of four modules sharing the mtags prefix and a family of four sharing the metals prefix, with the sbt-side plugin sitting alongside them.

```text
metals/
metals-mcp/
metals-bench/
metals-docs/
mtags/
mtags-java/
mtags-shared/
mtags-interfaces/
sbt-metals/
```

Four names carry the mtags prefix: a plain core, a Java-facing sibling, a shared sibling and an interfaces sibling. Putting mtags-interfaces/ in its own module rather than inside mtags/ tells you the boundary between what a client sees and what the backend keeps internal is drawn on purpose. sbt-metals/ at the same level is the piece named after the server itself, and build.sbt, project/ and tests/ complete the picture of an ordinary sbt project. None of that division appears in prose on the front page, and architecture.md is the only pointer given.

What the module names do not settle is where the work is split between them. Which parts of the Scala toolchain the mtags family owns, and which parts metals/ takes, is left to a reader of the source.

## metals-mcp/ ships in the tree and never reaches the README

A module named metals-mcp/ occupies a top-level slot, and neither the front page nor the topic list touches it. The description promises rich IDE features, the Why Metals? section expands the name in one line, and the Documentation section sends you to the website, so the protocol angle of that module is invisible from the README alone. A sibling called metals-bench/ sits next to it with the same problem: no sentence on the front page states what it is or who runs it.

The gap reads strangely next to AGENTS.md, which occupies the same top level. An instructions file for automated coding agents and a module named metals-mcp/ in one repository is a pairing a careful reader would notice, and nothing in the README connects the two. What metals-mcp/ does, which protocol it speaks, whether it is enabled by default and whether it is stable all sit on the website, and the README stays silent in both directions. Nobody should read that front page and conclude the repository lacks the piece.

## Two scalafix configs, one scalafmt config and three bots

The dotted files carry more information about how this project is worked on than any paragraph of the front page. Eleven dotted entries sit at the top level against five capitalised ones. Formatting is `.scalafmt.conf`. Linting is configured twice, in `.scalafix.conf` and `.scalafix3.conf`, two configs for one tool at two generation numbers. `.scala-steward.conf` sits beside them for dependency updates, and `.git-blame-ignore-revs` sits beside that, a file whose only job is keeping mass reformat commits out of blame.

Then the automation. `.coderabbit.yaml`, `.mergify.yml` and `.scala-steward.conf` are three separate bots covering automated review, branch merging and dependency bumps, with `.github/` holding workflow definitions the README never describes. `.jvmopts` and `.gitattributes` finish the local tooling set, and `bin/` sits next to `project/` without a word of explanation anywhere.

Two of those details cost more than they look. A duplicated scalafix configuration means the lint story sits mid-migration, and no file in the README tells a newcomer which config to change. A `.git-blame-ignore-revs` list in a repository this size is a standing tax on every future contributor, because history was rewritten wholesale at some point and every blame line a newcomer follows is filtered through that list.

## No install command appears anywhere on the front page

The honest tutorial is short. The README gives no installation command, no package name to install and no editor plugin to download, and it names no binary either. It does give two addresses, and both are the project's own site.

```text
https://scalameta.org/metals/
https://scalameta.org/metals/docs/contributors/getting-started.html
```

What you can act on without leaving the source is the repository itself. build.sbt at the top level makes this an sbt project, project/ holds the build definition, and sbt-metals/ is the module named after the server. The README does not document how sbt-metals/ is published, which sbt version it targets, or how an editor is told to start the server, so a first real use ends at the website.

Three things are worth verifying there before anyone adopts this. Which editors ship a client. How the server is launched against a build. And how sbt-metals/ connects to the mtags family at runtime. None of the three answers exists in the repository, and a team that plans its editor rollout from the front page alone will find no command to run.

## The alternatives list names one rival and its differentiator

The Alternatives section holds exactly one entry, and it is not a comparison table. IntelliJ IDEA is called the most widely used IDE for Scala using a re-implementation of the Scala typechecker. That one clause is the entire stated difference in approach: one project presents itself as a language server, the other as an IDE carrying its own typechecker.

This is where the repository description and the repository front page pull apart. The description claims rich IDE features, while the only rival named on the page is a different IDE that the same page calls the most widely used one for the language. Neither statement carries a measurement, and no latency, accuracy or feature matrix appears anywhere in the files a reader gets from the repository.

The gap that matters when choosing is the typechecker. A team that wants one Scala toolchain shared between editor and build gets that from a server attached to the build. A team that wants a self-contained IDE that answers questions without loading the build gets that from a re-implementation. Metals makes no argument for itself on either count, because no file in the repository makes it.

## Two codenames moving on the same afternoon in September

Version naming carries the shape of the plan. Three tags carry one day, 2026-09-14: v2.0.0-M18 Gold at 11:27:54Z, v2.0.0-M19 Gold at 12:02:59Z and v1.6.9 Osmium at 17:52:01Z, a stable line and a milestone line moving within six hours of each other. The repository is not archived, and the last push landed on 2026-09-28 at 13:26:30Z under Apache-2.0, so the tree holds two weeks of work made after that afternoon.

What the code does with the milestone line is undocumented. Nothing in the README states what a Gold milestone means for behaviour, how far the 2.0.0 line sits from becoming the default, or whether an editor should be pinned to 1.6.9 while the milestones settle. There is no upgrade note, no compatibility table and no migration guide in the repository, only architecture.md for layout and the website for behaviour.

The human side is as thin and as explicit. The README names the Scala Tooling Spree as the recurring event for anyone interested in contributing to Scala tooling, points the contributing guide at the site, and defers maintainers, sponsors and acknowledgements to a third page. A repository with more than thirty top-level entries, three bots and an AGENTS.md file keeps its process on that site, and the front page summarises none of it.

## Conclusion

Metals fits a Scala team that wants its editor choice back and is willing to read the project site before touching anything, and it does not fit anyone who expects a repository to answer setup questions, because the front page carries no install command and passes over two shipped modules. Verify architecture.md first, then check the editor client, the mtags module split and the milestone line against the version your build pins, and hold an editor rollout until the website has answered all three.

## FAQ

### What is Metals and who is it for?

Metals is a Scala language server, the name standing for Meta from Scalameta plus LS from Language Server, and it sits between an editor and the Scala toolchain over the lsp protocol. It is aimed at Scala developers who would rather choose their editor than adopt one IDE.

### How do I install Metals?

The README gives no installation command, package name or plugin download, and sends readers to scalameta.org/metals/ instead. The repository is an sbt project with build.sbt at the top level, project/ for the build definition and a module named sbt-metals/.

### What is the metals-mcp module in the repository?

A directory named metals-mcp/ occupies a top-level slot next to metals/ and metals-bench/. Neither the README nor the six repository topics mention it, and no file in the README states what it does or which protocol it speaks.

### How does Metals compare with IntelliJ IDEA?

The README lists one alternative, IntelliJ IDEA, described as the most widely used IDE for Scala using a re-implementation of the Scala typechecker. That comparison is the whole Alternatives section, with no feature table, latency figure or accuracy result attached to it.

### Is Metals still being worked on?

The repository is not archived, and the last push was on 2026-09-28 at 13:26:30Z. Tags for v1.6.9 Osmium, v2.0.0-M19 Gold and v2.0.0-M18 Gold all carry the date 2026-09-14.

### Why are there two scalafix config files?

The top level carries .scalafix.conf and .scalafix3.conf beside .scalafmt.conf, and no README sentence says which one is current. A .git-blame-ignore-revs file in the same list exists to keep mass reformat commits out of blame.

## Sources

- [License: Apache-2.0](https://github.com/scalameta/metals/blob/main/LICENSE)
- [Project website](https://scalameta.org/metals/)
- [README](https://github.com/scalameta/metals/blob/main/README.md)
- [Releases](https://github.com/scalameta/metals/releases)
- [scalameta/metals on GitHub](https://github.com/scalameta/metals)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/scalameta-metals