星战科技xingzhan.cloud
返回市场
MCP-你好世界

MCP-你好世界

作者：rwachters2 星标更新：2025-10-24
安装使用来源：spider==github.com

项目介绍

MCP Hello World (Kotlin)

该项目演示了使用Kotlin中的模型上下文协议（MCP）实现的最小“Hello World”应用程序。它包括一个简单的MCP服务器，该服务器公开了一个“greet”工具，以及一个对应的MCP客户端，该客户端连接到服务器，发现该工具，并允许交互执行。

此示例旨在展示MCP的核心客户端-服务器通信，而不涉及任何外部AI模型或复杂的业务逻辑。

目录

什么是MCP？

模型上下文协议（MCP）是一个开源标准，用于将AI应用程序连接到外部系统。它提供了一种标准化的方式，使AI应用程序（如LLMs）能够访问数据源、工具和工作流，从而使其能够检索信息并在外部世界中执行任务。

可以将MCP视为AI模型的通用适配器，允许它们扩展其能力，超越内部知识，与现实世界系统进行互动。

项目结构

此项目具有多模块Gradle设置：

mcp-hello-world/
├── build.gradle.kts          // 根Gradle配置
├── settings.gradle.kts       // 多模块项目的Gradle设置
├── client/                   // 客户端模块
│   ├── build.gradle.kts
│   └── src/main/kotlin/eu/torvian/mcp/helloworld/client/
│       ├── HelloWorldClient.kt // MCP客户端实现
│       └── main.kt             // 客户端入口点
├── docs/MCP/                 // MCP及相关SDK的文档
│   ├── Architecture-overview.md // MCP架构概述
│   ├── Clients.md             // MCP客户端文档
│   ├── Servers.md             // MCP服务器文档
│   ├── Specification.md       // MCP详细规范
│   ├── Versioning.md          // MCP版本策略
│   ├── What-is-MCP.md         // MCP简介
│   └── Kotlin-SDK-0.7.3/     // MCP Kotlin SDK的源代码
├── gradle/
│   ├── libs.versions.toml    // 依赖项版本目录
│   └── wrapper/              // Gradle包装程序文件
└── server                    // 服务器模块
    ├── build.gradle.kts
    └── src/main/kotlin/eu/torvian/mcp/helloworld/server/
        └── HelloWorldServer.kt // MCP服务器实现

先决条件

  • Java 17或更高版本：运行JVM上的Kotlin应用程序所需。
  • Gradle：（可选）如果不使用提供的Gradle包装程序，请确保已安装Gradle。
  • 基本了解Kotlin：熟悉Kotlin语法和概念将有所帮助。

构建项目

该项目使用Gradle构建两个独立的“胖JAR”文件，一个用于服务器，一个用于客户端。这些JAR文件包含了所有必要的依赖项，以便独立运行。

  1. 克隆仓库：

    git clone https://github.com/your-username/mcp-hello-world.git
cd mcp-hello-world

  2. 构建服务器JAR：

    ./gradlew :server:jar

    这将生成server/build/libs/mcp-hello-world-server.jar。

  3. 构建客户端JAR：

    ./gradlew :client:jar

    这将生成client/build/libs/mcp-hello-world-client.jar。

运行项目

要查看MCP的实际操作，只需执行客户端应用程序即可。客户端被配置为启动服务器作为子进程，并通过标准I/O流直接与其通信。

  1. 确保客户端和服务器JAR均已构建（参见构建项目部分）。

  2. 从项目根目录执行客户端应用程序，并提供服务器JAR的路径作为参数：

    java -jar client/build/libs/mcp-hello-world-client.jar server/build/libs/mcp-hello-world-server.jar

    客户端将启动，作为子进程启动服务器，连接到它，然后进入交互循环。来自客户端及其服务器子进程的组合输出将出现在同一终端中：

    正在启动Hello World MCP服务器...
客户端：正在启动服务器进程：java -jar server/build/libs/mcp-hello-world-server.jar
客户端：成功连接到MCP服务器。
客户端：从服务器发现工具：greet

--- 交互式工具调用器 ---
输入工具名称以调用它，或输入'quit'退出。
> 输入工具名称：greet
> 输入'name'值：Rogier
客户端：调用工具'greet'，参数：{name=Rogier}
服务器：调用了'greet'，name='Rogier'。响应：'Hello, Rogier!'
服务器响应：Hello, Rogier!
> 输入工具名称：quit
客户端：连接已关闭。
服务器已关闭。

它是如何工作的

  • HelloWorldServer.kt：

    • 使用基本功能初始化一个MCP Server实例。
    • 定义一个名为greet的Tool，带有name参数，使用MCP Kotlin SDK的模式定义。
    • 注册一个lambda函数，用于greet工具，该函数提取name参数，并返回一个包含"Hello, [name]!"的TextContent作为CallToolResult。
    • 连接到StdioServerTransport，这允许它通过标准输入/输出流与客户端通信。

  • HelloWorldClient.kt：

    • 初始化一个MCP Client实例。
    • 在connectToServer()中，它启动mcp-hello-world-server.jar作为一个单独的子进程。
    • 然后设置一个StdioClientTransport来与服务器子进程的标准I/O流通信。
    • 连接后，它调用mcp.listTools()来发现服务器提供的greet工具。
    • interactiveToolLoop()允许用户输入greet，提示输入name参数，然后调用mcp.callTool()来执行服务器的greet工具。
    • 从服务器获取的结果随后被处理并打印到控制台。

  • build.gradle.kts（胖JAR）：

    • 客户端和服务器模块的Gradle构建脚本都配置为创建“胖JAR”。这意味着所有依赖项（如kotlin-stdlib、kotlinx-coroutines-core和MCP Kotlin SDK本身）都被直接打包到mcp-hello-world-client.jar和mcp-hello-world-server.jar文件中。这使得它们可以通过java -jar轻松运行。
    • 在jar任务中应用特殊的exclude规则，以防止构建过程中出现Duplicate entry错误，特别是对于合并JAR时经常引起冲突的META-INF文件和module-info.class文件。

故障排除

  • NoClassDefFoundError：这通常意味着你的JAR不是一个“胖JAR”，并且缺少运行时依赖项。确保你在build.gradle.kts中使用了胖JAR配置，并使用./gradlew :<module>:jar进行构建。
  • 构建期间出现Duplicate entry：检查你的build.gradle.kts jar任务中的from(configurations.runtimeClasspath.get()...)块，并确保META-INF文件的exclude规则正确无误。
  • 客户端无法连接：
    • 确保提供给客户端作为参数的服务器JAR路径是正确的。
    • 验证没有意外问题启动子进程（例如权限问题，java命令不在PATH中）。
  • SLF4J警告：SLF4J(W): 没有找到SLF4J提供者。是一个常见的警告。SLF4J是一个日志门面。要消除警告，你可以添加一个日志实现，如slf4j-simple到你的依赖项中（例如，implementation("org.slf4j:slf4j-simple:2.0.13")）。这只是为了日志输出，不影响核心MCP功能。

进一步学习