# 第一部分 概述

本文主要从以下几个维度进行对**OpenJDK 发行版本**进行对比，便于在使用中根据自身业务场景进行选择：

* 📦 是否长期支持（LTS）
* 🛡️ 是否免费可商用
* 🔁 更新频率与支持周期
* 🌐 发布组织与可信度
* 📥 安装包完整性与可用性（是否带 JRE、支持平台等）
* 🔧 适用场景推荐（服务器端/客户端/嵌入式等）



# 第二部分 常见分发版本对比表

| 名称 | LTS | 商用授权 | 适合场景 | 发布组织 | 平台 | JRE | 特点说明 |
| :----: | :------: | :-------: | :------: | ------- |:---------: |:------: | -------- |
| **Adoptium （AdoptOpenJDK）** | ✅ | 免费商用 | 通用、构建 桌面客户端 服务端 | Eclipse | Win Linux macOS| ✅ | 最常用开源版本，广泛社区支持 |
| **Zulu OpenJDK** | ✅ | 免费商用 | 企业 桌面客户端 嵌入式 | Azul | Win Linux macOS | ✅ | 提供最全平台支持，包括 ARM、Alpine |
| **Amazon Corretto** | ✅ | 免费商用 | 云环境 AWS服务端 | 亚马逊 | Win Linux macOS | ❌ | AWS 优化，适合微服务 |
| **Red Hat OpenJDK** | ✅ | 需订阅 | 企业 Red Hat系统用户 | Red Hat | Linux | ❌ | RHEL 集成推荐，更新稳定但不开放 |
| **Oracle OpenJDK** | ✅ | OpenJDK 免费 | 研发 测试用 | Oracle | Win Linux macOS | ❌| 免费版本仅供开发使用，长期商用需授权 |
| **Liberica JDK** | ✅ | 免费商用 | JavaFX客户端 IoT设备 | BellSoft | Win Linux macOS 嵌入式 | ✅ | 唯一带 JavaFX + 全功能 JDK 的版本 |

---

# 第三部分 分发版本详细说明

## 3.1 Adoptium（Eclipse Temurin）

* 官方地址：[https://adoptium.net](https://adoptium.net)
* **前身是 AdoptOpenJDK**
* 社区最广，默认首选，适合 Swing 桌面、后端服务、企业开发
* 提供带 JRE 的版本（`.zip` 格式，适合打包）

## 3.2 Zulu OpenJDK（Azul Systems）

* 官方地址：[https://www.azul.com/downloads/](https://www.azul.com/downloads/)
* 提供最广泛平台支持（Windows, Linux, macOS, Alpine Linux, ARM64, 嵌入式设备）
* 支持全版本下载（含 legacy JDK 6/7/8）
* 商业版也提供 SLA 支持，稳定性高
* **非常适合：打包桌面程序 + 跨平台部署**

## 3.3 Amazon Corretto

* 官方地址：[https://docs.aws.amazon.com/corretto/](https://docs.aws.amazon.com/corretto/)
* AWS 官方维护，安全性和稳定性高
* 内部做了 **GC、性能优化**
* 适合：AWS 云环境（Lambda、EC2、Fargate 等）

##3.4 Oracle OpenJDK

* 官网：[https://jdk.java.net](https://jdk.java.net)
* 源自 Oracle，但更新频率和商业授权复杂
* **从 JDK11 开始，Oracle JDK 和 OpenJDK 分离**
* 不推荐用于正式发布或长期运行的生产系统

##3.5 Red Hat OpenJDK

* 由 Red Hat 支持，主要用于 RHEL/CentOS 系统环境
* 用户需订阅 RHEL 才能获取长期支持
* 更适合企业内部环境使用，不适合独立开发分发场景

## 3.6 Liberica JDK（BellSoft）

* 官网：[https://bell-sw.com/pages/downloads/](https://bell-sw.com/pages/downloads/)
* 唯一官方集成 JavaFX 的 OpenJDK 分发
* 提供完整版、标准版、轻量版（用于 IoT/容器）
* 如果你需要 GUI（如 Swing + JavaFX），这是最佳选择

# 第四部分 不同场景下选择

| 使用场景 | 推荐版本 | 说明 |
| ---------------- | --------------------------------- | ---------------------------- |
| 桌面客户端程序（如 Swing） | **Adoptium / Zulu / Liberica** | 支持打包 JRE，跨平台性好 |
| 服务器后端服务 | **Corretto / Adoptium / Zulu** | Corretto AWS优化，Adoptium通用 |
| 构建多平台安装包 | **Zulu / Liberica** | 提供 Windows/Linux/macOS ARM 包 |
| JavaFX 应用 | **Liberica JDK Full** | 集成 JavaFX，兼容好 |
| Docker、容器环境 | **Zulu (Alpine)** | 支持轻量级镜像，官方支持 |
| 嵌入式设备（树莓派等） | **Zulu Embedded / Liberica Lite** | 支持 ARM，适合设备部署 |

常用openjdk版本

# 第一部分 概述

在开发和系统管理工作中，我们常常需要快速找到某个全局可执行文件在计算机上的具体位置。这不仅有助于排查问题，还能优化工作流程。`go-where`一个用于确定可执行文件根路径的库。支持 `Windows`、`macOS` 和 `Linux`。




:::info{title="相关信息"}
在 v2.0.0 版本中引入了重大变更。该库已被简化为一个单一的导出函数，该函数接受一个配置对象。所有先前的功能仍然得到支持，但不再有单独用于查找单个路径与多个路径、异常处理等功能的函数。
:::

项目地址：[https://github.com/coreybutler/go-where](https://github.com/coreybutler/go-where)

# 第二部分 基本使用

```go
package main

import (
 "fmt"
 "os"
 "github.com/coreybutler/go-where/v2"
)

func main() {
 executable := os.Args[1]
 path, err := where.Find(executable)

 if err != nil {
 panic(err)
 }

 fmt.Print(path[0])
}
```

使用如下方式运行:

```sh
$ go run myapp.go node.exe
C:\nodejs\node.exe
```

[GO每日一库]go-where

# 第一部分 概述

`viper` 是`Go`语言中的一个配置管理库，用于读取、解析和管理应用程序的配置文件。它支持多种格式的配置文件（如`JSON`、`YAML`、`TOML`、`ENV`等），并提供灵活的方式来读取配置项和管理配置的生命周期。`viper` 的优势在于它能够简化配置的管理，尤其适用于需要从多个来源（文件、环境变量、命令行标志等）加载配置的场景。




项目地址：https://github.com/spf13/viper

## 1.1 主要功能和作用
- **多种配置来源**：`viper` 可以从多种来源加载配置，如本地配置文件（`JSON`、`YAML`、`TOML`等）、环境变量、命令行参数、远程配置服务等，方便将配置集中管理。
- **动态更新配置**：`viper` 支持动态加载和热更新配置文件，允许程序在运行时重新加载配置而不需要重启。
- **配置格式支持**：支持 `JSON`、`YAML`、`TOML`、`HCL`、`ENV` 等多种格式，开发者可以根据项目需求选择合适的格式。
- **默认值和环境变量支持**：`viper` 允许为每个配置项设置默认值，并支持从环境变量中读取配置值，尤其适用于云环境和容器化部署。
- **灵活的配置访问**：提供了多种方法来访问配置项，包括按路径、按键、按默认值等方式，支持结构化配置数据的映射。
- **与 `cobra` 集成**：`viper` 可以与 `cobra` 集成，管理命令行工具的配置和命令行参数，使得命令行工具更加灵活。
- **支持配置监控**：`viper` 可以监控配置文件的变化，当文件被修改时，自动加载新配置，适用于需要动态调整配置的应用程序。

## 1.2 常见使用场景
- **Web 应用配置管理**：在 `Web` 应用中，通常需要加载数据库连接信息、日志配置、API 密钥等。`viper` 可以集中管理这些配置，支持从不同来源（如文件、环境变量）读取配置信息。
- **CLI 工具的配置管理**：使用 `cobra` 构建命令行工具时，`viper` 可以帮助管理和读取命令行的参数、配置文件等，使得命令行工具更加灵活。
- **分布式系统中的配置管理**：在分布式系统中，`viper` 可以与远程配置服务（如 Consul、etcd 等）集成，统一管理和同步配置，避免不同节点之间的配置不一致问题。
- **DevOps 工具和自动化脚本**：DevOps 工具通常需要根据不同的环境读取配置，`viper` 可以帮助动态加载和管理配置文件，使得工具在不同环境下可以灵活运行。

# 第二部分 常用操作

## 2.1 安装

通过以下命令安装 `viper` 库：

```bash
go get github.com/spf13/viper
```

## 2.2 设置默认值
 
实际使用中，常常会对部分配置项进行默认值的配置，使用 `viper` 可以轻松的完成这项工作。如果配置文件中没有相应的配置，`viper` 会使用默认值：

```go
package main

import (
 "fmt"
 "github.com/spf13/viper"
)

func main() {
 // 设置默认值
 viper.SetDefault("server.port", 8080)

 // 获取值
 port := viper.GetInt("server.port")
 fmt.Printf("Server will run on port: %d\n", port)
}
```

上述代码中，`viper.SetDefault` 用于设置配置项的默认值。

## 2.3 读取配置文件

`viper` 可以读取多种格式的配置文件。以下是加载`YAML`格式配置文件的示例：

```go
package main

import (
 "fmt"
 "log"
 "github.com/spf13/viper"
)

func main() {
 // 设置配置文件路径
 viper.SetConfigName("config") // 文件名（不带扩展名）
 viper.AddConfigPath(".") // 配置文件所在目录

 // 读取配置文件
 if err := viper.ReadInConfig(); err != nil {
 log.Fatalf("Error reading config file, %s", err)
 }

 // 获取配置项
 port := viper.GetInt("server.port")
 fmt.Printf("Server running on port: %d\n", port)
}
```

假设配置文件 `config.yaml` 内容如下：

```yaml
 server:
 port: 8080
 ```

`viper.ReadInConfig()` 会从当前目录加载 `config.yaml` 配置文件，并读取其中的配置项。

## 2.4 支持多种配置格式
`viper` 支持多种格式的配置文件，包括`JSON`、`YAML`、`TOML`、`ENV` 等。只需要根据文件类型调用对应的方法：

```go
viper.SetConfigType("yaml") // 设置配置文件格式
viper.ReadInConfig() // 读取配置
```

## 2.5 从环境变量加载配置

`viper` 支持从环境变量中读取配置项。默认情况下，环境变量名会被转化为大写，并用下划线代替点（`.`）。例如，配置项 `server.port` 会对应环境变量 `SERVER_PORT`：

```go
package main

import (
 "fmt"
 "github.com/spf13/viper"
)

func main() {
 // 从环境变量中读取配置
 viper.AutomaticEnv() // 启用自动加载环境变量

 // 获取环境变量值
 port := viper.GetInt("SERVER_PORT")
 fmt.Printf("Server running on port: %d\n", port)
}
```

如果环境变量 `SERVER_PORT` 存在，则 `viper` 会自动读取该值。

## 2.6 读取命令行标志

`viper` 可以与 `cobra` 一起使用，从命令行标志中读取配置：

```go
var configFile string

var rootCmd = &cobra.Command{
 Use: "myapp",
 Short: "My Application",
 Run: func(cmd *cobra.Command, args []string) {
 // 从命令行标志读取配置
 viper.SetConfigFile(configFile)
 err := viper.ReadInConfig()
 if err != nil {
 fmt.Println("Error reading config:", err)
 }
 },
}

func init() {
 rootCmd.PersistentFlags().StringVar(&configFile, "config", "", "config file")
}
```

上面的代码允许通过命令行传递配置文件路径，例如：

```bash
myapp --config ./config.yaml
```

## 2.7 动态监控配置文件变化

`viper` 可以监控配置文件的变化，并在文件发生更改时重新加载配置。可以通过`viper.WatchConfig` 来实现：

```go
package main

import (
 "fmt"
 "github.com/spf13/viper"
)

func main() {
 // 设置配置文件路径
 viper.SetConfigName("config")
 viper.AddConfigPath(".")

 // 读取配置
 if err := viper.ReadInConfig(); err != nil {
 fmt.Println("Error reading config:", err)
 }

 // 监控配置文件的变化
 viper.WatchConfig()
 // 设置配置更改的回调函数
 viper.OnConfigChange(func(e fsnotify.Event) {
 fmt.Println("Config file changed:", e.Name)
 })

 // 获取配置值
 port := viper.GetInt("server.port")
 fmt.Printf("Server running on port: %d\n", port)
 // 等待用户按键，防止程序退出
 fmt.Scanln()
}
```

在上面的代码中，`viper.WatchConfig()` 会监控配置文件的变化，并在文件更改时调用回调函数。

## 2.8 结构体映射

`viper` 可以将配置文件中的数据映射到 `Go` 结构体中，便于使用：
 
 ```go
type Config struct {
 Server struct {
 Port int `mapstructure:"port"`
 }
}

var config Config
viper.SetConfigName("config")
viper.AddConfigPath(".")
viper.ReadInConfig()

// 将配置文件数据映射到结构体
err := viper.Unmarshal(&config)
if err != nil {
 fmt.Println("Error unmarshalling config:", err)
}

fmt.Printf("Server running on port: %d\n", config.Server.Port)
```

在上面的代码中，`viper.Unmarshal` 将配置文件中的数据映射到 `Config` 结构体。

[GO每日一库]viper

# 第一部分 概述

`MCP`（Model Context Protocol ）是一个开放协议，标准化了应用程序如何为大型语言模型（`LLMs`）提供上下文。可以将`MCP`想象成`AI`应用程序的`USB-C`接口。正如`USB-C`提供了连接设备与各种外设和配件的标准化方式，`MCP`提供了一种标准化方式，将`AI`模型与不同的数据源和工具连接起来。



## 1.1 为什么选择 MCP？

`MCP`可以帮助你在大型语言模型（`LLMs`）之上构建代理和复杂的工作流。`LLMs`经常需要与数据和工具集成，而`MCP`提供了以下优势：

- 一个不断增长的预构建集成列表，`LLM`可以直接连接这些集成。
- 在不同的`LLM`提供商和供应商之间切换的灵活性。
- 在基础设施内确保数据安全的最佳实践。

## 1.2 一般架构

`MCP`基于客户端-服务器架构，核心思想是主机应用程序可以连接到多个服务器：


![01.png](/static/img/c662dd16cb00be0657d80491011eced4.01.webp)

- **MCP 主机**：应用程序如`Claude`、`IDE`或`AI`工具，通常需要通过`MCP`协议访问数据。
- **MCP 客户端**：这些客户端与服务器保持直接连接，用于处理实际的协议通信。
- **MCP 服务器**：轻量级程序，每个程序通过标准化的模型上下文协议暴露特定的功能。
- **本地数据源**：计算机上的文件、数据库和服务，MCP 服务器可以安全地访问这些数据。
- **远程服务**：通过互联网可访问的外部系统（例如，通过`API`），`MCP`服务器可以连接到这些服务。

## 1.3 基于MCP的集成架构

![640.webp](/static/img/882d7ad1f11bf158dc90d41b0d1e0daf.640.webp)

相对于`LLM`应用直连外部资源，这里主要多了一个中间层（`MCP Server`），以及连接这个中间层的（`MCP Client`）。

# 第二部分 MCP概念

## 2.1 核心架构

`MCP`建立在一个灵活且可扩展的架构之上，能够实现大型语言模型（`LLM`）应用程序与集成之间的无缝通信。

`MCP`采用`客户端`-`服务器`架构，其中：
 - **Hosts**：是发起连接的LLM应用程序（例如Claude Desktop或IDE）。
 - **Clients**：在宿主应用程序内与服务器保持一对一连接。
 - **Servers**：向客户端提供上下文、工具和提示。


![02.png](/static/img/d13c8dc38790c0f8725dc0e5153ad905.02.webp)

### 2.1.1 核心组件

- **协议层**：协议层负责消息封装、请求/响应关联以及高级通信模式。
- **传输层**：传输层负责客户端与服务器之间的实际通信。`MCP`支持多种传输机制：
 - 标准输入/输出传输（`Stdio transport`）
 - 使用标准输入/输出进行通信。
 - 适用于本地进程。
 - 带有服务器发送事件（`SSE`）的`HTTP`传输
 - 使用服务器发送事件进行服务器到客户端的消息传递。
 - 使用`HTTP POST`进行客户端到服务器的消息传递。


:::info{title="相关信息"}
所有传输机制均使用[`JSON-RPC 2.0`](https://www.jsonrpc.org/specification)来交换消息。有关模型上下文协议消息格式的详细信息，可查看[官网](https://www.jsonrpc.org/specification)说明或[JSON-RPC 2.0协议详解](https://blog.jianggujin.com/post/19)。
:::

- **消息类型**：`MCP`主要有以下几种消息类型：
 - **请求（Requests）**：期望从另一端获得响应。
 - **结果（Results）**：对请求的成功响应。
 - **错误（Errors）**：表示请求失败。
 - **通知（Notifications）**：单向消息，不期望响应。



### 2.1.2 连接生命周期
#### 2.1.2.1 初始化

![03.png](/static/img/57c6e01b25a5331c54d24967c4364d71.03.webp)

1. 客户端发送`initialize`请求，包含协议版本和功能。
2. 服务器响应其协议版本和功能。
3. 客户端发送`initialized`通知作为确认。
4. 开始正常的消息交换。

#### 2.1.2.2 消息交换
初始化完成后，支持以下模式：
- **请求-响应**：客户端或服务器发送请求，另一端响应。
- **通知**：任一方发送单向消息。

#### 2.1.2.3 终止

任一方都可以终止连接：
- 通过`close()`进行干净的关闭。
- 传输断开连接。
- 出现错误条件。

### 2.1.3 错误处理

`MCP`定义了以下标准错误代码：

```ts
enum ErrorCode {
 // Standard JSON-RPC error codes
 ParseError = -32700,
 InvalidRequest = -32600,
 MethodNotFound = -32601,
 InvalidParams = -32602,
 InternalError = -32603
}
```

`SDK`和应用程序可以在`-32000`以上定义自己的错误代码。

## 2.2 Resources（资源）

资源是`MCP`的核心原语，允许服务器向客户端暴露数据和内容，这些数据和内容可以被客户端读取，并用作与大型语言模型（`LLM`）交互的上下文。

资源代表了`MCP`服务器希望向客户端提供的任何类型的数据。这可以包括：

- 文件内容
- 数据库记录
- API响应
- 实时系统数据
- 截图和图片
- 日志文件
- 以及其他更多内容

每个资源都通过一个唯一的`URI`进行标识，并且可以包含文本或二进制数据。

### 2.2.1 资源URI

资源通过URI进行标识，其格式如下：

```
[protocol]://[host]/[path]
```

例如：

- `file:///home/user/documents/report.pdf`
- `postgres://database/customers/schema`
- `screen://localhost/display1`

协议和路径结构由`MCP`服务器实现定义。服务器可以定义自己的自定义`URI`方案。

### 2.2.2 资源类型

资源可以包含两种类型的内容：

- **文本资源**：文本资源包含`UTF-8`编码的文本数据。这些适用于：
 - 源代码
 - 配置文件
 - 日志文件
 - `JSON`/`XML`数据
 - 纯文本
- **二进制资源**：二进制资源包含以`base64`编码的原始二进制数据。这些适用于：
 - 图像
 - PDF文件
 - 音频文件
 - 视频文件
 - 其他非文本格式

### 2.2.3 资源发现

客户端可以通过两种主要方法发现可用资源：
- **直接资源**：服务器通过`resources/list`端点暴露一组具体的资源。每个资源包括：
```json
{
 uri: string; // Unique identifier for the resource
 name: string; // Human-readable name
 description?: string; // Optional description
 mimeType?: string; // Optional MIME type
}
```

- **资源模板**：对于动态资源，服务器可以暴露`URI`模板，客户端可以使用这些模板构建有效的资源`URI`。

```json
{
 uriTemplate: string; // URI template following RFC 6570
 name: string; // Human-readable name for this type
 description?: string; // Optional description
 mimeType?: string; // Optional MIME type for all matching resources
}
```

### 2.2.4 读取资源

要读取资源，客户端需要使用资源`URI`发起`resources/read`请求。

服务器会返回资源内容的列表：

```json
{
 contents: [
 {
 uri: string; // The URI of the resource
 mimeType?: string; // Optional MIME type

 // One of:
 text?: string; // For text resources
 blob?: string; // For binary resources (base64 encoded)
 }
 ]
}
```

:::tip{title="提示"}
服务器可能会对一个`resources/read`请求返回多个资源。例如，当读取一个目录时，这可以用来返回目录内的文件列表。
:::

### 2.2.5 资源更新

`MCP`通过两种机制支持资源的实时更新：

- **列表变更**：服务器可以通过`notifications/resources/list_changed`通知客户端其可用资源列表的变化。
- **内容变更**：客户端可以订阅特定资源的更新：
 1. 客户端发送`resources/subscribe`请求，包含资源`URI`。
 2. 资源变更时，服务器发送`notifications/resources/updated`通知。
 3. 客户端可以通过`resources/read`获取最新内容。
 4. 客户端可以通过`resources/unsubscribe`取消订阅。

## 2.3 Prompts（提示）

提示使服务器能够定义可重用的提示模板和工作流，客户端可以轻松地将其展示给用户和大型语言模型（`LLM`）。它们为标准化和共享常见的`LLM`交互提供了一种强大的方式。

`MCP`中的提示是预定义的模板，可以：
- 接受动态参数
- 包含来自资源的上下文
- 链接多个交互
- 指导特定的工作流
- 作为`UI`元素展示（例如斜杠命令）

### 2.3.1 提示结构

每个提示的定义包括：

```json
{
 name: string; // Unique identifier for the prompt
 description?: string; // Human-readable description
 arguments?: [ // Optional list of arguments
 {
 name: string; // Argument identifier
 description?: string; // Argument description
 required?: boolean; // Whether argument is required
 }
 ]
}
```

### 2.3.2 发现提示

客户端可以通过`prompts/list`端点发现可用的提示：

```json
// Request
{
 method: "prompts/list"
}

// Response
{
 prompts: [
 {
 name: "analyze-code",
 description: "Analyze code for potential improvements",
 arguments: [
 {
 name: "language",
 description: "Programming language",
 required: true
 }
 ]
 }
 ]
}
```

### 2.3.3 使用提示

要使用提示，客户端需要发起`prompts/get`请求：

```json
// Request
{
 method: "prompts/get",
 params: {
 name: "analyze-code",
 arguments: {
 language: "python"
 }
 }
}

// Response
{
 description: "Analyze Python code for potential improvements",
 messages: [
 {
 role: "user",
 content: {
 type: "text",
 text: "Please analyze the following Python code for potential improvements:\n\n```python\ndef calculate_sum(numbers):\n total = 0\n for num in numbers:\n total = total + num\n return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n```"
 }
 }
 ]
}
```

### 2.3.4 动态提示

提示可以是动态的，并包含以下内容：

- **嵌入资源上下文**

在处理`prompts/get`请求时：
```json
{
 "name": "analyze-project",
 "description": "Analyze project logs and code",
 "arguments": [
 {
 "name": "timeframe",
 "description": "Time period to analyze logs",
 "required": true
 },
 {
 "name": "fileUri",
 "description": "URI of code file to review",
 "required": true
 }
 ]
}
```

在处理`prompts/get`请求时：

```json
{
 "messages": [
 {
 "role": "user",
 "content": {
 "type": "text",
 "text": "Analyze these system logs and the code file for any issues:"
 }
 },
 {
 "role": "user",
 "content": {
 "type": "resource",
 "resource": {
 "uri": "logs://recent?timeframe=1h",
 "text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded",
 "mimeType": "text/plain"
 }
 }
 },
 {
 "role": "user",
 "content": {
 "type": "resource",
 "resource": {
 "uri": "file:///path/to/code.py",
 "text": "def connect_to_service(timeout=30):\n retries = 3\n for attempt in range(retries):\n try:\n return establish_connection(timeout)\n except TimeoutError:\n if attempt == retries - 1:\n raise\n time.sleep(5)\n\ndef establish_connection(timeout):\n # Connection implementation\n pass",
 "mimeType": "text/x-python"
 }
 }
 }
 ]
}
```

- **多步骤工作流**

```ts
const debugWorkflow = {
 name: "debug-error",
 async getMessages(error: string) {
 return [
 {
 role: "user",
 content: {
 type: "text",
 text: `Here's an error I'm seeing: ${error}`
 }
 },
 {
 role: "assistant",
 content: {
 type: "text",
 text: "I'll help analyze this error. What have you tried so far?"
 }
 },
 {
 role: "user",
 content: {
 type: "text",
 text: "I've tried restarting the service, but the error persists."
 }
 }
 ];
 }
};
```

## 2.4 Tools（工具）

工具是`MCP`中一个强大的原语，它允许服务器向客户端暴露可执行的功能。通过工具，`LLM`可以与外部系统交互、执行计算以及在现实世界中采取行动。

`MCP`中的工具允许服务器暴露可被客户端调用并由`LLM`用于执行操作的可执行函数。工具的关键特性包括：

- **发现**：客户端可以通过`tools/list`端点列出可用的工具。
- **调用**：工具通过`tools/call`端点被调用，服务器执行请求的操作并返回结果。
- **灵活性**：工具可以是从简单计算到复杂API交互的任何内容。

与资源类似，工具通过唯一名称进行标识，并且可以包含描述以指导其使用。然而，与资源不同的是，工具代表动态操作，可以修改状态或与外部系统交互。

**每个工具的定义结构如下**：

```json
{
 name: string; // Unique identifier for the tool
 description?: string; // Human-readable description
 inputSchema: { // JSON Schema for the tool's parameters
 type: "object",
 properties: { ... } // Tool-specific parameters
 }
}
```

**`MCP`支持动态工具发现**：

1. 客户端可以随时列出可用的工具。
2. 服务器可以通过`notifications/tools/list_changed`通知客户端工具的变化。
3. 工具可以在运行时添加或移除。
4. 工具定义可以更新（尽管这应该谨慎进行）。

## 2.5 Roots（根目录）

根目录是`MCP`中的一个概念，用于定义服务器可以操作的边界。它们为客户端提供了一种方式，用于告知服务器相关资源及其位置。

### 2.5.1 什么是根目录？

根目录是一个客户端建议服务器关注的`URI`。当客户端连接到服务器时，它会声明服务器应该使用哪些根目录。根目录主要用于文件系统路径，但也可以是任何有效的`URI`，包括`HTTP URL`。

例如，根目录可以是：

- `file:///home/user/projects/myapp`
- `https://api.example.com/v1`

### 2.5.2 为什么使用根目录？

根目录有以下几个重要的作用：

1. **引导**：它们告知服务器相关资源和位置。
2. **明确性**：根目录明确了哪些资源属于你的工作空间。
3. **组织性**：多个根目录允许你同时处理不同的资源。

### 2.5.3 根目录的工作原理

当客户端支持根目录时，它会：

1. 在连接时声明`roots`能力。
2. 向服务器提供一组建议的根目录。
3. 在支持的情况下，当根目录发生变化时通知服务器。

虽然根目录是信息性的，并不强制执行，但服务器应该：

1. 尊重提供的根目录。
2. 使用根目录URI定位和访问资源。
3. 优先在根目录边界内执行操作。

## 2.6 Transports（传输）

在`MCP`中，传输为客户端和服务器之间的通信提供了基础。传输层负责消息发送和接收的底层机制。

### 2.6.1 消息格式

`MCP`使用`[JSON-RPC 2.0](https://blog.jianggujin.com/post/19)`作为其传输格式。传输层负责将`MCP`协议消息转换为`JSON-RPC`格式以进行传输，并将接收到的`JSON-RPC`消息转换回`MCP`协议消息。

使用的JSON-RPC消息有三种类型：

- 请求（Requests）

```json
{
 jsonrpc: "2.0",
 id: number | string,
 method: string,
 params?: object
}
```

- 响应（Responses）

```json
{
 jsonrpc: "2.0",
 id: number | string,
 result?: object,
 error?: {
 code: number,
 message: string,
 data?: unknown
 }
}
```

- 通知（Notifications）

```json
{
 jsonrpc: "2.0",
 method: string,
 params?: object
}
```

### 2.6.2 内置传输类型

MCP提供了两种标准的传输实现：

- **标准输入/输出（stdio）**：通过标准输入和输出流实现通信。这种传输方式特别适用于本地集成和命令行工具。使用stdio的情况：
 - 构建命令行工具时
 - 实现本地集成时
 - 需要简单的进程间通信时
 - 使用shell脚本时

- **服务器发送事件（`SSE`）**：通过`HTTP POST`请求实现客户端到服务器的通信，同时支持服务器到客户端的流式传输。使用`SSE`的情况：
 - 只需要服务器到客户端的流式传输时
 - 在受限网络环境中工作时
 - 实现简单的更新时

### 2.6.3 自定义传输

`MCP`支持为特定需求实现自定义传输。任何传输实现只需符合`Transport`接口即可：

可以为以下场景实现自定义传输：

- 自定义网络协议
- 专用通信通道
- 与现有系统的集成
- 性能优化

# 第三部分 MCP常用地址
- [官网 (modelcontextprotocol.io)](https://modelcontextprotocol.io/introduction)
- [MCP servers](https://github.com/modelcontextprotocol/servers)
- [MCP Server精选 (glama.ai)](https://glama.ai/mcp/servers)
- [MCP Server精选 (awesome-mcp-servers)](https://github.com/punkpeye/awesome-mcp-servers)
- [社区驱动的平台 (mcp.so)](https://mcp.so/)
- [portkey.ai](https://portkey.ai/mcp-servers)
- [把stdio-based转化为SSE远程Server](https://github.com/supercorp-ai/supergateway)
- [LangChain的mcp适配器](https://github.com/langchain-ai/langchain-mcp-adapters)
- [FastMCP (Python)](https://github.com/jlowin/fastmcp)
- [FastMCP (TypeScript)](https://github.com/punkpeye/fastmcp)
- [SDKs (Python)](https://github.com/modelcontextprotocol/python-sdk)
- [SDKs (TypeScript)](https://github.com/modelcontextprotocol/typescript-sdk)
- [Inspector：用于测试和调试MCP服务器的开发工具](https://github.com/modelcontextprotocol/inspector)
- [MCP YouTube：用于yt-dlp从 YouTube 下载字幕](https://github.com/anaisbetts/mcp-youtube)
- [mcp-security-scanner：使用 MCP 插件构建的安全漏洞扫描器，用于分析 JavaScript 代码](https://github.com/DMontgomery40/mcp-security-scanner)
- [Cloudflare MCP Server：这是一个用于与 Cloudflare 服务交互的模型上下文协议 (MCP) 服务器。它提供了用于管理 Cloudflare KV Store、R2 Storage、D1 Database、Workers 和 Analytics 的统一界面](https://github.com/cloudflare/mcp-server-cloudflare)
- [mcp-get：用于安装和管理模型上下文协议 (MCP) 服务器的命令行工具](https://github.com/michaellatman/mcp-get)

Model Context Protocol (MCP)

# 第一部分 概述

[`JSON-RPC 2.0`](https://www.jsonrpc.org/specification)是一种基于`JSON`（`JavaScript Object Notation`）的远程过程调用（`RPC`）协议。它是一种轻量级的、无状态的、跨语言的通信协议，常用于客户端与服务端之间的交互。





# 第二部分 基本特点

- **简单直观**：消息结构清晰，仅由JSON对象组成。
- **双向通信**：支持客户端调用服务端方法，服务端也可通知客户端。
- **无状态**：协议本身不维护会话状态。
- **支持批量请求**：允许在一个JSON数组中发送多个请求，提升效率。
- **错误处理**：定义了标准的错误对象，便于排查和处理异常。

# 第三部分 消息格式

在`JSON-RPC 2.0`中，有以下三种主要的消息类型：
- **请求对象（Request Object）**
- **响应对象（Response Object）**
- **通知对象（Notification Object）**

## 3.1 请求对象

用于客户端调用服务端的方法，结构如下：
```json
{
 "jsonrpc": "2.0",
 "method": "methodName",
 "params": ["param1", "param2"],
 "id": 1
}
```

- `jsonrpc`：协议版本，固定为`2.0`。
- `method`：调用的远程方法名。
- `params`：方法参数，可以是数组或对象。
- `id`：唯一标识请求的ID，用于匹配响应。可为数字、字符串或`null`。

**示例：**
```json
{
 "jsonrpc": "2.0",
 "method": "add",
 "params": [4, 5],
 "id": 123
}
```

## 3.2 响应对象

用于服务端返回结果或错误信息，结构如下：

**成功响应：**
```json
{
 "jsonrpc": "2.0",
 "result": 9,
 "id": 123
}
```
- `jsonrpc`：协议版本。
- `result`：调用方法的返回结果。
- `id`：与请求对象中的`id`一致，用于匹配响应。

**错误响应：**
```json
{
 "jsonrpc": "2.0",
 "error": {
 "code": -32600,
 "message": "Invalid Request",
 "data": "Additional information if available"
 },
 "id": null
}
```
- `error`：包含错误信息的对象。
 - `code`：标准错误码。
 - `message`：错误描述信息。
 - `data`：可选的额外错误信息。
- `id`：如果无法解析请求或无法响应，则`id`设为`null`。

---

## 3.3 通知对象

通知是一种特殊的请求，不需要响应。用于不关心结果的场景，例如日志记录等。

**通知对象示例：**
```json
{
 "jsonrpc": "2.0",
 "method": "logMessage",
 "params": ["User logged in"]
}
```
- 没有`id`字段。
- 不会有响应对象返回。

# 第四部分 错误码列表

`JSON-RPC 2.0`定义了一组标准错误码：

| 错误码 | 错误类型 | 描述 |
|-------------|-----------------------|------------------------------------|
| -32700 | Parse Error | 无法解析 JSON 数据 |
| -32600 | Invalid Request | 请求对象无效 |
| -32601 | Method Not Found | 方法不存在或不可用 |
| -32602 | Invalid Params | 参数无效 |
| -32603 | Internal Error | 服务端内部错误 |
| -32000~-32099| Server Error | 自定义服务器错误 |

# 第五部分 批量请求与响应

`JSON-RPC 2.0`支持在一个请求中发送多个调用，服务端也会以数组形式返回响应。

**批量请求示例：**
```json
[
 {
 "jsonrpc": "2.0",
 "method": "add",
 "params": [1, 2],
 "id": 1
 },
 {
 "jsonrpc": "2.0",
 "method": "subtract",
 "params": [5, 3],
 "id": 2
 }
]
```

**批量响应示例：**
```json
[
 {
 "jsonrpc": "2.0",
 "result": 3,
 "id": 1
 },
 {
 "jsonrpc": "2.0",
 "result": 2,
 "id": 2
 }
]
```

如果某个请求是通知或者出错，也会在响应中反映：
```json
[
 {
 "jsonrpc": "2.0",
 "result": 3,
 "id": 1
 },
 {
 "jsonrpc": "2.0",
 "error": {
 "code": -32601,
 "message": "Method not found"
 },
 "id": 2
 }
]
```

# 第六部分 示例场景

**场景1：简单调用**
客户端请求服务端进行加法运算：
```json
{
 "jsonrpc": "2.0",
 "method": "add",
 "params": [10, 20],
 "id": 100
}
```
服务端返回结果：
```json
{
 "jsonrpc": "2.0",
 "result": 30,
 "id": 100
}
```

---

**场景2：错误处理**
客户端请求一个不存在的方法：
```json
{
 "jsonrpc": "2.0",
 "method": "unknownMethod",
 "params": [],
 "id": 101
}
```
服务端返回错误：
```json
{
 "jsonrpc": "2.0",
 "error": {
 "code": -32601,
 "message": "Method not found"
 },
 "id": 101
}
```

**场景3：通知**
客户端发送通知，不需要返回结果：
```json
{
 "jsonrpc": "2.0",
 "method": "notifyEvent",
 "params": ["EventData"]
}
```
服务端不会返回任何响应。


# 第七部分 总结

`JSON-RPC 2.0`提供了一种简洁、灵活且强大的通信方式，特别适用于：
- 分布式系统中的服务调用 
- 微服务架构下的跨语言交互 
- 物联网设备与后端服务的通信 

通过`JSON-RPC 2.0`，可以高效地管理远程方法调用、错误处理和批量操作，提升系统的整体性能和可靠性。

第一部分概述

第一部分概述

第一部分概述

第一部分概述

第一部分概述

第一部分 概述

第一部分 概述

第一部分 概述

第一部分 概述

第一部分 概述

第一部分概述

第一部分概述

第一部分概述

第一部分概述

第一部分概述