core

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 31, 2026 License: Apache-2.0 Imports: 17 Imported by: 2

README

MCP Toolbox Logo

MCP Toolbox Core SDK

[!IMPORTANT] Breaking Change Notice: As of version 0.6.0, this repository has transitioned to a multi-module structure.

  • For new versions (v0.6.0+): You must import specific modules (e.g., go get github.com/googleapis/mcp-toolbox-sdk-go/core).
  • For older versions (v0.5.1 and below): The repository remains a single-module library (go get github.com/googleapis/mcp-toolbox-sdk-go).
  • Please update your imports and go.mod accordingly when upgrading.

This SDK allows you to seamlessly integrate the functionalities of Toolbox allowing you to load and use tools defined in the service as standard Go structs within your GenAI applications.

For comprehensive guides, authentication examples, and advanced configuration, visit the Go SDK Core Documentation.

Installation

go get github.com/googleapis/mcp-toolbox-sdk-go/core

This SDK is supported on Go version 1.24.4 and higher.

[!NOTE]

  • While the SDK itself is synchronous, you can execute its functions within goroutines to achieve asynchronous behavior.

Quickstart

Here's a minimal example to get you started. Ensure your Toolbox service is running and accessible.

package main

import (
	"context"
	"fmt"
	"github.com/googleapis/mcp-toolbox-sdk-go/core"
)

func quickstart() string {
	ctx := context.Background()
	inputs := map[string]any{"location": "London"}
	client, err := core.NewToolboxClient("http://localhost:5000")
	if err != nil {
		return fmt.Sprintln("Could not start Toolbox Client", err)
	}
	tool, err := client.LoadTool("get_weather", ctx)
	if err != nil {
		return fmt.Sprintln("Could not load Toolbox Tool", err)
	}
	result, err := tool.Invoke(ctx, inputs)
	if err != nil {
		return fmt.Sprintln("Could not invoke tool", err)
	}
	return fmt.Sprintln(result)
}

func main() {
	fmt.Println(quickstart())
}

Usage

The core package provides a framework-agnostic way to interact with your MCP Toolbox server. For detailed guides and advanced configuration, please visit the following sections on our Documentation Site:

Contributing

Contributions are welcome! Please refer to the DEVELOPER.md file for guidelines on how to set up a development environment and run tests.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Support

If you encounter issues or have questions, check the existing GitHub Issues for the main Toolbox project.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetGoogleIDToken 

func GetGoogleIDToken(ctx context.Context, audience string) (string, error)

GetGoogleIDToken fetches a Google ID token for a specific audience.

Inputs:

  • ctx: The context for the request, which can be used for cancellation or deadlines.
  • audience: The recipient of the token, typically the URL of the secured service

Returns: 

A string in the format "Bearer <token>" on success, or an error if
the token could not be fetched.

func GetSupportedMcpVersions 

func GetSupportedMcpVersions() []string

GetSupportedMcpVersions returns a list of supported MCP protocol versions.

func NewCustomTokenSource 

func NewCustomTokenSource(provider func() string) oauth2.TokenSource

This function converts a custom function that returns a string into an oauth2.TokenSource type.

Inputs:

  • provider: A custom function that returns a token as a string.

Returns:

  • An oauth2.TokenSource that wraps the custom function.

Types

type ClientOption 

type ClientOption func(*ToolboxClient) error

ClientOption configures a ToolboxClient at creation time.

func WithClientHeaderString 

func WithClientHeaderString(headerName string, value string) ClientOption

WithClientHeaderString adds a static string value as a client-wide HTTP header.

func WithClientHeaderTokenSource 

func WithClientHeaderTokenSource(headerName string, value oauth2.TokenSource) ClientOption

WithClientHeaderTokenSource adds a dynamic client-wide HTTP header from a TokenSource.

func WithClientName 

func WithClientName(name string) ClientOption

WithClientName sets the client name used in the MCP protocol handshake. Defaults to "toolbox-core-go" if not set.

func WithClientVersion added in v0.7.0 

func WithClientVersion(version string) ClientOption

WithClientVersion sets the client version used in the MCP protocol handshake. Defaults to the core SDK version if not set.

func WithDefaultToolOptions 

func WithDefaultToolOptions(opts ...ToolOption) ClientOption

WithDefaultToolOptions provides default Options that will be applied to every tool loaded by this client.

func WithHTTPClient 

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient provides a custom http.Client to the ToolboxClient.

func WithProtocol 

func WithProtocol(p Protocol) ClientOption

WithProtocol provides a the underlying transport protocol to the ToolboxClient..

type Float 

type Float interface {
	~float32 | ~float64
}

type Integer 

type Integer interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}

type ManifestSchema 

type ManifestSchema = transport.ManifestSchema

type ParameterSchema 

type ParameterSchema = transport.ParameterSchema

ParameterSchema defines the structure and validation logic for tool parameters.

type Protocol 

type Protocol string

Protocol defines underlying transport protocols. 

const (
	// MCP Version Constants
	MCPv20251125 Protocol = "2025-11-25"
	MCPv20250618 Protocol = "2025-06-18"
	MCPv20250326 Protocol = "2025-03-26"
	MCPv20241105 Protocol = "2024-11-05"

	// MCP is the default alias pointing to the newest supported version.
	MCP = MCPv20250618
)

type ToolConfig 

type ToolConfig struct {
	AuthTokenSources map[string]oauth2.TokenSource
	BoundParams      map[string]any
	Strict           bool
	// contains filtered or unexported fields
}

ToolConfig holds all configurable aspects for creating or deriving a tool.

type ToolOption 

type ToolOption func(*ToolConfig) error

ToolOption defines a single, universal type for a functional option that configures a tool.

func WithAuthTokenSource 

func WithAuthTokenSource(authSourceName string, idToken oauth2.TokenSource) ToolOption

WithAuthTokenSource provides an authentication token from a standard TokenSource.

func WithAuthTokenString 

func WithAuthTokenString(authSourceName string, idToken string) ToolOption

WithAuthTokenString provides a static string authentication token.

func WithBindParamAnyMap added in v0.7.0 

func WithBindParamAnyMap(name string, value map[string]any) ToolOption

WithBindParamAnyMap binds a generic map to a parameter.

func WithBindParamAnyMapFunc added in v0.7.0 

func WithBindParamAnyMapFunc(name string, fn func() (map[string]any, error)) ToolOption

WithBindParamAnyMapFunc binds a function that returns a generic map to a parameter.

func WithBindParamBool 

func WithBindParamBool(name string, value bool) ToolOption

WithBindParamBool binds a static boolean value to a parameter.

func WithBindParamBoolArray 

func WithBindParamBoolArray(name string, value []bool) ToolOption

WithBindParamBoolArray binds a static slice of booleans to a parameter.

func WithBindParamBoolArrayFunc 

func WithBindParamBoolArrayFunc(name string, fn func() ([]bool, error)) ToolOption

WithBindParamBoolArrayFunc binds a function that returns a slice of booleans.

func WithBindParamBoolFunc 

func WithBindParamBoolFunc(name string, fn func() (bool, error)) ToolOption

WithBindParamBoolFunc binds a function that returns a boolean to a parameter.

func WithBindParamBoolMap added in v0.7.0 

func WithBindParamBoolMap(name string, value map[string]bool) ToolOption

WithBindParamBoolMap binds a static map of booleans to a parameter.

func WithBindParamBoolMapFunc added in v0.7.0 

func WithBindParamBoolMapFunc(name string, fn func() (map[string]bool, error)) ToolOption

WithBindParamBoolMapFunc binds a function that returns a map of booleans to a parameter.

func WithBindParamFloat 

func WithBindParamFloat[T Float](name string, value T) ToolOption

WithBindParamFloat binds a static float value to a parameter.

func WithBindParamFloatArray 

func WithBindParamFloatArray[T Float](name string, value []T) ToolOption

WithBindParamFloatArray binds a static slice of floats to a parameter.

func WithBindParamFloatArrayFunc 

func WithBindParamFloatArrayFunc[T Float](name string, fn func() ([]T, error)) ToolOption

WithBindParamFloatArrayFunc binds a function that returns a slice of floats.

func WithBindParamFloatFunc 

func WithBindParamFloatFunc[T Float](name string, fn func() (T, error)) ToolOption

WithBindParamFloatFunc binds a function that returns a float to a parameter.

func WithBindParamFloatMap added in v0.7.0 

func WithBindParamFloatMap[T Float](name string, value map[string]T) ToolOption

WithBindParamFloatMap binds a static map of floats to a parameter.

func WithBindParamFloatMapFunc added in v0.7.0 

func WithBindParamFloatMapFunc[T Float](name string, fn func() (map[string]T, error)) ToolOption

WithBindParamFloatMapFunc binds a function that returns a map of floats to a parameter.

func WithBindParamInt 

func WithBindParamInt[T Integer](name string, value T) ToolOption

WithBindParamInt binds a static integer value to a parameter.

func WithBindParamIntArray 

func WithBindParamIntArray[T Integer](name string, value []T) ToolOption

WithBindParamIntArray binds a static slice of integers to a parameter.

func WithBindParamIntArrayFunc 

func WithBindParamIntArrayFunc[T Integer](name string, fn func() ([]T, error)) ToolOption

WithBindParamIntArrayFunc binds a function that returns a slice of integers.

func WithBindParamIntFunc 

func WithBindParamIntFunc[T Integer](name string, fn func() (T, error)) ToolOption

WithBindParamIntFunc binds a function that returns an integer to a parameter.

func WithBindParamIntMap added in v0.7.0 

func WithBindParamIntMap[T Integer](name string, value map[string]T) ToolOption

WithBindParamIntMap binds a static map of integers to a parameter.

func WithBindParamIntMapFunc added in v0.7.0 

func WithBindParamIntMapFunc[T Integer](name string, fn func() (map[string]T, error)) ToolOption

WithBindParamIntMapFunc binds a function that returns a map of integers to a parameter.

func WithBindParamString 

func WithBindParamString(name string, value string) ToolOption

WithBindParamString binds a static string value to a parameter.

func WithBindParamStringArray 

func WithBindParamStringArray(name string, value []string) ToolOption

WithBindParamStringArray binds a static slice of strings to a parameter.

func WithBindParamStringArrayFunc 

func WithBindParamStringArrayFunc(name string, fn func() ([]string, error)) ToolOption

WithBindParamStringArrayFunc binds a function that returns a slice of strings.

func WithBindParamStringFunc 

func WithBindParamStringFunc(name string, fn func() (string, error)) ToolOption

WithBindParamStringFunc binds a function that returns a string to a parameter.

func WithBindParamStringMap added in v0.7.0 

func WithBindParamStringMap(name string, value map[string]string) ToolOption

WithBindParamStringMap binds a static map of strings to a parameter.

func WithBindParamStringMapFunc added in v0.7.0 

func WithBindParamStringMapFunc(name string, fn func() (map[string]string, error)) ToolOption

WithBindParamStringMapFunc binds a function that returns a map of strings to a parameter.

func WithStrict 

func WithStrict(strict bool) ToolOption

WithStrict provides an option to enable strict validation for LoadToolset.

type ToolSchema 

type ToolSchema = transport.ToolSchema

ToolSchema defines a single tool in the manifest.

type ToolboxClient 

type ToolboxClient struct {
	// contains filtered or unexported fields
}

The synchronous interface for a Toolbox service client.

func NewToolboxClient 

func NewToolboxClient(url string, opts ...ClientOption) (*ToolboxClient, error)

NewToolboxClient creates and configures a new, immutable client for interacting with a Toolbox server.

Inputs:

  • url: The base URL of the Toolbox server.
  • opts: A variadic list of ClientOption functions to configure the client, such as setting a custom http.Client, default headers, or the underlying protocol.

Returns: 

A configured *ToolboxClient and a nil error on success, or a nil client
and an error if configuration fails.

func (*ToolboxClient) LoadTool 

func (tc *ToolboxClient) LoadTool(name string, ctx context.Context, opts ...ToolOption) (*ToolboxTool, error)

LoadTool fetches a manifest for a single tool

Inputs:

  • name: The specific name of the tool to load.
  • ctx: The context to control the lifecycle of the request.
  • opts: A variadic list of ToolOption functions to configure auth tokens or bind parameters for this tool.

Returns: 

A configured *ToolboxTool and a nil error on success, or a nil tool and
an error if loading or validation fails.

func (*ToolboxClient) LoadToolset 

func (tc *ToolboxClient) LoadToolset(name string, ctx context.Context, opts ...ToolOption) ([]*ToolboxTool, error)

LoadToolset fetches a manifest for a collection of tools.

Inputs:

  • name: Name of the toolset to be loaded.Set this arg to "" to load the default toolset
  • ctx: The context to control the lifecycle of the request.
  • opts: A variadic list of ToolOption functions. These can include WithStrict and options for auth or bound params that may apply to tools in the set.

Returns: 

A slice of configured *ToolboxTool and a nil error on success, or a nil
slice and an error if loading or validation fails.

type ToolboxTool 

type ToolboxTool struct {
	// contains filtered or unexported fields
}

ToolboxTool represents an immutable, universal definition of a Toolbox tool.

func (*ToolboxTool) DescribeParameters 

func (tt *ToolboxTool) DescribeParameters() string

DescribeParameters returns a single, human-readable string that describes all of the tool's unbound parameters, including their names, types, and descriptions.

Returns: 

A formatted string of parameter descriptions, or an empty string if there
are no unbound parameters.

func (*ToolboxTool) Description 

func (tt *ToolboxTool) Description() string

Description returns the tool's description.

func (*ToolboxTool) InputSchema 

func (tt *ToolboxTool) InputSchema() ([]byte, error)

InputSchema generates an OpenAPI JSON Schema for the tool's input parameters and returns it as raw bytes.

func (*ToolboxTool) Invoke 

func (tt *ToolboxTool) Invoke(ctx context.Context, input map[string]any) (any, error)

Invoke executes the tool with the given input.

Inputs:

  • ctx: The context to control the lifecycle of the API request.
  • input: A map of parameter names to values provided by the user for this specific invocation.

Returns: 

The result from the API call, which can be a structured object (from a JSON
'result' field) or a raw string. Returns an error if any step of the
process fails.

func (*ToolboxTool) Name 

func (tt *ToolboxTool) Name() string

Name returns the tool's name.

func (*ToolboxTool) Parameters 

func (tt *ToolboxTool) Parameters() []ParameterSchema

Parameters returns the list of parameters that must be provided by a user at invocation time.

func (*ToolboxTool) ToolFrom 

func (tt *ToolboxTool) ToolFrom(opts ...ToolOption) (*ToolboxTool, error)

ToolFrom creates a new, more specialized tool from an existing one by applying additional options. This is useful for creating variations of a tool with different bound parameters without modifying the original and all provided options must be applicable.

Inputs:

  • opts: A variadic list of ToolOption functions to further configure the new tool, such as binding more parameters.

Returns: 

A new, specialized *ToolboxTool and a nil error, or a nil tool and an
error if the new options are invalid or conflict with existing settings.

Source Files

View all Source files

Directories

Path Synopsis
mcp
mcp/v20241105
mcp/v20250326
mcp/v20250618
mcp/v20251125

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.