From ea9a6de8c30c21db119979ec3b5eccaceb852451 Mon Sep 17 00:00:00 2001 From: Jingze <52855280+Jing-ze@users.noreply.github.com> Date: Tue, 29 Apr 2025 22:08:10 +0800 Subject: [PATCH] fix: update golang filter README (#2147) --- plugins/golang-filter/README.md | 24 +++++-- plugins/golang-filter/README_en.md | 24 +++++-- .../{mcp-session => mcp-server}/README.md | 27 +++----- plugins/golang-filter/mcp-server/README_en.md | 60 +++++++++++++++++ .../golang-filter/mcp-session/README_en.md | 67 ------------------- 5 files changed, 110 insertions(+), 92 deletions(-) rename plugins/golang-filter/{mcp-session => mcp-server}/README.md (51%) create mode 100644 plugins/golang-filter/mcp-server/README_en.md delete mode 100644 plugins/golang-filter/mcp-session/README_en.md diff --git a/plugins/golang-filter/README.md b/plugins/golang-filter/README.md index f0d8a3f14..686c175d3 100644 --- a/plugins/golang-filter/README.md +++ b/plugins/golang-filter/README.md @@ -20,24 +20,38 @@ Golang HTTP Filter 允许开发者使用 Go 语言编写自定义的 Envoy Filte 请参考 [Envoy Golang HTTP Filter 示例](https://github.com/envoyproxy/examples/tree/main/golang-http) 了解如何开发和运行一个基本的 Golang Filter。 +## 插件注册 + +在开发新的 Golang Filter 时，需要在`main.go` 的 `init()` 函数中注册你的插件。注册时需要提供插件名称、Filter 工厂函数和配置解析器： + +```go +func init() { + envoyHttp.RegisterHttpFilterFactoryAndConfigParser( + "your-plugin-name", // 插件名称 + yourFilterFactory, // Filter 工厂函数 + &yourConfigParser{}, // 配置解析器 + ) +} +``` + ## 配置示例 +多个 Golang Filter 插件可以共同编译到一个 `golang-filter.so` 文件中，通过 `plugin_name` 来指定要使用的插件。配置示例如下： + ```yaml http_filters: - name: envoy.filters.http.golang typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config - library_id: my-go-filter - library_path: "./go-filter.so" - plugin_name: my-go-filter + library_id: your-plugin-name + library_path: "./golang-filter.so" # 包含多个插件的共享库文件 + plugin_name: your-plugin-name # 指定要使用的插件名称，需要与 init() 函数中注册的插件名称保持一致 plugin_config: "@type": type.googleapis.com/xds.type.v3.TypedStruct value: your_config_here: value - ``` - ## 快速构建 使用以下命令可以快速构建 golang filter 插件: diff --git a/plugins/golang-filter/README_en.md b/plugins/golang-filter/README_en.md index 9d0be9450..fc351c28e 100644 --- a/plugins/golang-filter/README_en.md +++ b/plugins/golang-filter/README_en.md @@ -20,16 +20,32 @@ The Golang HTTP Filter allows developers to write custom Envoy Filters using the Please refer to [Envoy Golang HTTP Filter Example](https://github.com/envoyproxy/examples/tree/main/golang-http) to learn how to develop and run a basic Golang Filter. +## Plugin Registration + +When developing a new Golang Filter, you need to register your plugin in the `init()` function of `main.go`. The registration requires a plugin name, Filter factory function, and configuration parser: + +```go +func init() { + envoyHttp.RegisterHttpFilterFactoryAndConfigParser( + "your-plugin-name", // Plugin name + yourFilterFactory, // Filter factory function + &yourConfigParser{}, // Configuration parser + ) +} +``` + ## Configuration Example +Multiple Golang Filter plugins can be compiled into a single `golang-filter.so` file, and the desired plugin can be specified using `plugin_name`. Here's an example configuration: + ```yaml http_filters: - name: envoy.filters.http.golang typed_config: "@type": type.googleapis.com/envoy.extensions.filters.http.golang.v3alpha.Config - library_id: my-go-filter - library_path: "./my-go-filter.so" - plugin_name: my-go-filter + library_id: your-plugin-name + library_path: "./golang-filter.so" # Shared library file containing multiple plugins + plugin_name: your-plugin-name # Specify which plugin to use, must match the name registered in init() plugin_config: "@type": type.googleapis.com/xds.type.v3.TypedStruct value: @@ -41,5 +57,5 @@ http_filters: Use the following command to quickly build the golang filter plugin: ```bash -GO_FILTER_NAME=mcp-server make build +make build ``` \ No newline at end of file diff --git a/plugins/golang-filter/mcp-session/README.md b/plugins/golang-filter/mcp-server/README.md similarity index 51% rename from plugins/golang-filter/mcp-session/README.md rename to plugins/golang-filter/mcp-server/README.md index e24407aad..0f5229acd 100644 --- a/plugins/golang-filter/mcp-session/README.md +++ b/plugins/golang-filter/mcp-server/README.md @@ -3,27 +3,22 @@ ## 概述 -MCP Server 是一个基于 Envoy 的 Golang Filter 插件，用于实现服务器端事件（SSE）和消息通信功能。该插件支持多种数据库类型，并使用 Redis 作为消息队列来实现负载均衡的请求通过对应的SSE连接发送。 +MCP Server 是一个基于 Envoy 的 Golang Filter 插件，提供了统一的 MCP (Model Context Protocol) 服务接口。它支持多种后端服务的集成，包括： -> **注意**：MCP Server需要 Higress 2.1.0 或更高版本才能使用。 -## 项目结构 -``` -mcp-server/ -├── config.go # 配置解析相关代码 -├── filter.go # 请求处理相关代码 -├── internal/ # 内部实现逻辑 -├── servers/ # MCP 服务器实现 -├── go.mod # Go模块依赖定义 -└── go.sum # Go模块依赖校验 -``` -## MCP Server开发指南 +- 数据库服务：通过 GORM 支持多种数据库的访问和管理 +- 配置中心：支持 Nacos 配置中心的集成 +- 可扩展性：支持自定义服务器实现，方便集成其他服务 + +> **注意**：MCP Server 需要 Higress 2.1.0 或更高版本才能使用。 + +## MCP Server 开发指南 ```go // 在init函数中注册你的服务器 // 参数1: 服务器名称 // 参数2: 配置结构体实例 func init() { - internal.GlobalRegistry.RegisterServer("demo", &DemoConfig{}) + common.GlobalRegistry.RegisterServer("demo", &DemoConfig{}) } // 服务器配置结构体 @@ -43,8 +38,8 @@ func (c *DBConfig) ParseConfig(config map[string]any) error { // 创建新的MCP服务器实例 // serverName: 服务器名称 // 返回值: MCP服务器实例和可能的错误 -func (c *DBConfig) NewServer(serverName string) (*internal.MCPServer, error) { - mcpServer := internal.NewMCPServer(serverName, Version) +func (c *DBConfig) NewServer(serverName string) (*common.MCPServer, error) { + mcpServer := common.NewMCPServer(serverName, Version) // 添加工具方法到服务器 // mcpServer.AddTool() diff --git a/plugins/golang-filter/mcp-server/README_en.md b/plugins/golang-filter/mcp-server/README_en.md new file mode 100644 index 000000000..653b264dd --- /dev/null +++ b/plugins/golang-filter/mcp-server/README_en.md @@ -0,0 +1,60 @@ +# MCP Server +English | [简体中文](./README.md) + +## Overview + +MCP Server is a Golang Filter plugin based on Envoy that provides a unified MCP (Model Context Protocol) service interface. It supports integration with various backend services, including: + +- Database Services: Supports multiple database access and management through GORM +- Configuration Service: Supports integration with Nacos configuration service +- Extensibility: Supports custom server implementations for easy integration with other services + +> **Note**: MCP Server requires Higress version 2.1.0 or higher to be used. + +## MCP Server Development Guide + +```go +// Register your server in the init function +// Parameter 1: Server name +// Parameter 2: Configuration struct instance +func init() { + common.GlobalRegistry.RegisterServer("demo", &DemoConfig{}) +} + +// Server configuration struct +type DemoConfig struct { + helloworld string +} + +// Parse configuration method +// Parse and validate configuration items from the config map +func (c *DBConfig) ParseConfig(config map[string]any) error { + helloworld, ok := config["helloworld"].(string) + if !ok { return errors.New("missing helloworld")} + c.helloworld = helloworld + return nil +} + +// Create a new MCP server instance +// serverName: Server name +// Returns: MCP server instance and possible error +func (c *DBConfig) NewServer(serverName string) (*common.MCPServer, error) { + mcpServer := common.NewMCPServer(serverName, Version) + + // Add tool methods to the server + // mcpServer.AddTool() + + // Add resources to the server + // mcpServer.AddResource() + + return mcpServer, nil +} +``` + +**Note**: +You need to use underscore imports in config.go to execute the package's init function +```go +import ( + _ "github.com/alibaba/higress/plugins/golang-filter/mcp-server/servers/gorm" +) +``` \ No newline at end of file diff --git a/plugins/golang-filter/mcp-session/README_en.md b/plugins/golang-filter/mcp-session/README_en.md deleted file mode 100644 index e107251bd..000000000 --- a/plugins/golang-filter/mcp-session/README_en.md +++ /dev/null @@ -1,67 +0,0 @@ -# MCP Server -English | [简体中文](./README.md) - -## Overview - -MCP Server is a Golang Filter plugin based on Envoy, designed to implement Server-Sent Events (SSE) and message communication functionality. This plugin supports various database types and uses Redis as a message queue to enable load-balanced requests to be sent through corresponding SSE connections. - -> **Note**: MCP Server requires Higress 2.1.0 or higher version. - -## Project Structure -``` -mcp-server/ -├── config.go # Configuration parsing code -├── filter.go # Request processing code -├── internal/ # Internal implementation logic -├── servers/ # MCP server implementation -├── go.mod # Go module dependency definition -└── go.sum # Go module dependency checksum -``` - -## MCP Server Development Guide - -```go -// Register your server in the init function -// Param 1: Server name -// Param 2: Config struct instance -func init() { - internal.GlobalRegistry.RegisterServer("demo", &DemoConfig{}) -} - -// Server configuration struct -type DemoConfig struct { - helloworld string -} - -// Configuration parsing method -// Parse and validate configuration items from the config map -func (c *DBConfig) ParseConfig(config map[string]any) error { - helloworld, ok := config["helloworld"].(string) - if !ok { return errors.New("missing helloworld")} - c.helloworld = helloworld - return nil -} - -// Create a new MCP server instance -// serverName: Server name -// Returns: MCP server instance and possible error -func (c *DBConfig) NewServer(serverName string) (*internal.MCPServer, error) { - mcpServer := internal.NewMCPServer(serverName, Version) - - // Add tool methods to server - // mcpServer.AddTool() - - // Add resources to server - // mcpServer.AddResource() - - return mcpServer, nil -} -``` - -**Note**: -Need to use underscore import in config.go to execute the package's init function -```go -import ( - _ "github.com/alibaba/higress/plugins/golang-filter/mcp-server/servers/gorm" -) -``` \ No newline at end of file