feat!: validate resource naming

docs/en/getting-started/colab_quickstart.ipynb

@@ -509,7 +509,7 @@
       },
       "outputs": [],
       "source": [
-        "! pip install toolbox-adk --quiet\n",
+        "! pip install toolbox-core --quiet\n",
         "! pip install google-adk --quiet"
       ]
     },
@@ -525,18 +525,14 @@
         "from google.adk.runners import Runner\n",
         "from google.adk.sessions import InMemorySessionService\n",
         "from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService\n",
-        "from google.adk.tools.toolbox_toolset import ToolboxToolset\n",
         "from google.genai import types\n",
+        "from toolbox_core import ToolboxSyncClient\n",
         "\n",
         "import os\n",
         "# TODO(developer): replace this with your Google API key\n",
         "os.environ['GOOGLE_API_KEY'] = \"<GOOGLE_API_KEY>\"\n",
         "\n",
-        "# Configure toolset\n",
-        "toolset = ToolboxToolset(\n",
-        "    server_url=\"http://127.0.0.1:5000\",\n",
-        "    toolset_name=\"my-toolset\"\n",
-        ")\n",
+        "toolbox_client = ToolboxSyncClient(\"http://127.0.0.1:5000\")\n",
         "\n",
         "prompt = \"\"\"\n",
         "  You're a helpful hotel assistant. You handle hotel searching, booking and\n",
@@ -553,7 +549,7 @@
         "    name='hotel_agent',\n",
         "    description='A helpful AI assistant.',\n",
         "    instruction=prompt,\n",
-        "    tools=[toolset],\n",
+        "    tools=toolbox_client.load_toolset(\"my-toolset\"),\n",
         ")\n",
         "\n",
         "session_service = InMemorySessionService()\n",

docs/en/getting-started/local_quickstart.md

@@ -52,7 +52,7 @@ runtime](https://research.google.com/colaboratory/local-runtimes.html).
     {{< tabpane persist=header >}}
 {{< tab header="ADK" lang="bash" >}}
 
-pip install toolbox-adk
+pip install toolbox-core
 {{< /tab >}}
 {{< tab header="Langchain" lang="bash" >}}
 

docs/en/getting-started/quickstart/python/adk/quickstart.py

@@ -1,17 +1,15 @@
 from google.adk import Agent
 from google.adk.apps import App
-from google.adk.tools.toolbox_toolset import ToolboxToolset
+from toolbox_core import ToolboxSyncClient
 
 # TODO(developer): update the TOOLBOX_URL to your toolbox endpoint
-toolset = ToolboxToolset(
-    server_url="http://127.0.0.1:5000",
-)
+client = ToolboxSyncClient("http://127.0.0.1:5000")
 
 root_agent = Agent(
     name='root_agent',
     model='gemini-2.5-flash',
     instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
-    tools=[toolset],
+    tools=client.load_toolset(),
 )
 
 app = App(root_agent=root_agent, name="my_agent")

docs/en/getting-started/quickstart/python/adk/requirements.txt

@@ -1,3 +1,3 @@
 google-adk==1.21.0
-toolbox-adk>=0.1.0
+toolbox-core==0.5.4
 pytest==9.0.2

docs/en/how-to/deploy_adk_agent.md

@@ -49,7 +49,7 @@ with the necessary configuration for deployment to Vertex AI Agent Engine.
 4.  Add `toolbox-core` as a dependency to the new project:
 
     ```bash
-    uv add toolbox-adk
+    uv add toolbox-core
     ```
 
 ## Step 3: Configure Google Cloud Authentication
@@ -95,23 +95,22 @@ authentication token.
     ```python
     from google.adk import Agent
     from google.adk.apps import App
-    from google.adk.tools.toolbox_toolset import ToolboxToolset
-    from toolbox_adk import CredentialStrategy
+    from toolbox_core import ToolboxSyncClient, auth_methods
 
     # TODO(developer): Replace with your Toolbox Cloud Run Service URL
     TOOLBOX_URL = "https://your-toolbox-service-xyz.a.run.app"
 
-    # Initialize the toolset with Workload Identity (generates ID token for the URL)
-    toolset = ToolboxToolset(
-        server_url=TOOLBOX_URL,
-        credentials=CredentialStrategy.workload_identity(target_audience=TOOLBOX_URL)
+    # Initialize the client with the Cloud Run URL and Auth headers
+    client = ToolboxSyncClient(
+        TOOLBOX_URL, 
+        client_headers={"Authorization": auth_methods.get_google_id_token(TOOLBOX_URL)}
     )
 
     root_agent = Agent(
         name='root_agent',
         model='gemini-2.5-flash',
         instruction="You are a helpful AI assistant designed to provide accurate and useful information.",
-        tools=[toolset],
+        tools=client.load_toolset(),
     )
 
     app = App(root_agent=root_agent, name="my_agent")

docs/en/samples/bigquery/local_quickstart.md

@@ -365,7 +365,7 @@ pip install llama-index-llms-google-genai
 
 {{< /tab >}}
 {{< tab header="ADK" lang="bash" >}}
-pip install toolbox-adk
+pip install toolbox-core
 {{< /tab >}}
 {{< /tabpane >}}
 
@@ -607,8 +607,8 @@ from google.adk.agents import Agent
 from google.adk.runners import Runner
 from google.adk.sessions import InMemorySessionService
 from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService
-from google.adk.tools.toolbox_toolset import ToolboxToolset
 from google.genai import types # For constructing message content
+from toolbox_core import ToolboxSyncClient
 
 import os
 os.environ['GOOGLE_GENAI_USE_VERTEXAI'] = 'True'
@@ -623,47 +623,48 @@ os.environ['GOOGLE_CLOUD_LOCATION'] = 'us-central1'
 
 # --- Load Tools from Toolbox ---
 
-# TODO(developer): Ensure the Toolbox server is running at http://127.0.0.1:5000
-toolset = ToolboxToolset(server_url="http://127.0.0.1:5000")
+# TODO(developer): Ensure the Toolbox server is running at <http://127.0.0.1:5000>
 
-# --- Define the Agent's Prompt ---
-prompt = """
-  You're a helpful hotel assistant. You handle hotel searching, booking and
-  cancellations. When the user searches for a hotel, mention it's name, id,
-  location and price tier. Always mention hotel ids while performing any
-  searches. This is very important for any operations. For any bookings or
-  cancellations, please provide the appropriate confirmation. Be sure to
-  update checkin or checkout dates if mentioned by the user.
-  Don't ask for confirmations from the user.
-"""
+with ToolboxSyncClient("<http://127.0.0.1:5000>") as toolbox_client:
+    # TODO(developer): Replace "my-toolset" with the actual ID of your toolset as configured in your MCP Toolbox server.
+    agent_toolset = toolbox_client.load_toolset("my-toolset")
 
-# --- Configure the Agent ---
+    # --- Define the Agent's Prompt ---
+    prompt = """
+      You're a helpful hotel assistant. You handle hotel searching, booking and
+      cancellations. When the user searches for a hotel, mention it's name, id,
+      location and price tier. Always mention hotel ids while performing any
+      searches. This is very important for any operations. For any bookings or
+      cancellations, please provide the appropriate confirmation. Be sure to
+      update checkin or checkout dates if mentioned by the user.
+      Don't ask for confirmations from the user.
+    """
 
-root_agent = Agent(
-    model='gemini-2.0-flash-001',
-    name='hotel_agent',
-    description='A helpful AI assistant that can search and book hotels.',
-    instruction=prompt,
-    tools=[toolset], # Pass the loaded toolset
-)
+    # --- Configure the Agent ---
 
-# --- Initialize Services for Running the Agent ---
-session_service = InMemorySessionService()
-artifacts_service = InMemoryArtifactService()
+    root_agent = Agent(
+        model='gemini-2.0-flash-001',
+        name='hotel_agent',
+        description='A helpful AI assistant that can search and book hotels.',
+        instruction=prompt,
+        tools=agent_toolset, # Pass the loaded toolset
+    )
 
-runner = Runner(
-    app_name='hotel_agent',
-    agent=root_agent,
-    artifact_service=artifacts_service,
-    session_service=session_service,
-)
-
-async def main():
+    # --- Initialize Services for Running the Agent ---
+    session_service = InMemorySessionService()
+    artifacts_service = InMemoryArtifactService()
     # Create a new session for the interaction.
-    session = await session_service.create_session(
+    session = session_service.create_session(
         state={}, app_name='hotel_agent', user_id='123'
     )
 
+    runner = Runner(
+        app_name='hotel_agent',
+        agent=root_agent,
+        artifact_service=artifacts_service,
+        session_service=session_service,
+    )
+
     # --- Define Queries and Run the Agent ---
     queries = [
         "Find hotels in Basel with Basel in it's name.",
@@ -686,10 +687,6 @@ async def main():
 
         for text in responses:
           print(text)
-
-import asyncio
-if __name__ == "__main__":
-    asyncio.run(main())
 {{< /tab >}}
 {{< /tabpane >}}
 

docs/en/samples/neo4j/_index.md

@@ -1,7 +0,0 @@
----
-title: "Neo4j"
-type: docs
-weight: 1
-description: >
-  How to get started with Toolbox using Neo4j.
----

docs/en/samples/neo4j/mcp_quickstart.md

@@ -1,141 +0,0 @@
----
-title: "Quickstart (MCP with Neo4j)"
-type: docs
-weight: 1
-description: >
-  How to get started running Toolbox with MCP Inspector and Neo4j as the source.
----
-
-## Overview
-
-[Model Context Protocol](https://modelcontextprotocol.io) is an open protocol that standardizes how applications provide context to LLMs. Check out this page on how to [connect to Toolbox via MCP](../../how-to/connect_via_mcp.md).
-
-
-## Step 1: Set up your Neo4j Database and Data
-
-In this section, you'll set up a database and populate it with sample data for a movies-related agent. This guide assumes you have a running Neo4j instance, either locally or in the cloud.
-
-. **Populate the database with data.**
-To make this quickstart straightforward, we'll use the built-in Movies dataset available in Neo4j.
-
-. In your Neo4j Browser, run the following command to create and populate the database:
-+
-```cypher
-:play movies
-````
-
-. Follow the instructions to load the data. This will create a graph with `Movie`, `Person`, and `Actor` nodes and their relationships.
-
-
-## Step 2: Install and configure Toolbox
-
-In this section, we will install the MCP Toolbox, configure our tools in a `tools.yaml` file, and then run the Toolbox server.
-
-. **Install the Toolbox binary.**
-The simplest way to get started is to download the latest binary for your operating system.
-
-. Download the latest version of Toolbox as a binary:
-\+
-
-```bash
-export OS="linux/amd64" # one of linux/amd64, darwin/arm64, darwin/amd64, or windows/amd64
-curl -O [https://storage.googleapis.com/genai-toolbox/v0.16.0/$OS/toolbox](https://storage.googleapis.com/genai-toolbox/v0.16.0/$OS/toolbox)
-```
-
-  + 
-. Make the binary executable:
-\+
-
-```bash
-chmod +x toolbox
-```
-
-. **Create the `tools.yaml` file.**
-This file defines your Neo4j source and the specific tools that will be exposed to your AI agent.
-\+
-{{\< notice tip \>}}
-Authentication for the Neo4j source uses standard username and password fields. For production use, it is highly recommended to use environment variables for sensitive information like passwords.
-{{\< /notice \>}}
-\+
-Write the following into a `tools.yaml` file:
-\+
-
-```yaml
-sources:
-  my-neo4j-source:
-    kind: neo4j
-    uri: bolt://localhost:7687
-    user: neo4j
-    password: my-password # Replace with your actual password
-
-tools:
-  search-movies-by-actor:
-    kind: neo4j-cypher
-    source: my-neo4j-source
-    description: "Searches for movies an actor has appeared in based on their name. Useful for questions like 'What movies has Tom Hanks been in?'"
-    parameters:
-      - name: actor_name
-        type: string
-        description: The full name of the actor to search for.
-    statement: |
-      MATCH (p:Person {name: $actor_name}) -[:ACTED_IN]-> (m:Movie)
-      RETURN m.title AS title, m.year AS year, m.genre AS genre
-  
-  get-actor-for-movie:
-    kind: neo4j-cypher
-    source: my-neo4j-source
-    description: "Finds the actors who starred in a specific movie. Useful for questions like 'Who acted in Inception?'"
-    parameters:
-      - name: movie_title
-        type: string
-        description: The exact title of the movie.
-    statement: |
-      MATCH (p:Person) -[:ACTED_IN]-> (m:Movie {title: $movie_title})
-      RETURN p.name AS actor
-```
-
-. **Start the Toolbox server.**
-Run the Toolbox server, pointing to the `tools.yaml` file you created earlier.
-\+
-
-```bash
-./toolbox --tools-file "tools.yaml"
-```
-
-## Step 3: Connect to MCP Inspector
-
-. **Run the MCP Inspector:**
-\+
-
-```bash
-npx @modelcontextprotocol/inspector
-```
-
-. Type `y` when it asks to install the inspector package.
-. It should show the following when the MCP Inspector is up and running (please take note of `<YOUR_SESSION_TOKEN>`):
-\+
-
-```bash
-Starting MCP inspector...
-⚙️ Proxy server listening on localhost:6277
-🔑 Session token: <YOUR_SESSION_TOKEN>
-    Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth
-
-🚀 MCP Inspector is up and running at:
-    http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<YOUR_SESSION_TOKEN>
-```
-
-1. Open the above link in your browser.
-
-1. For `Transport Type`, select `Streamable HTTP`.
-
-1. For `URL`, type in `http://127.0.0.1:5000/mcp`.
-
-1. For `Configuration` -\> `Proxy Session Token`, make sure `<YOUR_SESSION_TOKEN>` is present.
-
-1. Click `Connect`.
-
-1. Select `List Tools`, you will see a list of tools configured in `tools.yaml`.
-
-1. Test out your tools here\!
-

internal/server/config.go

@@ -16,6 +16,7 @@ package server
 import (
 	"context"
 	"fmt"
+	"regexp"
 	"strings"
 
 	yaml "github.com/goccy/go-yaml"
@@ -139,6 +140,10 @@ func (c *SourceConfigs) UnmarshalYAML(ctx context.Context, unmarshal func(interf
 	}
 
 	for name, u := range raw {
+		err := NameValidation(name)
+		if err != nil {
+			return err
+		}
 		// Unmarshal to a general type that ensure it capture all fields
 		var v map[string]any
 		if err := u.Unmarshal(&v); err != nil {
@@ -183,6 +188,10 @@ func (c *AuthServiceConfigs) UnmarshalYAML(ctx context.Context, unmarshal func(i
 	}
 
 	for name, u := range raw {
+		err := NameValidation(name)
+		if err != nil {
+			return err
+		}
 		var v map[string]any
 		if err := u.Unmarshal(&v); err != nil {
 			return fmt.Errorf("unable to unmarshal %q: %w", name, err)
@@ -226,6 +235,10 @@ func (c *EmbeddingModelConfigs) UnmarshalYAML(ctx context.Context, unmarshal fun
 	}
 
 	for name, u := range raw {
+		err := NameValidation(name)
+		if err != nil {
+			return err
+		}
 		// Unmarshal to a general type that ensure it capture all fields
 		var v map[string]any
 		if err := u.Unmarshal(&v); err != nil {
@@ -270,6 +283,10 @@ func (c *ToolConfigs) UnmarshalYAML(ctx context.Context, unmarshal func(interfac
 	}
 
 	for name, u := range raw {
+		err := NameValidation(name)
+		if err != nil {
+			return err
+		}
 		var v map[string]any
 		if err := u.Unmarshal(&v); err != nil {
 			return fmt.Errorf("unable to unmarshal %q: %w", name, err)
@@ -323,6 +340,10 @@ func (c *ToolsetConfigs) UnmarshalYAML(ctx context.Context, unmarshal func(inter
 	}
 
 	for name, toolList := range raw {
+		err := NameValidation(name)
+		if err != nil {
+			return err
+		}
 		(*c)[name] = tools.ToolsetConfig{Name: name, ToolNames: toolList}
 	}
 	return nil
@@ -342,6 +363,10 @@ func (c *PromptConfigs) UnmarshalYAML(ctx context.Context, unmarshal func(interf
 	}
 
 	for name, u := range raw {
+		err := NameValidation(name)
+		if err != nil {
+			return err
+		}
 		var v map[string]any
 		if err := u.Unmarshal(&v); err != nil {
 			return fmt.Errorf("unable to unmarshal prompt %q: %w", name, err)
@@ -389,7 +414,31 @@ func (c *PromptsetConfigs) UnmarshalYAML(ctx context.Context, unmarshal func(int
 	}
 
 	for name, promptList := range raw {
+		err := NameValidation(name)
+		if err != nil {
+			return err
+		}
 		(*c)[name] = prompts.PromptsetConfig{Name: name, PromptNames: promptList}
 	}
 	return nil
 }
+
+// Tools naming validation is added in the MCP v2025-11-25, but we'll be
+// implementing it across Toolbox
+// Tool names SHOULD be between 1 and 128 characters in length (inclusive).
+// Tool names SHOULD be considered case-sensitive.
+// The following SHOULD be the only allowed characters: uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.)
+// Tool names SHOULD NOT contain spaces, commas, or other special characters.
+// Tool names SHOULD be unique within a server.
+func NameValidation(name string) error {
+	strLen := len(name)
+	if strLen < 1 || strLen > 128 {
+		return fmt.Errorf("resource name SHOULD be between 1 and 128 characters in length (inclusive)")
+	}
+	validChars := regexp.MustCompile("^[a-zA-Z0-9_.-]+$")
+	isValid := validChars.MatchString(name)
+	if !isValid {
+		return fmt.Errorf("invalid character for resource name; only uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.) is allowed")
+	}
+	return nil
+}

internal/server/server_test.go

@@ -200,3 +200,62 @@ func TestUpdateServer(t *testing.T) {
 		t.Errorf("error updating server, promptset (-want +got):\n%s", diff)
 	}
 }
+
+func TestNameValidation(t *testing.T) {
+	testCases := []struct {
+		desc         string
+		resourceName string
+		errStr       string
+	}{
+		{
+			desc:         "names with 0 length",
+			resourceName: "",
+			errStr:       "resource name SHOULD be between 1 and 128 characters in length (inclusive)",
+		},
+		{
+			desc:         "names with allowed length",
+			resourceName: "foo",
+		},
+		{
+			desc:         "names with 128 length",
+			resourceName: strings.Repeat("a", 128),
+		},
+		{
+			desc:         "names with more than 128 length",
+			resourceName: strings.Repeat("a", 129),
+			errStr:       "resource name SHOULD be between 1 and 128 characters in length (inclusive)",
+		},
+		{
+			desc:         "names with space",
+			resourceName: "foo bar",
+			errStr:       "invalid character for resource name; only uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.) is allowed",
+		},
+		{
+			desc:         "names with commas",
+			resourceName: "foo,bar",
+			errStr:       "invalid character for resource name; only uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.) is allowed",
+		},
+		{
+			desc:         "names with other special character",
+			resourceName: "foo!",
+			errStr:       "invalid character for resource name; only uppercase and lowercase ASCII letters (A-Z, a-z), digits (0-9), underscore (_), hyphen (-), and dot (.) is allowed",
+		},
+		{
+			desc:         "names with allowed special character",
+			resourceName: "foo_.-bar6",
+		},
+	}
+	for _, tc := range testCases {
+		t.Run(tc.desc, func(t *testing.T) {
+			err := server.NameValidation(tc.resourceName)
+			if err != nil {
+				if tc.errStr != err.Error() {
+					t.Fatalf("unexpected error: %s", err)
+				}
+			}
+			if err == nil && tc.errStr != "" {
+				t.Fatalf("expect error: %s", tc.errStr)
+			}
+		})
+	}
+}