ScalaSemantic
ScalaSemantic is an MCP server that gives AI coding agents compiler-resolved Scala facts — exact symbols, types, inheritance, usages, implicits, and call paths — from compiler-emitted SemanticDB. Instead of grepping source text, agents query what the compiler already knows.
Works with Scala 2.13.* and 3.., any sbt/Mill/Gradle project, and any MCP-compatible agent (Claude Code, Codex, Gemini CLI, Cline, Roo Code, Continue…).
Quick setup
Needs only java. One command registers the server for your user, so every Scala project on the machine gets it:
curl -fsSL https://raw.githubusercontent.com/MercurieVV/ScalaSemantic/master/scripts/scalasemantic-mcp.sh | sh
Run it from a project root with --project to also enable SemanticDB, write the agent steering files and install the Claude guard hook. Re-running is safe:
curl -fsSL https://raw.githubusercontent.com/MercurieVV/ScalaSemantic/master/scripts/scalasemantic-mcp.sh | sh -s -- --project
iwr https://raw.githubusercontent.com/MercurieVV/ScalaSemantic/master/scripts/scalasemantic-mcp.ps1 -OutFile scalasemantic-mcp.ps1; .\scalasemantic-mcp.ps1 setup
Launcher, plain jar and logging: Integration. The optional guard hook denies grep/cat/Read on .scala files and points agents at the MCP tools; it is not installed by default.
Tools
find_symbol · find_usages · class_hierarchy · method_signature · members · resolve_implicits · call_path · type_at_position · hole_context · resolve_references · literal_tokens · contract_clauses · trace_implicit_chain · find_overloads — what each does, plus the symbol grammar: Tool reference.
For a shell hook or script that can't hold an MCP session open, scalasemantic-mcp call <tool> '<json-args>' [root] [classpath] runs one tool and prints its JSON result.
SemanticDB vs grep
| Question | Right tool |
|---|
| Exact callers of a method | find_usages |
| All subtypes of a trait | class_hierarchy |
Which given satisfies a type | resolve_implicits |
Call path from method a to c | call_path |
| Comments, TODOs, config files | grep |
| Code that hasn't compiled yet | grep |
Measured: semantic tools use ~90% fewer tokens than grep for symbol questions. Details: ScalaSemantic vs grep.
Documentation
Full documentation: mercurievv.github.io/ScalaSemantic
License
MIT
