feat(spanner-admin): spanner admin source + create instance tool

.ci/integration.cloudbuild.yaml

@@ -340,6 +340,26 @@ steps:
           spanner \
           spanner || echo "Integration tests failed." # ignore test failures
 
+  - id: "spanner-admin"
+    name: golang:1
+    waitFor: ["compile-test-binary"]
+    entrypoint: /bin/bash
+    env:
+      - "GOPATH=/gopath"
+      - "SPANNER_PROJECT=$PROJECT_ID"
+      - "SERVICE_ACCOUNT_EMAIL=$SERVICE_ACCOUNT_EMAIL"
+    secretEnv: ["CLIENT_ID"]
+    volumes:
+      - name: "go"
+        path: "/gopath"
+    args:
+      - -c
+      - |
+        .ci/test_with_coverage.sh \
+          "Spanner Admin" \
+          spanneradmin \
+          spanneradmin || echo "Integration tests failed."
+
   - id: "neo4j"
     name: golang:1
     waitFor: ["compile-test-binary"]

cmd/root.go

@@ -217,6 +217,7 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannerlistgraphs"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannerlisttables"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/spanner/spannersql"
+	_ "github.com/googleapis/genai-toolbox/internal/tools/spanneradmin/spannercreateinstance"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/sqlite/sqliteexecutesql"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/sqlite/sqlitesql"
 	_ "github.com/googleapis/genai-toolbox/internal/tools/tidb/tidbexecutesql"
@@ -261,6 +262,7 @@ import (
 	_ "github.com/googleapis/genai-toolbox/internal/sources/serverlessspark"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/singlestore"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/spanner"
+	_ "github.com/googleapis/genai-toolbox/internal/sources/spanneradmin"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/sqlite"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/tidb"
 	_ "github.com/googleapis/genai-toolbox/internal/sources/trino"

docs/SPANNERADMIN_README.md

@@ -0,0 +1,59 @@
+# Cloud Spanner Admin MCP Server
+
+The Cloud Spanner Admin Model Context Protocol (MCP) Server gives AI-powered development tools the ability to manage your Google Cloud Spanner infrastructure. It supports creating instances.
+
+## Features
+
+An editor configured to use the Cloud Spanner Admin MCP server can use its AI capabilities to help you:
+
+- **Provision & Manage Infrastructure** - Create Cloud Spanner instances
+
+## Prerequisites
+
+*   [Node.js](https://nodejs.org/) installed.
+*   A Google Cloud project with the **Cloud Spanner Admin API** enabled.
+*   Ensure [Application Default Credentials](https://cloud.google.com/docs/authentication/gcloud) are available in your environment.
+*   IAM Permissions:
+    *   Cloud Spanner Admin (`roles/spanner.admin`)
+
+## Install & Configuration
+
+In the Antigravity MCP Store, click the "Install" button.
+
+You'll now be able to see all enabled tools in the "Tools" tab.
+
+> [!NOTE]
+> If you encounter issues with Windows Defender blocking the execution, you may need to configure an allowlist. See [Configure exclusions for Microsoft Defender Antivirus](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/configure-exclusions-microsoft-defender-antivirus?view=o365-worldwide) for more details.
+
+## Usage
+
+Once configured, the MCP server will automatically provide Cloud Spanner Admin capabilities to your AI assistant. You can:
+
+   * "Create a new Spanner instance named 'my-spanner-instance' in the 'my-gcp-project' project with config 'regional-us-central1', edition 'ENTERPRISE', and 1 node."
+
+## Server Capabilities
+
+The Cloud Spanner Admin MCP server provides the following tools:
+
+| Tool Name         | Description                      |
+|:------------------|:---------------------------------|
+| `create_instance` | Create a Cloud Spanner instance. |
+
+## Custom MCP Server Configuration
+
+Add the following configuration to your MCP client (e.g., `settings.json` for Gemini CLI, `mcp_config.json` for Antigravity):
+
+```json
+{
+  "mcpServers": {
+    "spanner-admin": {
+      "command": "npx",
+      "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "spanner-admin", "--stdio"]
+    }
+  }
+}
+```
+
+## Documentation
+
+For more information, visit the [Cloud Spanner Admin API documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.instance.v1).

docs/en/resources/sources/spanner-admin.md

@@ -0,0 +1,42 @@
+---
+title: Spanner Admin
+type: docs
+weight: 1
+description: "A \"spanner-admin\" source provides a client for the Cloud Spanner Admin API.\n"
+alias: [/resources/sources/spanner-admin]
+---
+
+## About
+
+The `spanner-admin` source provides a client to interact with the [Google
+Cloud Spanner Admin API](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.instance.v1). This
+allows tools to perform administrative tasks on Spanner instances, such as
+creating instances.
+
+Authentication can be handled in two ways:
+
+1.  **Application Default Credentials (ADC):** By default, the source uses ADC
+    to authenticate with the API.
+2.  **Client-side OAuth:** If `useClientOAuth` is set to `true`, the source will
+    expect an OAuth 2.0 access token to be provided by the client (e.g., a web
+    browser) for each request.
+
+## Example
+
+```yaml
+sources:
+    my-spanner-admin:
+        kind: spanner-admin
+
+    my-oauth-spanner-admin:
+        kind: spanner-admin
+        useClientOAuth: true
+```
+
+## Reference
+
+| **field**      | **type** | **required** | **description**                                                                                                                                |
+| -------------- | :------: | :----------: | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| kind           |  string  |     true     | Must be "spanner-admin".                                                                                                                       |
+| defaultProject |  string  |     false    | The Google Cloud project ID to use for Spanner infrastructure tools.                                                                           |
+| useClientOAuth |  boolean |     false    | If true, the source will use client-side OAuth for authorization. Otherwise, it will use Application Default Credentials. Defaults to `false`. |

docs/en/resources/tools/spanneradmin/spanner-create-instance.md

@@ -0,0 +1,52 @@
+---
+title: spanner-create-instance
+type: docs
+weight: 2
+description: "Create a Cloud Spanner instance."
+---
+
+The `spanner-create-instance` tool creates a new Cloud Spanner instance in a
+specified Google Cloud project.
+
+{{< notice info >}}
+This tool uses the `spanner-admin` source.
+{{< /notice >}}
+
+## Configuration
+
+Here is an example of how to configure the `spanner-create-instance` tool in
+your `tools.yaml` file:
+
+```yaml
+sources:
+  my-spanner-admin-source:
+    kind: spanner-admin
+
+tools:
+  create_my_spanner_instance:
+    kind: spanner-create-instance
+    source: my-spanner-admin-source
+    description: "Creates a Spanner instance."
+```
+
+## Parameters
+
+The `spanner-create-instance` tool has the following parameters:
+
+| **field**       | **type** | **required** | **description**                                                                      |
+| --------------- | :------: | :----------: | ------------------------------------------------------------------------------------ |
+| project         |  string  |     true     | The Google Cloud project ID.                                                         |
+| instanceId      |  string  |     true     | The ID of the instance to create.                                                    |
+| displayName     |  string  |     true     | The display name of the instance.                                                    |
+| config          |  string  |     true     | The instance configuration (e.g., `regional-us-central1`).                           |
+| nodeCount       | integer  |     true     | The number of nodes. Mutually exclusive with `processingUnits` (one must be 0).      |
+| processingUnits | integer  |     true     | The number of processing units. Mutually exclusive with `nodeCount` (one must be 0). |
+| edition         |  string  |    false     | The edition of the instance (`STANDARD`, `ENTERPRISE`, `ENTERPRISE_PLUS`).           |
+
+## Reference
+
+| **field**   | **type** | **required** | **description**                                              |
+| ----------- | :------: | :----------: | ------------------------------------------------------------ |
+| kind        |  string  |     true     | Must be `spanner-create-instance`.                           |
+| source      |  string  |     true     | The name of the `spanner-admin` source to use for this tool. |
+| description |  string  |    false     | A description of the tool that is passed to the agent.       |

internal/prebuiltconfigs/prebuiltconfigs_test.go

@@ -49,6 +49,7 @@ var expectedToolSources = []string{
 	"postgres",
 	"serverless-spark",
 	"singlestore",
+	"spanner-admin",
 	"spanner-postgres",
 	"spanner",
 	"sqlite",

internal/prebuiltconfigs/tools/spanner-admin.yaml

@@ -0,0 +1,27 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+sources:
+  spanner-admin-source:
+    kind: spanner-admin
+    defaultProject: ${SPANNER_PROJECT:}
+
+tools:
+  create_instance:
+    kind: spanner-create-instance
+    source: spanner-admin-source
+
+toolsets:
+  spanner_admin_tools:
+    - create_instance

internal/sources/spanneradmin/spanneradmin.go

@@ -0,0 +1,116 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package spanneradmin
+
+import (
+	"context"
+	"fmt"
+
+	instance "cloud.google.com/go/spanner/admin/instance/apiv1"
+	"github.com/goccy/go-yaml"
+	"github.com/googleapis/genai-toolbox/internal/sources"
+	"github.com/googleapis/genai-toolbox/internal/util"
+	"go.opentelemetry.io/otel/trace"
+	"golang.org/x/oauth2"
+	"google.golang.org/api/option"
+)
+
+const SourceKind string = "spanner-admin"
+
+// validate interface
+var _ sources.SourceConfig = Config{}
+
+func init() {
+	if !sources.Register(SourceKind, newConfig) {
+		panic(fmt.Sprintf("source kind %q already registered", SourceKind))
+	}
+}
+
+func newConfig(ctx context.Context, name string, decoder *yaml.Decoder) (sources.SourceConfig, error) {
+	actual := Config{Name: name}
+	if err := decoder.DecodeContext(ctx, &actual); err != nil {
+		return nil, err
+	}
+	return actual, nil
+}
+
+type Config struct {
+	Name           string `yaml:"name" validate:"required"`
+	Kind           string `yaml:"kind" validate:"required"`
+	DefaultProject string `yaml:"defaultProject"`
+	UseClientOAuth bool   `yaml:"useClientOAuth"`
+}
+
+func (r Config) SourceConfigKind() string {
+	return SourceKind
+}
+
+// Initialize initializes a Spanner Admin Source instance.
+func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {
+	var client *instance.InstanceAdminClient
+
+	if !r.UseClientOAuth {
+		ua, err := util.UserAgentFromContext(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("error in User Agent retrieval: %s", err)
+		}
+		// Use Application Default Credentials
+		client, err = instance.NewInstanceAdminClient(ctx, option.WithUserAgent(ua))
+		if err != nil {
+			return nil, fmt.Errorf("error creating new spanner instance admin client: %w", err)
+		}
+	}
+
+	s := &Source{
+		Config: r,
+		Client: client,
+	}
+	return s, nil
+}
+
+var _ sources.Source = &Source{}
+
+type Source struct {
+	Config
+	Client *instance.InstanceAdminClient
+}
+
+func (s *Source) SourceKind() string {
+	return SourceKind
+}
+
+func (s *Source) ToConfig() sources.SourceConfig {
+	return s.Config
+}
+
+func (s *Source) GetClient(ctx context.Context, accessToken string) (*instance.InstanceAdminClient, error) {
+	if s.UseClientOAuth {
+		token := &oauth2.Token{AccessToken: accessToken}
+		ua, err := util.UserAgentFromContext(ctx)
+		if err != nil {
+			return nil, err
+		}
+		client, err := instance.NewInstanceAdminClient(ctx, option.WithTokenSource(oauth2.StaticTokenSource(token)), option.WithUserAgent(ua))
+		if err != nil {
+			return nil, fmt.Errorf("error creating new spanner instance admin client: %w", err)
+		}
+		return client, nil
+	}
+	return s.Client, nil
+}
+
+func (s *Source) UseClientAuthorization() bool {
+	return s.UseClientOAuth
+}