Metals Standalone Client

\[！注意\] > 截至 金属v1.6.6（锇），Metals现在包括一个内置的独立MCP服务器(metals-mcp)可以通过Coursier安装(cs install metals-mcp).这使得金属独立客户端项目变得没有必要。请使用官方 metals-mcp 命令代替。 > > # 金属独立MCP客户端

一个独立的客户端，启动支持MCP（模型上下文协议）的Metals语言服务器，使AI助手能够与Scala项目进行交互。使用scala-cli构建，可快速编译和轻松分发。

目的

该工具提供了一种无头方式来运行具有MCP功能的Metals语言服务器，允许像Claude这样的AI代码助手理解并使用您的Scala代码库。它会自动发现Metals安装，配置语言服务器，并监控MCP服务器的运行状况。

为什么需要它，它是如何工作的？

Metals是一个Scala语言服务器，通常在编辑器（VS Code、Neovim等）中运行。编辑器充当LSP客户端：它启动Metals，执行初始化握手，并发送配置。没有编辑做这项工作，Metals就不会开始。

这个独立客户端取代了编辑器。它作为一个 无头LSP客户端 这样Metals就可以在没有打开任何编辑器的情况下运行。以下是运行它时发生的情况：

1. 独立客户端 发现并发射金属 作为一个子流程（通过Coursier）。
2. 它 执行LSP握手 使用JSON-RPC 2.0通过stdin/stdout（初始化、初始化）。
3. 它 配置Metals以启用其内置的MCP服务器 通过发送 startMcpServer: true.
4. Metals启动MCP服务器 写a .mcp.json 文件 在您的项目根目录下，使用连接URL：

   {
     "mcpServers": {
       "metals": {
         "url": "http://localhost:
/mcp",
         "type": "http"
       }
     }
   }

1. 独立客户端 监视MCP服务器运行状况 通过HTTP轮询来确保它保持运行。

运行后，您可以在Scala项目目录中打开Claude Code（或另一个支持MCP的AI助手）。

这使AI助手可以访问Scala语言智能（去定义、查找引用、补全、诊断等），而不需要IDE。

有关详细的图表和组件分解，请参阅 建筑.md.

快速开始

下载预构建的可执行文件

Linux：

wget https://github.com/jpablo/metals-standalone-client/releases/latest/download/metals-standalone-client-linux-executable
chmod +x metals-standalone-client-linux-executable
./metals-standalone-client-linux-executable --help

macOS：

wget https://github.com/jpablo/metals-standalone-client/releases/latest/download/metals-standalone-client-macos-executable
chmod +x metals-standalone-client-macos-executable
./metals-standalone-client-macos-executable --help

窗户：

REM Download both files to the same directory:
REM - metals-standalone-client-windows-executable.bat
REM - metals-standalone-client-windows-executable.jar
metals-standalone-client-windows-executable.bat --help

从源代码构建

# Build assembly JAR
scala-cli --power package . --assembly -f -o metals-standalone-client

# Or build standalone executable
scala-cli --power package . --standalone -f -o metals-standalone-client

从源代码运行

# Use current directory
scala-cli run .

# Specify project path and options
scala-cli run . -- --verbose /path/to/scala/project

选项

• -v, --verbose：启用详细日志记录
• -h, --help：显示帮助消息

特性

• 多种金属的发现：支持Coursier、SBT开发模式、本地JAR
• 无头操作：运行时不依赖IDE
• MCP集成：自动配置Metals MCP服务器
• 健康监测：连续监测，自动重新连接
• 跨平台：适用于Linux、macOS和Windows

配置

使用Claude代码

独立客户端运行后，isntrations将打印到控制台。只需按照项目目录中的这些说明进行操作。首次使用时，系统会提示您批准MCP服务器。

MCP配置文件

Metals根据检测到的客户端将MCP配置写入不同的位置：

金属版本覆盖

当通过Coursier发现金属时，您可以锁定版本：

METALS_VERSION=1.6.0 ./metals-standalone-client --help

需求

对于预构建的可执行文件

• Java 11或更高版本
• Scala项目 build.sbt

从源头构建

• Java 11或更高版本
• scala-cli（从安装https://scala-cli.virtuslab.org)
• Scala项目 build.sbt, project.scala，或 .scala 文件

项目结构

此项目使用scala-cli进行构建管理。配置定义见 project.scala 使用scala-cli的“使用指令”：

//> using scala "3.7.1"
//> using dep "io.circe::circe-core:0.14.14"
//> using dep "io.circe::circe-parser:0.14.14"
// ... other dependencies

这种方法提供了：

• 快速编译和启动时间
• 自给自足的依赖关系管理
• 单个文件中的简单配置
• 非常适合简单性和速度很重要的MCP服务器用例

发展

# Compile
scala-cli compile .

# Run application
scala-cli run . -- [--verbose] [PROJECT_PATH]

# Test
scala-cli test .

# Build assembly JAR
scala-cli --power package . --assembly -f -o metals-standalone-client

# Build standalone executable
scala-cli --power package . --standalone -f -o metals-standalone-client

# Quick build test (compile + test + package)
./test-build.sh

自动化构建

该项目使用GitHub Actions在每次向主分支推送时自动构建和发布Linux、macOS和Windows的可执行文件。这些版本包括无需编译即可使用的单个可执行文件。