feat(apigw-manager): 补充 MCP Server 同步相关文档、脚本和配置样例 (#259)

Author: Han-Ya-Jun

sdks/apigw-manager/CHANGE.md

@@ -1,5 +1,12 @@
 ## Change logs
 
+### 4.2.3
+
+- 支持同步网关环境 MCP Server 配置，新增 Django Command `sync_apigw_stage_mcp_servers`
+- 基础镜像 sync-apigateway.sh 支持通过环境变量 `ENABLE_SYNC_MCP_SERVERS=true` 开启 MCP Server 同步
+- DRF 集成支持 MCP Server 配置生成与同步（`gen_apigateway_resource_config` 新增 `enable_mcp`/`none_schema` 参数）
+- 完善 examples 中的 definition.yaml 和 sync-apigateway.sh 样例，添加 MCP Server 配置示例
+
 ### 4.1.0
 
 - [breaking change] 做了多租户改造的全租户应用必须显式设置 `BK_APP_TENANT_ID=system` (环境变量或django settings)

sdks/apigw-manager/bin/sync-apigateway.sh

@@ -27,7 +27,7 @@ call_definition_command_or_exit create_version_and_release_apigw "${definition_f
 
 if [[ "${ENABLE_SYNC_MCP_SERVERS}" = "true" ]]; then
     title "syncing stage MCP Servers"
-    call_definition_command_or_exit sync_apigw_stage_mcp_servers "${definition_file}"
+    call_definition_command_or_exit sync_apigw_stage_mcp_servers "${definition_file}" ${SYNC_APIGW_STAGE_MCP_SERVERS_ARGS}
 fi
 
 log_info "done"

sdks/apigw-manager/docs/sync-apigateway-with-docker.md

@@ -33,6 +33,7 @@
 - `SYNC_RESOURCE_DOCS_BY_ARCHIVE_ARGS`: 默认值： "--safe-mode"，用于命令 `sync_resource_docs_by_archive`，同步网关文档
 - `CREATE_VERSION_AND_RELEASE_APIGW_ARGS`: 默认值："--generate-sdks"，用于命令 `create_version_and_release_apigw`,创建资源版本并发布
 - `ENABLE_SYNC_MCP_SERVERS`: 用于命令 `sync_apigw_stage_mcp_servers`, 是否开启同步环境 MCP Server
+- `SYNC_APIGW_STAGE_MCP_SERVERS_ARGS`: 用于命令 `sync_apigw_stage_mcp_servers`，同步环境 MCP Server 的额外参数
 
 基础镜像提供了一些自定义同步脚本常用的 bash 函数，以及执行 Django Command 指令的辅助脚本：
 
@@ -87,6 +88,9 @@ title "releasing"
 # 指定参数 --no-pub 则只生成版本，不发布
 call_definition_command_or_exit create_version_and_release_apigw "${definition_file}" --gateway-name=${gateway_name}
 
+# 可选：需要同步 MCP Server 时调用。注意：前提是该 stage 有生效的版本且声明的 mcp tool 在生效版本的资源列表里且确认过请求参数
+# call_definition_command_or_exit sync_apigw_stage_mcp_servers "${definition_file}" --gateway-name=${gateway_name}
+
 log_info "done"
 ```
 
@@ -314,4 +318,7 @@ call_definition_command_or_exit sync_apigw_stage "${definition_file}" --gateway-
 
 # 可选，同步资源文档
 call_definition_command_or_exit sync_resource_docs_by_archive "${definition_file}" --gateway-name=${gateway_name} --safe-mode
+
+# 可选：需要同步 MCP Server 时调用。注意：前提是该 stage 有生效的版本且声明的 mcp tool 在生效版本的资源列表里且确认过请求参数
+# call_definition_command_or_exit sync_apigw_stage_mcp_servers "${definition_file}" --gateway-name=${gateway_name}
 ```

sdks/apigw-manager/examples/chart/use-configmap/files/support-files/bin/sync-apigateway.sh

@@ -32,7 +32,7 @@ call_definition_command_or_exit create_version_and_release_apigw "${definition_f
 
 if [[ "${ENABLE_SYNC_MCP_SERVERS}" = "true" ]]; then
     title "syncing stage MCP Servers"
-    call_definition_command_or_exit sync_apigw_stage_mcp_servers "${definition_file}"
+    call_definition_command_or_exit sync_apigw_stage_mcp_servers "${definition_file}" --gateway-name=${gateway_name}
 fi
 
 log_info "done"

sdks/apigw-manager/examples/chart/use-configmap/files/support-files/definition.yaml

@@ -26,6 +26,28 @@ stages:
           # 网关调用后端服务的默认域名或IP，不包含Path，比如：http://api.example.com
            - host: "https://httpbin.org"
              weight: 100
+
+    # 同步 MCP Server 相关配置（可选）
+    # mcp_servers:
+    #   - name: "mcp_server1"
+    #     # MCP Server 中文名/显示名称
+    #     title: "MCP Server 示例"
+    #     description: "mcp-server demo"
+    #     labels:
+    #       - "test"
+    #     # 添加的 tool 对应的资源名称
+    #     resource_names:
+    #       - resource1
+    #     # 是否公开
+    #     is_public: true
+    #     # 1: 开启, 0: 停止; 默认是开启
+    #     status: 1
+    #     # MCP 协议类型: sse（默认）、streamable_http
+    #     protocol_type: "sse"
+    #     # 授权的应用
+    #     target_app_codes:
+    #       - "bk_app_code1"
+
     # 环境插件配置
     # plugin_configs:
     #     - type: bk-rate-limit

sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/bin/sync-apigateway.sh

@@ -30,11 +30,9 @@ title "releasing"
 # 指定参数 --no-pub 则只生成版本，不发布
 call_definition_command_or_exit create_version_and_release_apigw "${definition_file}" --gateway-name=${gateway_name}
 
-title "done"
-
-if [[ "${ENABLE_MCP_SERVER}" = "true" ]]; then
+if [[ "${ENABLE_SYNC_MCP_SERVERS}" = "true" ]]; then
     title "syncing stage MCP Servers"
-    call_definition_command_or_exit sync_apigw_stage_mcp_servers "${definition_file}"
+    call_definition_command_or_exit sync_apigw_stage_mcp_servers "${definition_file}" --gateway-name=${gateway_name}
 fi
 
 log_info "done"

sdks/apigw-manager/examples/chart/use-custom-docker-image/my-apigw-manager/support-files/definition.yaml

@@ -27,6 +27,27 @@ stages:
            - host: "https://httpbin.org"
              weight: 100
 
+    # 同步 MCP Server 相关配置（可选）
+    # mcp_servers:
+    #   - name: "mcp_server1"
+    #     # MCP Server 中文名/显示名称
+    #     title: "MCP Server 示例"
+    #     description: "mcp-server demo"
+    #     labels:
+    #       - "test"
+    #     # 添加的 tool 对应的资源名称
+    #     resource_names:
+    #       - resource1
+    #     # 是否公开
+    #     is_public: true
+    #     # 1: 开启, 0: 停止; 默认是开启
+    #     status: 1
+    #     # MCP 协议类型: sse（默认）、streamable_http
+    #     protocol_type: "sse"
+    #     # 授权的应用
+    #     target_app_codes:
+    #       - "bk_app_code1"
+
     # 环境插件配置
     # plugin_configs:
     #     - type: bk-rate-limit

sdks/apigw-manager/examples/django/use-custom-script/support-files/bin/sync-apigateway.sh

@@ -23,6 +23,10 @@ python manage.py sync_apigw_stage --gateway-name=${gateway_name} --file="${defin
 python manage.py sync_apigw_resources --delete --gateway-name=${gateway_name} --file="${resources_file}"
 python manage.py sync_resource_docs_by_archive --gateway-name=${gateway_name} --file="${definition_file}"
 python manage.py create_version_and_release_apigw --gateway-name=${gateway_name} --file="${definition_file}"
+
+# 可选：需要同步 MCP Server 时调用。注意：前提是该 stage 有生效的版本且声明的 mcp tool 在生效版本的资源列表里且确认过请求参数
+# python manage.py sync_apigw_stage_mcp_servers --gateway-name=${gateway_name} --file="${definition_file}"
+
 python manage.py grant_apigw_permissions --gateway-name=${gateway_name} --file="${definition_file}"
 python manage.py fetch_apigw_public_key --gateway-name=${gateway_name}
 echo "gateway ${gateway_name} sync definition end"

sdks/apigw-manager/examples/django/use-custom-script/support-files/definition.yaml

@@ -27,6 +27,27 @@ stages:
            - host: "https://httpbin.org"
              weight: 100
 
+    # 同步 MCP Server 相关配置（可选）
+    # mcp_servers:
+    #   - name: "mcp_server1"
+    #     # MCP Server 中文名/显示名称
+    #     title: "MCP Server 示例"
+    #     description: "mcp-server demo"
+    #     labels:
+    #       - "test"
+    #     # 添加的 tool 对应的资源名称
+    #     resource_names:
+    #       - resource1
+    #     # 是否公开
+    #     is_public: true
+    #     # 1: 开启, 0: 停止; 默认是开启
+    #     status: 1
+    #     # MCP 协议类型: sse（默认）、streamable_http
+    #     protocol_type: "sse"
+    #     # 授权的应用
+    #     target_app_codes:
+    #       - "bk_app_code1"
+
 # 资源文档
 # 资源文档的目录格式样例如下，en 为英文文档，zh 为中文文档：
 # ./