JinDaGe - fast-mcp-scala MCP Details

article

README

🚀 快速MCP-Scala

快速MCP-Scala是一个高级且对开发者友好的Scala 3库，主要用于构建模型上下文协议（MCP）服务器，能有效提升开发效率与体验。

🚀 快速开始

本库是一个基于Scala 3构建的高级库，用于创建模型上下文协议（MCP）服务器。它提供了基于ZIO的异步支持、注解驱动的API和自动JSON Schema生成等特性。

//> using scala 3.6.4
//> using dep com.tjclp::fast-mcp-scala:0.1.0
//> using options "-Xcheck-macros" "-experimental"

import com.tjclp.fastmcp.core.{Tool, ToolParam, Prompt, PromptParam, Resource}
import com.tjclp.fastmcp.server.FastMcpServer
import com.tjclp.fastmcp.macros.RegistrationMacro.*
import zio.*

// 定义带有注解的工具、提示和资源
object Example:
  @Tool(name = Some("add"), description = Some("Add two numbers"))
  def add(
      @ToolParam("First operand") a: Double,
      @ToolParam("Second operand") b: Double
    ): Double = a + b

  @Prompt(name = Some("greet"), description = Some("Generate a greeting message"))
  def greet(@PromptParam("Name to greet") name: String): String =
    s"Hello, $name!"

  // 注意：资源模板（templated URIs）尚未支持；
  // 当 MCP Java SDK 添加了模板支持后即将实现。
  @Resource(uri = "file://test", description = Some("Test resource"))
  def test(): String = "This is a test"

object ExampleServer extends ZIOAppDefault:
  override def run =
    for
      server <- ZIO.succeed(FastMcpServer("ExampleServer"))
      _      <- ZIO.attempt(server.scanAnnotations[Example.type])
      _      <- server.runStdio()
    yield ()

✨ 主要特性

基于ZIO的效果处理和异步支持：借助ZIO实现强大的效果处理和异步操作，提升程序性能。
注解驱动的API：通过 @Tool、@Resource、@Prompt 等注解，简化API开发。
自动生成JSON Schema和处理程序：利用Scala 3宏，自动生成JSON Schema和处理程序，提高开发效率。
与Java MCP SDK无缝集成：可与Java MCP SDK进行无缝集成，拓展功能。

📦 安装指南

使用 sbt

将以下内容添加到您的 build.sbt（默认为 Scala 3.6.4）：

libraryDependencies += "com.tjclp" %% "fast-mcp-scala" % "0.1.0"

使用 Scala CLI

使用以下命令：

//> using scala 3.6.4
//> using dep com.tjclp::fast-mcp-scala:0.1.0
//> using options "-Xcheck-macros" "-experimental"

💻 使用示例

基础用法

// 此代码展示了如何定义工具、提示和资源，并启动服务器
//> using scala 3.6.4
//> using dep com.tjclp::fast-mcp-scala:0.1.0
//> using options "-Xcheck-macros" "-experimental"

import com.tjclp.fastmcp.core.{Tool, ToolParam, Prompt, PromptParam, Resource}
import com.tjclp.fastmcp.server.FastMcpServer
import com.tjclp.fastmcp.macros.RegistrationMacro.*
import zio.*

// 定义带有注解的工具、提示和资源
object Example:
  @Tool(name = Some("add"), description = Some("Add two numbers"))
  def add(
      @ToolParam("First operand") a: Double,
      @ToolParam("Second operand") b: Double
    ): Double = a + b

  @Prompt(name = Some("greet"), description = Some("Generate a greeting message"))
  def greet(@PromptParam("Name to greet") name: String): String =
    s"Hello, $name!"

  // 注意：资源模板（templated URIs）尚未支持；
  // 当 MCP Java SDK 添加了模板支持后即将实现。
  @Resource(uri = "file://test", description = Some("Test resource"))
  def test(): String = "This is a test"

object ExampleServer extends ZIOAppDefault:
  override def run =
    for
      server <- ZIO.succeed(FastMcpServer("ExampleServer"))
      _      <- ZIO.attempt(server.scanAnnotations[Example.type])
      _      <- server.runStdio()
    yield ()

📚 详细文档

运行示例

上述示例可以通过 scala-cli scripts/quickstart.scala 从仓库根目录运行。您可以通过以下命令使用 MCP 检查器运行服务器：

npx @modelcontextprotocol/inspector scala-cli <path_to_repo>/scripts/quickstart scala

您还可以直接从命令行运行示例：

scala-cli \
    -e '//> using dep com.tjclp::fast-mcp-scala:0.1.0'
    //> using options "-Xcheck-macros" "-experimental"

与Claude Desktop集成

您可以在 ~/.config/claude 中创建一个文件，内容如下：

export Claude=$((待实现))

📄 许可证

项目在 MIT 许可证下发布。

fast-mcp-scala