Documentation
¶
Overview ¶
Package extensions provides optional middleware and configuration for mcp-datahub.
Extensions add cross-cutting concerns like logging, metrics, error hints, and metadata enrichment to DataHub MCP tools. All extensions are opt-in and configured via environment variables or a config file.
Environment Variables ¶
Extensions can be enabled via environment variables:
- MCP_DATAHUB_EXT_LOGGING: Enable structured logging of tool calls ("true"/"1")
- MCP_DATAHUB_EXT_METRICS: Enable metrics collection ("true"/"1")
- MCP_DATAHUB_EXT_METADATA: Enable metadata enrichment on results ("true"/"1")
- MCP_DATAHUB_EXT_ERRORS: Enable error hint enrichment ("true"/"1", default: "true")
Config File ¶
For file-based configuration, use FromFile or LoadConfig to load YAML or JSON config files. See ServerConfig for the full schema.
Usage ¶
cfg := extensions.FromEnv() opts := extensions.BuildToolkitOptions(cfg) toolkit := tools.NewToolkit(client, toolsCfg, opts...)
Index ¶
- func BuildToolkitOptions(cfg Config) []tools.ToolkitOption
- type Config
- type DataHubConfig
- type Duration
- type ErrorHintMiddleware
- type ExtFileConfig
- type InMemoryCollector
- type LoggingMiddleware
- type MetadataMiddleware
- type MetricsCollector
- type MetricsMiddleware
- type ServerConfig
- type ToolMetrics
- type ToolkitConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BuildToolkitOptions ¶
func BuildToolkitOptions(cfg Config) []tools.ToolkitOption
BuildToolkitOptions converts extension config into toolkit options.
Types ¶
type Config ¶
type Config struct {
// EnableLogging enables structured logging of tool calls.
EnableLogging bool
// EnableMetrics enables metrics collection.
EnableMetrics bool
// EnableMetadata enables metadata enrichment on tool results.
EnableMetadata bool
// EnableErrorHelp enables error hint enrichment.
EnableErrorHelp bool
// LogOutput is the writer for logging output. Defaults to os.Stderr.
LogOutput io.Writer
}
Config controls which extensions are enabled.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with error hints enabled by default.
type DataHubConfig ¶
type DataHubConfig struct {
URL string `json:"url" yaml:"url"`
Token string `json:"token" yaml:"token"`
Timeout Duration `json:"timeout" yaml:"timeout"`
ConnectionName string `json:"connection_name" yaml:"connection_name"`
WriteEnabled *bool `json:"write_enabled" yaml:"write_enabled"`
}
DataHubConfig configures the DataHub connection.
type Duration ¶
Duration wraps time.Duration for JSON/YAML unmarshalling. Accepts Go duration strings like "30s", "5m", "1h".
func (Duration) MarshalJSON ¶
MarshalJSON implements json.Marshaler.
func (Duration) MarshalYAML ¶
MarshalYAML implements yaml.Marshaler.
func (*Duration) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler.
type ErrorHintMiddleware ¶
type ErrorHintMiddleware struct{}
ErrorHintMiddleware enriches error results with helpful hints.
func NewErrorHintMiddleware ¶
func NewErrorHintMiddleware() *ErrorHintMiddleware
NewErrorHintMiddleware creates an error hint middleware.
func (*ErrorHintMiddleware) After ¶
func (m *ErrorHintMiddleware) After( _ context.Context, _ *tools.ToolContext, result *mcp.CallToolResult, _ error, ) (*mcp.CallToolResult, error)
After appends helpful hints to error results.
func (*ErrorHintMiddleware) Before ¶
func (m *ErrorHintMiddleware) Before(ctx context.Context, _ *tools.ToolContext) (context.Context, error)
Before is a no-op for error hints.
type ExtFileConfig ¶
type ExtFileConfig struct {
Logging *bool `json:"logging" yaml:"logging"`
Metrics *bool `json:"metrics" yaml:"metrics"`
Metadata *bool `json:"metadata" yaml:"metadata"`
Errors *bool `json:"errors" yaml:"errors"`
}
ExtFileConfig configures extensions via file. Pointer bools allow distinguishing "not set" from "set to false".
type InMemoryCollector ¶
type InMemoryCollector struct {
// contains filtered or unexported fields
}
InMemoryCollector is a thread-safe in-memory metrics collector.
func NewInMemoryCollector ¶
func NewInMemoryCollector() *InMemoryCollector
NewInMemoryCollector creates a new in-memory metrics collector.
func (*InMemoryCollector) GetMetrics ¶
func (c *InMemoryCollector) GetMetrics(toolName string) *ToolMetrics
GetMetrics returns a snapshot of metrics for a tool. Returns nil if no metrics have been recorded for the tool.
func (*InMemoryCollector) RecordCall ¶
func (c *InMemoryCollector) RecordCall(toolName string, duration time.Duration, success bool)
RecordCall records a tool call metric.
func (*InMemoryCollector) Reset ¶
func (c *InMemoryCollector) Reset()
Reset clears all collected metrics.
type LoggingMiddleware ¶
type LoggingMiddleware struct {
// contains filtered or unexported fields
}
LoggingMiddleware logs tool invocations and results.
func NewLoggingMiddleware ¶
func NewLoggingMiddleware(output io.Writer) *LoggingMiddleware
NewLoggingMiddleware creates a logging middleware that writes to the given writer.
func (*LoggingMiddleware) After ¶
func (m *LoggingMiddleware) After( _ context.Context, tc *tools.ToolContext, result *mcp.CallToolResult, handlerErr error, ) (*mcp.CallToolResult, error)
After logs the tool result.
func (*LoggingMiddleware) Before ¶
func (m *LoggingMiddleware) Before(ctx context.Context, tc *tools.ToolContext) (context.Context, error)
Before logs the tool invocation.
type MetadataMiddleware ¶
type MetadataMiddleware struct{}
MetadataMiddleware appends execution metadata to tool results.
func NewMetadataMiddleware ¶
func NewMetadataMiddleware() *MetadataMiddleware
NewMetadataMiddleware creates a metadata enrichment middleware.
func (*MetadataMiddleware) After ¶
func (m *MetadataMiddleware) After( _ context.Context, tc *tools.ToolContext, result *mcp.CallToolResult, _ error, ) (*mcp.CallToolResult, error)
After appends execution metadata to successful results.
func (*MetadataMiddleware) Before ¶
func (m *MetadataMiddleware) Before(ctx context.Context, _ *tools.ToolContext) (context.Context, error)
Before is a no-op for metadata enrichment.
type MetricsCollector ¶
type MetricsCollector interface {
// RecordCall records a tool call with its duration and success status.
RecordCall(toolName string, duration time.Duration, success bool)
}
MetricsCollector defines the interface for collecting tool metrics.
type MetricsMiddleware ¶
type MetricsMiddleware struct {
// contains filtered or unexported fields
}
MetricsMiddleware collects metrics for tool calls.
func NewMetricsMiddleware ¶
func NewMetricsMiddleware(collector MetricsCollector) *MetricsMiddleware
NewMetricsMiddleware creates a metrics middleware with the given collector.
func (*MetricsMiddleware) After ¶
func (m *MetricsMiddleware) After( _ context.Context, tc *tools.ToolContext, result *mcp.CallToolResult, handlerErr error, ) (*mcp.CallToolResult, error)
After records the tool call metrics.
func (*MetricsMiddleware) Before ¶
func (m *MetricsMiddleware) Before(ctx context.Context, _ *tools.ToolContext) (context.Context, error)
Before is a no-op for metrics (timing starts from ToolContext.StartTime).
type ServerConfig ¶
type ServerConfig struct {
DataHub DataHubConfig `json:"datahub" yaml:"datahub"`
Toolkit ToolkitConfig `json:"toolkit" yaml:"toolkit"`
Extensions ExtFileConfig `json:"extensions" yaml:"extensions"`
}
ServerConfig is the top-level configuration loaded from a file.
func DefaultServerConfig ¶
func DefaultServerConfig() ServerConfig
DefaultServerConfig returns a ServerConfig with sensible defaults.
func FromBytes ¶
func FromBytes(data []byte, format string) (ServerConfig, error)
FromBytes parses a ServerConfig from raw bytes in the given format ("json" or "yaml").
func FromFile ¶
func FromFile(path string) (ServerConfig, error)
FromFile loads a ServerConfig from a YAML or JSON file. The format is determined by the file extension (.yaml, .yml, .json).
func LoadConfig ¶
func LoadConfig(path string) (ServerConfig, error)
LoadConfig loads a ServerConfig from a file and applies environment variable overrides. Environment variables take precedence over file values for sensitive fields.
func (*ServerConfig) ClientConfig ¶
func (sc *ServerConfig) ClientConfig() client.Config
ClientConfig converts the file config to a client.Config.
func (*ServerConfig) DescriptionsMap ¶
func (sc *ServerConfig) DescriptionsMap() map[tools.ToolName]string
DescriptionsMap converts string-keyed descriptions to tools.ToolName-keyed map.
func (*ServerConfig) ExtConfig ¶
func (sc *ServerConfig) ExtConfig() Config
ExtConfig converts the file config to an extensions.Config.
func (*ServerConfig) ToolsConfig ¶
func (sc *ServerConfig) ToolsConfig() tools.Config
ToolsConfig converts the file config to a tools.Config.
type ToolMetrics ¶
ToolMetrics holds aggregated metrics for a single tool.
type ToolkitConfig ¶
type ToolkitConfig struct {
DefaultLimit int `json:"default_limit" yaml:"default_limit"`
MaxLimit int `json:"max_limit" yaml:"max_limit"`
MaxLineageDepth int `json:"max_lineage_depth" yaml:"max_lineage_depth"`
Descriptions map[string]string `json:"descriptions" yaml:"descriptions"`
}
ToolkitConfig configures toolkit behavior.