# 第一部分 概述
本文主要介绍在Go语言环境中如何对达梦数据库进行操作，官方相关材料地址如下：
- DM8下载地址：[https://eco.dameng.com/download/](https://eco.dameng.com/download/)
- 产品手册【DM Go 编程指南】：[https://eco.dameng.com/document/dm/zh-cn/pm/go-rogramming-guide.html](https://eco.dameng.com/document/dm/zh-cn/pm/go-rogramming-guide.html)
- 应用开发指南【DM 接口】：[https://eco.dameng.com/document/dm/zh-cn/app-dev/go_dm.html](https://eco.dameng.com/document/dm/zh-cn/app-dev/go_dm.html)
- 常见问题【GO语言】：[https://eco.dameng.com/document/dm/zh-cn/faq/faq-go-new.html](https://eco.dameng.com/document/dm/zh-cn/faq/faq-go-new.html)




# 第二部分 环境准备

## 2.1 获取Go版本驱动
达梦数据库安装完成后，在其安装目录的`drivers`目录下可以找到对应语言的驱动文件。

![image.png](/static/img/313076847920372d24ae773f5ce71a0e.image.webp)
在`go`目录下的`dm-go-driver.zip`即为我们需要使用的驱动包。

:::tip{title="提示"}
如果使用`GORM`进行数据库操作则可以使用达梦一起提供的`gorm_v1_dialect.zip`和`gorm_v2_dialect.zip`，本文主要使用标准方式进行达梦数据库的连接操作，不对`GORM`进行展开
:::

除上述获取方式外，笔者在达梦论坛中找到了一份分享链接，在其中也可以获取达梦数据库相关资源(Windows)

链接地址：[https://eco.dameng.com/s/4IZA73B22P](https://eco.dameng.com/s/4IZA73B22P) 
提取码：`erem`


![image.png](/static/img/95e8f733eb47e4edbc972af7a74c2d92.image.webp)

:::warning{title="注意"}
本人不对上述链接的有效性以及内容安全性等进行保证，请谨慎选择下载
:::

## 2.2 安装驱动包

驱动文件下载完成后，可以参考官网方式进行操作，在实际体验中，本着感觉官网方式较为繁琐，我么可以直接将下载的驱动作为项目依赖进行引入。

### 2.2.1 解压驱动包

解压驱动包至项目目录中，名称可以定义，笔者将其放在`dm-go-driver`中，目录结构如下


![image.png](/static/img/7b7fc97fbeafae410292e7c2e4b9566b.image.webp)

### 2.2.2 引入依赖

修改`go.mod`文件，添加达梦驱动包的依赖

```
module jianggujin.com//dm

go 1.23.0

require (
	dm v0.0.0
)

replace dm => ./dm-go-driver/dm
```

:::tip{title="提示"}
需要特别注意上述配置中的配置信息
- `replace dm => ./dm-go-driver/dm`：表示将`dm`依赖指向为本地目录`./dm-go-driver/dm`，这样包管理工具会直接使用本地文件，不会从网络上下载
- `dm v0.0.0`：引入驱动包，版本号自定义指定
:::

上述配置完成后，需要执行`go mod tidy`下载驱动包依赖的`golang.org/x/text`和`github.com/golang/snappy`。最终配置参考如下：

```
module jianggujin.com//dm

go 1.23.0

require (
	dm v0.0.0
)

replace dm => ./dm-go-driver/dm

require (
	github.com/golang/snappy v0.0.1 // indirect
	golang.org/x/text v0.3.2 // indirect
)
```

# 第三部分 连接测试

准备工作完成后，可以按照Go语言中标准的数据库操作方式进行验证，示例代码如下：

```go
import (
	"database/sql"
	_ "dm"
	"testing"
)

func TestConnDm(t *testing.T) {
	db, err := sql.Open("dm", "连接串")
	if err != nil {
		t.Fatal(err)
	}
	defer db.Close()
	// 检测连通性
	err = db.Ping()
	if err != nil {
		t.Fatal(err)
	}
	// 查询数据库版本信息
	rows, err := db.Query("select * from v$version")
	if err != nil {
		t.Fatal(err)
	}
	defer rows.Close()
	for rows.Next() {
		var version string
		rows.Scan(&version)
		t.Log(version)
	}
	if rows.Err() != nil {
		t.Fatal(rows.Err())
	}
}
```

连接字符串可参考官网说明，常用格式如下：
```
dm://user:password@host:port[?propName1=propValue1][&propName2=propValue2]…
dm://user:password@GroupName[?propName1=propValue1][&propName2=propValue2]…
dm://user:password@GroupName?GroupName=(host1:port1,host2:port2,…)[&propName1=propValue1]…
dm://user:password@host:port?dialName=anyName[&propName1=propValue1]…
```

Go操作达梦数据库

# 第一部分 概述

本文主要从以下几个维度进行对**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)

第一部分概述

第一部分概述

第一部分概述

第一部分概述

第一部分概述

第一部分 概述

第一部分 概述

第一部分 概述

第一部分 概述

第一部分 概述

第一部分概述

第一部分概述

第一部分概述

第一部分概述

第一部分概述