企业官网建设流程全解析

Klavis 中的 Google Cloud MCP Server 开发指南：四大 GCP 服务管理器的架构、认证与实操

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis

本篇技术指南面向希望在 Klavis 开源仓库中开发、调试或扩展 Google Cloud MCP Server 的开发者，围绕 mcp_servers/google_cloud_toolathlon/CLAUDE.md 这份面向 AI 编码助手的开发规范展开。文章将完整讲解该 MCP Server 的模块化架构、BigQuery / Cloud Logging / Cloud Storage / Compute Engine 四个管理器类的统一设计模式、双通道认证（服务账号与默认凭据）、项目 ID 解析策略以及常见运维操作，并结合仓库内 src/server.py、src/big_query.py 等源码给出可验证的实现细节。读完本文，你将掌握该项目的代码组织方式、开发调试命令、认证接入流程与每一类 MCP 工具的真实调用链。

项目概述：面向 GCP 的 MCP 服务端

google_cloud_toolathlon是一个基于 Model Context Protocol（MCP）的 Google Cloud Platform 服务管理服务器。它通过 Python 包装模块将 GCP 各服务的客户端操作封装为高层方法，再以 MCP 工具（tool）的形式暴露给 AI 模型调用，使 LLM 能够直接执行查询、读写日志、管理存储桶、启停虚拟机等云资源操作。

从 requirements.txt 可以看到它的技术栈：以fastmcp==2.10.6与mcp==1.12.2实现 MCP 协议层，以google-cloud-bigquery==3.35.1、google-cloud-storage==3.2.0、google-cloud-logging==3.12.1、google-cloud-compute==1.33.0四个官方 SDK 对接 GCP 服务，并用uvicorn==0.35.0与starlette==0.47.2承载 HTTP 传输。

该服务端支持三类传输方式（在 src/server.py 的main()中可见）：

• SSE：http://<host>:<port>/sse事件流端点，配套/messages/消息回传端点；
• StreamableHTTP：http://<host>:<port>/mcp挂载点，基于StreamableHTTPSessionManager，无状态（stateless=True）设计；
• stdio：通过--transport stdio启用，用于兼容旧式本地客户端。

服务端默认监听0.0.0.0:5000，主机与端口可由HOST/PORT或FASTMCP_HOST/FASTMCP_PORT环境变量覆盖。

架构：按 GCP 服务拆分的模块化管理器

项目采用"一服务一管理器"的模块化架构，每个 GCP 服务拥有独立的 Python 模块与管理器类：

四个管理器统一由 src/server.py 编排。服务端在启动时通过setup_server()初始化全局配置与四个管理器实例，并将每个管理器的核心方法通过@mcp.tool()装饰器注册为 MCP 工具。

统一的设计模式

从 CLAUDE.md 与各管理器源码可以归纳出一致的模式：

1. 构造函数签名统一：接收project_id与可选的service_account_path，部分管理器（如BigQueryManager）还额外支持传入预构建的credentials对象，用于 OAuth 令牌场景（big_query.py）。
2. 方法返回结构化字典：所有方法返回Dict/List[Dict]，而非原生 GCP 对象，便于 JSON 序列化后直接返回给 MCP 客户端。例如CloudStorageManager通过_bucket_to_dict()与_blob_to_dict()两个辅助方法标准化 bucket / blob 的返回格式（cloud_storage.py）。
3. 完整的异常处理与日志：所有方法均包含 try/except 块，针对 Google Cloud 的NotFound、AlreadyExists、Conflict等异常做专门处理（如 cloud_logging.py 中create_log_bucket捕获exceptions.AlreadyExists、delete_log_bucket捕获exceptions.NotFound），并以logging全程记录调试信息。
4. 可选参数使用合理默认值：如 BigQuery 查询默认max_results、日志读取默认时间范围为 24 小时等。

开发命令与环境搭建

依赖安装

CLAUDE.md 提供了两条安装路径（以仓库内 requirements.txt 为准）：

# 方式一：按 pyproject.toml 配置的编辑模式安装 pip install -e . # 方式二：手动安装四个 Google Cloud 官方库 pip install google-cloud-bigquery google-cloud-logging google-cloud-storage google-cloud-compute

生产或离线环境建议直接使用仓库自带的 requirements.txt（已锁定版本并注明来源于 uv.lock，可避免 pip 缓慢解析）。

认证配置

项目支持两种认证方式：

• 服务账号文件：在项目根目录放置service-account-key.json。各管理器构造函数通过service_account.Credentials.from_service_account_file()加载，并申请https://www.googleapis.com/auth/cloud-platform全量云平台作用域（见 big_query.py）。
• 默认凭据：执行gcloud auth application-default login后省略服务账号参数，SDK 自动使用环境中的 ADC（Application Default Credentials）。

启动服务

python main.py

启动入口位于 src/server.py 的main()，完整的命令行参数如下：

Docker 部署

仓库提供 Dockerfile，基于python:3.12-slim镜像，内置HOST=0.0.0.0、PORT=5000环境变量，容器启动命令为python -m src.server，PROJECT_ID需在运行期通过-e或.env注入。详细的 Docker 构建与运行方式（含服务账号只读挂载、访问控制列表注入）见 README.Docker.md。

双通道认证与项目 ID 解析

两种认证模式

CLAUDE.md 明确列出两种认证模式：

1. 服务账号文件：在构造函数中传入 JSON 密钥文件路径；
2. 默认凭据：省略服务账号参数，使用环境中的环境凭据。

第三种模式：逐请求 OAuth 令牌（源码补充）

从 server.py 的源码结构看，项目还支持逐请求（per-request）OAuth 认证：通过ContextVar保存每次请求的auth_token、auth_project、refresh_token、token_uri、client_id、client_secret。这些数据来自两条通道：

• 环境变量AUTH_DATA（JSON 字符串）；
• HTTP 请求头x-auth-data（Base64 编码的 JSON，_get_auth_data_raw()会同时处理 SSE 的 request 对象与 StreamableHTTP 的 scope 字典）。

extract_auth_data()从原始数据中解析出六元组，_get_oauth_credentials()则将其组装为google.oauth2.credentials.Credentials。当存在逐请求令牌时，get_bigquery_manager()/get_storage_manager()等工厂函数会优先使用该令牌构造对应管理器（server.py），这使多租户场景下每个请求可以携带独立的用户授权。

项目 ID 的三级解析顺序

_get_project_id()按以下顺序解析生效的项目 ID（server.py）：

1. 逐请求认证数据中的project_id（最高优先级）；
2. 全局配置PROJECT_ID（来自 CLI 参数或环境变量）；
3. 自动解析：通过 OAuth 凭据调用 Cloud Resource Manager API 的projects().search()；当只有一个项目时直接返回；有多个项目时，尝试匹配账号邮箱前缀与项目displayName，失败则回退到第一个项目。解析结果会缓存到 ContextVar 中，同一请求内的后续调用不再重复请求。

若以上均不可用，服务端会抛出RuntimeError，提示需要通过认证数据提供project_id、设置PROJECT_ID/GOOGLE_CLOUD_PROJECT环境变量或提供可自动解析的 OAuth 凭据。

资源级访问控制

服务端在setup_server()中将四个--allowed-*参数解析为逗号分隔的集合（ALLOWED_BUCKETS、ALLOWED_DATASETS、ALLOWED_LOG_BUCKETS、ALLOWED_INSTANCES），并通过四个validate_*_access()函数实施控制。

_matches_allowed_pattern()支持通配符前缀匹配：允许列表中的prefix*模式可以匹配所有以该前缀开头的资源名；未配置任何限制时默认放行（server.py）。所有 MCP 工具在操作前都会先校验资源是否在白名单内，例如storage_upload_file会先调用validate_bucket_access(bucket_name)，bigquery_create_dataset会先调用validate_dataset_access(dataset_id)，越权访问会直接返回Access denied提示而非执行操作。

各服务管理器常见操作详解

BigQuery：查询、加载、导出与费用估算

BigQueryManager的run_query()支持 dry-run 模式，通过QueryJobConfig(dry_run=True)只校验查询而不真正执行，并从作业对象中读取total_bytes_processed/total_bytes_billed计算预估费用（按$5/TB单价估算，见 big_query.py）。非 dry-run 模式下返回结果列表、总行数、处理字节数、计费字节数、执行耗时（毫秒）与作业 ID。

围绕该管理器注册的 MCP 工具包括：

• bigquery_run_query(query, dry_run, max_results)：执行 SQL 查询，dry-run 时返回预估字节数与费用；
• bigquery_list_datasets/bigquery_create_dataset(dataset_id, description, location)/bigquery_get_dataset_info(dataset_id)：数据集管理；
• bigquery_load_csv_data(dataset_id, table_id, csv_file_path, skip_header, write_mode)：CSV 加载，write_mode支持WRITE_TRUNCATE/WRITE_APPEND/WRITE_EMPTY，对应底层load_data_from_csv()的write_disposition；
• bigquery_export_table(dataset_id, table_id, destination_bucket, destination_path, file_format)：导出到 Cloud Storage，当前仅支持 CSV 格式（底层调用export_table_to_csv()）；
• bigquery_list_jobs(max_results, state_filter)/bigquery_cancel_job(job_id)：作业管理与取消。

Cloud Logging：读写日志与 sink 导出

CloudLoggingManager提供结构化的日志读写能力：

• write_log()支持文本日志（log_text）与结构化日志（log_struct），默认资源类型为global，severity 取DEBUG/INFO/WARNING/ERROR/CRITICAL；
• read_logs()自动追加timestamp >= "..."时间范围过滤（默认最近 24 小时），支持自定义过滤字符串，并按timestamp desc排序返回；
• search_logs()提供了简化的检索参数：search_query、time_range_hours、resource_types、severity_levels，内部构造(textPayload:"..." OR jsonPayload:"...")等组合过滤条件。

日志基础设施管理围绕config_service_v2.ConfigServiceV2Client展开（cloud_logging.py）：

• log bucket：create_log_bucket()/update_log_bucket()/delete_log_bucket()/clear_log_bucket()。其中删除与清空操作都会先检查 bucket 是否处于locked状态，锁定 bucket 不可删除（防止误删保留数据）；
• log sink：create_log_sink()创建导出路由，export_logs_to_storage()构造storage.googleapis.com/<bucket>目标，export_logs_to_bigquery()构造bigquery.googleapis.com/projects/<project>/datasets/<dataset>目标，创建时启用unique_writer_identity，并在返回的writer_identity中提示需要授予写权限；
• log exclusion：create_exclusion()/list_exclusions()/delete_exclusion()用于按过滤条件排除日志。

对应 MCP 工具包括logging_write_log、logging_read_logs、logging_list_logs、logging_delete_log、logging_create_log_sink、logging_list_log_sinks、logging_delete_log_sink、logging_export_logs_to_bigquery、logging_create_log_bucket等。值得注意的细节：logging_list_logs在配置了ALLOWED_LOG_BUCKETS时会联动列出受限 bucket、其路由 sink 与近 7 天的实际日志名，形成一份"受限可见"的日志清单（server.py）。

Cloud Storage：对象操作与生命周期

CloudStorageManager覆盖 bucket 与对象两级操作，辅助方法_bucket_to_dict()/_blob_to_dict()统一返回格式。围绕它注册的 MCP 工具包括：

• storage_create_bucket/storage_list_buckets/storage_get_bucket_info/storage_get_bucket_size：bucket 管理，其中storage_get_bucket_size返回对象总数与字节数（含 MB / GB 换算）；
• storage_upload_file/storage_download_file/storage_delete_object/storage_list_objects：对象 CRUD；
• storage_copy_object/storage_move_object：桶内或跨桶复制、移动；
• storage_generate_signed_url：生成带过期时间的临时访问 URL（默认 60 分钟，支持 GET / PUT / POST / DELETE）；
• storage_enable_versioning：开关版本控制；
• storage_set_bucket_lifecycle：设置生命周期策略（如对象超过 N 天后自动删除）。

Compute Engine：实例生命周期管理

ComputeEngineManager提供虚拟机实例的全生命周期操作：创建、删除、启动、停止、重启、查询详情、列出可用区。compute_restart_instance在重启前会先查询实例状态，仅允许RUNNING或STOPPING状态的实例重启，并在 GCP 返回"Invalid value for field ... RUNNING"错误时给出友好提示（server.py）。compute_wait_for_operation则用于同步等待异步操作完成，默认超时 5 分钟。

实战：接入 AI 客户端

将本项目接入 MCP 客户端（如 Claude Desktop）时，在客户端 MCP 配置中以uvx/python方式启动该服务端，并传入项目 ID、服务账号路径与资源白名单。配置要点：

1. 项目 ID：替换为真实 GCP Project ID（也可通过PROJECT_ID/GOOGLE_CLOUD_PROJECT环境变量注入）；
2. 服务账号：指向服务账号 JSON 文件路径；
3. 访问控制：通过逗号分隔列表限定可访问的 bucket、数据集、日志 bucket 与实例，最小化 AI 工具的攻击面。

安全与生产建议

结合 README.Docker.md 与 CLAUDE.md，生产部署应遵循：

• 服务账号遵循最小权限原则（如 BigQuery Data Editor、Storage Admin、Logging Admin、Compute Admin 视场景裁剪），并定期轮换密钥；
• 务必配置ALLOWED_*白名单限制 AI 可操作的资源范围；
• 凭据文件使用只读挂载（:ro），生产环境改用 Secrets 管理，切勿将密钥提交到版本控制；
• 使用编排平台（Kubernetes / Docker Swarm）部署，配置健康检查、重启策略、资源限制与负载均衡层 TLS 终结。

结语

google_cloud_toolathlon展示了一种清晰可复用的 GCP MCP Server 构建范式：按服务拆分管理器、统一字典化返回、双通道（服务账号 / 默认凭据 / 逐请求 OAuth）认证、三级项目 ID 解析与资源级访问控制。开发者可以以 CLAUDE.md 为开发基线，以 src/server.py 为工具注册入口，以四个管理器模块为实现蓝本，快速扩展新的 GCP 服务能力或接入自有 AI 工作流。

【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis