ScalaSemantic

ScalaSemantic helps AI understand your Scala code like the compiler does. Instead of asking an
agent to guess from text search (grep), you let it query compiler-emitted SemanticDB for exact symbols,
types, implicits, inheritance, usages, and call paths.

For a Scala developer, that means an agent can answer questions like:

• where a method is really used, without false matches from grep;
• which classes extend a trait or override a member;
• which given can satisfy a type;
• how one method can call another across the project.

It is exposed over MCP, so clients such as Claude Code, Codex, and
Gemini CLI can call it as a local tool while you keep using your normal Scala build.

📖 Documentation site: https://mercurievv.github.io/ScalaSemantic/ (mdoc-checked, so its code
samples are executed at build time).

Why, vs grep

grep matches characters; ScalaSemantic understands the compiled program.

Every capability is backed by a test that runs against this repo's own SemanticDB →
AnalyzerSuite.
Full trade-offs, including where grep wins:
docs/explanation/scala-semantic-vs-grep.md.

Quickstart

Your MCP client spawns the server over stdio. Two things are needed (only a JVM — no coursier, no sbt):

1. the target project compiled with SemanticDB (semanticdbEnabled := true);
2. MCP client config that launches the server with that project's root as its argument.

Pick one setup:

sbt plugin — recommended

Least manual: works on sbt 1 and sbt 2, enables SemanticDB, and generates MCP client config for you;
the jar arrives on first spawn.

// project/plugins.sbt — replace x.y.z with the latest release (see the badge / releases page)
addSbtPlugin("io.github.mercurievv" % "sbt-scalasemantic-mcp" % "x.y.z")
// build.sbt
enablePlugins(ScalaSemanticMcpPlugin)

Latest version: · GitHub releases

sbt mcpClientConfig prints the config; sbt mcpRun runs the server for testing. The default
mcpClient := "claude" emits .mcp.json-style JSON. Set mcpClient := "codex" for Codex
config.toml, mcpClient := "gemini" for Gemini CLI JSON, mcpClient := "cline" for Cline,
mcpClient := "roo" for Roo Code, mcpClient := "continue" for Continue YAML, or
mcpClient := "generic-json" for other MCP clients.

Any build tool / OS

• Auto-download launcher — curl -fsSL .../scripts/install.sh | sh (Windows: …ps1), then set
  your MCP client command to ~/.local/bin/scalasemantic-mcp. Fetches + caches the fat jar on first run.
• Plain java -jar — grab scalasemantic-mcp.jar from the
  latest release and run it directly.

Optional launcher flags — append to the MCP client args after the project root (the launcher
forwards them to the server; equivalent env vars in parentheses):

• --prefetch — download + cache the jar, then exit without serving.
• --log (SCALASEMANTIC_LOG) — log a tool call input to file.
• --log-output (SCALASEMANTIC_LOG_OUTPUT) — log a tool call output to file.

{
  "mcpServers": {
    "scala-semantic": {
      "command": "~/.local/bin/scalasemantic-mcp",
      "args": ["/abs/path/to/project", "--log", "--log-output"]
    }
  }
}

Full setup, generated config, and lifecycle:
docs/getting-started/integration.md.

Tools

Every tool takes a SemanticDB symbol string; call find_symbol first to get one from a plain name.
On initialize the server also sends instructions telling the agent to prefer these tools over
grep for Scala code questions. Results are lean by default (locations as uri:line:col,
signatures one line, empty fields omitted); pass "detailed": true to expand, and find_usages is
paged.

Supported Scala versions

There are two analysis paths, with different version coverage:

• Disk SemanticDB (primary path) — the server reads the *.semanticdb files your build emits,
  so it is largely compiler-version-agnostic: it works against any project that compiles cleanly with
  SemanticDB enabled. Cross-version behavior is enforced by tests — the analyzer is exercised against
  golden SemanticDB from Scala 2.13.* and 3.*.* (see
  docs/project/development.md).
• Presentation-compiler (live) path — used for position-local tools on an edited / uncompiled /
  broken in-memory buffer, before a clean compile exists on disk. This embeds Scala 3's own
  presentation compiler, which is version-locked to Scala 3.8.4 (the only PC build wired in today).
  In principle the Scala 3 compiler can parse older 3.* source, but no per-version PC switching ships
  yet, and Scala 2.13 is not supported on this path (Scala 3's compiler is not a Scala 2 compiler).

So: disk-based analysis covers 2.13.* + 3.*.*; the live broken-buffer path is Scala 3.8.4
only. The server itself runs on any JVM (java 11+); the target project's Scala version is independent.

Docs

• Documentation site — the rendered, mdoc-checked microsite
• Quickstart — shortest sbt setup path
• Integration — register with a client, sbt plugin, other build tools
• Tool reference — MCP tools, symbol grammar, request shape
• Examples — sample MCP queries and responses
• ScalaSemantic vs grep — trade-offs and measured context cost
• Development — module layout, build & test, cross-version testing
• Design decisions — implementation notes and future extension points
• Releasing — Sonatype Central release process

License

MIT