Documentation
¶
Overview ¶
Package tools defines the MCP tools exposed by the server and their shared registration, validation, and error-handling helpers.
Index ¶
- Constants
- func ExternallyActingToolAnnotation() mcp.ToolAnnotation
- func IsPathSegment(value string) bool
- func MutatingToolAnnotation() mcp.ToolAnnotation
- func NewDateAwareHandler[TParams, TResult any](...) server.ToolHandlerFunc
- func ReadOnlyToolAnnotation() mcp.ToolAnnotation
- func WithInputSchema[T any]() mcp.ToolOption
- func WithInputSchemaConstraints[T any](constraints map[string]SchemaConstraint) mcp.ToolOption
- func WithNullFreeInputSchema() mcp.ToolOption
- func WithResultOutputSchema[T any]() mcp.ToolOption
- func WithUnionOutputSchema[T any]() mcp.ToolOption
- func WithValidation[TParams, TResult any](tool Tool[TParams, TResult]) server.ToolHandlerFunc
- type BaseTool
- type Registry
- type SchemaConstraint
- type Tool
- type ToolError
- func (e *ToolError) API(resp *http.Response) *ToolError
- func (e *ToolError) Cause(err error) *ToolError
- func (e *ToolError) Error() string
- func (e *ToolError) Hint(hint string) *ToolError
- func (e *ToolError) Hintf(format string, args ...any) *ToolError
- func (e *ToolError) Schema(entityType, operation string) *ToolError
- func (e *ToolError) ToMap() map[string]any
- func (e *ToolError) Unwrap() error
- type UntrustedDataReporter
Constants ¶
const ( ToolNameManageEntities = "manage-entities" ToolNameExecuteAutomation = "execute-automation" ToolNameGetResource = "get-resource" ToolNameSearchEntities = "search-entities" )
Tool name constants identify the MCP tools exposed by the server.
Variables ¶
This section is empty.
Functions ¶
func ExternallyActingToolAnnotation ¶ added in v1.1.0
func ExternallyActingToolAnnotation() mcp.ToolAnnotation
ExternallyActingToolAnnotation describes a tool whose effects escape TheHive.
This is the only openWorldHint:true tool. The others reach exactly one known, configured system, which is a closed domain however remote it is; Cortex analyzers and responders reach an open-ended set of third-party services — submitting an observable to a sandbox, or having a responder block an address — that the server cannot enumerate and cannot undo.
func IsPathSegment ¶ added in v1.2.0
IsPathSegment reports whether value can be one URL path segment: not empty, not a dot segment, and free of slashes, backslashes and control characters.
func MutatingToolAnnotation ¶ added in v1.1.0
func MutatingToolAnnotation() mcp.ToolAnnotation
MutatingToolAnnotation describes a tool that changes state inside TheHive and nowhere else.
destructive because the set of operations includes irreversible ones (delete, merge) — the hint covers what the tool can do, not what a particular call does. Not idempotent: a repeated create makes a second entity.
func NewDateAwareHandler ¶ added in v0.3.1
func NewDateAwareHandler[TParams, TResult any](handler func(ctx context.Context, req mcp.CallToolRequest, args TParams) (TResult, error), wrapUntrusted bool) server.ToolHandlerFunc
NewDateAwareHandler date-processes the result; when wrapUntrusted is true, user-generated fields are wrapped in boundary tags.
func ReadOnlyToolAnnotation ¶ added in v1.1.0
func ReadOnlyToolAnnotation() mcp.ToolAnnotation
ReadOnlyToolAnnotation describes a tool that only ever reads.
destructiveHint and idempotentHint are meaningless while readOnlyHint is true, but mcp-go emits all four keys regardless, so they are set to the values that are trivially true of a read rather than left at the pessimistic default.
func WithInputSchema ¶ added in v1.2.0
func WithInputSchema[T any]() mcp.ToolOption
WithInputSchema infers the input schema from T, as mcp.WithInputSchema does, with every null dropped from its type unions. Tools use it in place of a bare mcp.WithInputSchema, whose ["null", T] unions TestToolSchemas_InputTypesAdmitNoNull rejects.
func WithInputSchemaConstraints ¶ added in v1.1.0
func WithInputSchemaConstraints[T any](constraints map[string]SchemaConstraint) mcp.ToolOption
WithInputSchemaConstraints infers the input schema from T and then applies constraints to named properties.
The struct stays the single source of truth for property names, types, descriptions and requiredness; this only adds what inference cannot see, and drops the null inference puts in a slice or pointer's type (see dropNullFromTypes). A constraint naming a property that does not exist is a bug — it is logged, and TestToolSchemas_ConstraintsMatchTheStruct fails on it.
It exists because mcp.WithInputSchema is silent on failure: it writes the inference error to stderr and returns without setting a schema, so a broken tag yields a tool advertising no parameters at all and nothing else reports it. See TestToolSchemas_AdvertiseTheirParameters.
func WithNullFreeInputSchema ¶ added in v1.2.0
func WithNullFreeInputSchema() mcp.ToolOption
WithNullFreeInputSchema drops null from the type unions of the input schema the options before it built, raw or structured. It is for a tool whose schema comes neither from WithInputSchema nor from WithInputSchemaConstraints, which both drop it already, and goes after the option that sets the schema.
func WithResultOutputSchema ¶ added in v1.1.0
func WithResultOutputSchema[T any]() mcp.ToolOption
WithResultOutputSchema advertises the output schema of a result type that serializes as itself. It exists so that even a non-union result gets the date-field retyping every tool's payload undergoes; see retypeDateFields.
func WithUnionOutputSchema ¶ added in v1.1.0
func WithUnionOutputSchema[T any]() mcp.ToolOption
WithUnionOutputSchema advertises the output schema of a union result type whose Unwrap() flattens it via utils.UnwrapUnion.
A union result serializes as its single active variant, hoisted to the top level — never as the wrapper struct. mcp.WithOutputSchema[T]() therefore advertises a shape the handler never sends: it permits only the wrapper's own field names and, since mcp-go v1.0.0, closes the object with additionalProperties:false. Every successful result then violates the tool's own declared contract, because each of its keys belongs to the variant rather than to the wrapper. Under mcp-go v0.43.1 this passed unnoticed — it set AllowAdditionalProperties:true, so the hoisted keys were tolerated.
So describe what Unwrap() actually produces: anyOf over the variant schemas. anyOf rather than oneOf because oneOf demands exactly one match and would reject a payload satisfying two variants whose field sets overlap.
Branches are lifted from the schema mcp-go itself generates for the wrapper, rather than reflected here, so each variant keeps mcp-go's own inference — including its fallback for the `jsonschema:"enum=..."` tag syntax that github.com/google/jsonschema-go rejects outright.
func WithValidation ¶ added in v0.3.1
func WithValidation[TParams, TResult any](tool Tool[TParams, TResult]) server.ToolHandlerFunc
WithValidation runs ValidateParams then ValidatePermissions before Handle, then date-processes the result.
Types ¶
type BaseTool ¶ added in v0.3.1
type BaseTool interface {
Name() string
Definition() mcp.Tool
Handler() server.ToolHandlerFunc
}
BaseTool is the non-generic interface for tool registration
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages tool registration
func (*Registry) RegisterAll ¶
RegisterAll registers every tool in the registry with the given MCP server.
type SchemaConstraint ¶ added in v1.1.0
type SchemaConstraint struct {
// Enum is the closed set of permitted values.
Enum []string
// Default is the value the server applies when the caller omits the field.
Default any
}
SchemaConstraint carries the parts of a JSON Schema property that Go struct tags can no longer express.
mcp-go v1.0.0 infers schemas with github.com/google/jsonschema-go, where the `jsonschema` tag is a plain description string rather than a `key=value` DSL — a tag shaped like `enum=a,enum=b` is rejected outright. Descriptions still come from `jsonschema_description`, so only enumerations and defaults need somewhere else to live.
type Tool ¶
type Tool[TParams, TResult any] interface { BaseTool Handle(ctx context.Context, request mcp.CallToolRequest, params TParams) (TResult, error) ValidateParams(params *TParams) error ValidatePermissions(ctx context.Context, params TParams) error }
Tool represents an MCP tool with typed parameters
type ToolError ¶ added in v0.3.1
type ToolError struct {
// contains filtered or unexported fields
}
ToolError represents a tool error with optional context.
func NewToolError ¶ added in v0.3.1
NewToolError creates a new tool error.
func NewToolErrorf ¶ added in v0.3.1
NewToolErrorf creates a new tool error with formatting.
func ValidatePathIDs ¶ added in v1.2.0
ValidatePathIDs rejects an ID that could leave the URL path segment it is interpolated into. The generated client percent-encodes every path value, so "/" cannot split a segment on its own, but a proxy that decodes %2F before routing would split it, a dot segment ("." or "..") is not encoded at all, some servers treat "\" as "/", and an empty ID turns an entity's path into its collection's. The class RandoriSec 5.3 found open to traversal.
It is the floor for IDs that may also be names (a case template, a page): an ID known to be TheHive's "~" + digits is held to that pattern instead.
func (*ToolError) API ¶ added in v0.3.1
API attaches resp's body to the error; consumes and closes it. A cause that is the client's failure to decode that body reads as TheHive's status line instead (utils.StatusCause): the body itself is right here.
func (*ToolError) ToMap ¶ added in v0.3.1
ToMap returns the error as a structured map for JSON serialization. These maps are embedded in successful bulk results and pass through the [UNTRUSTED_DATA] wrapping middleware: message and hints are MCP-authored recovery guidance (static text plus agent-supplied inputs) and stay unwrapped, while cause and apiResponse carry upstream content and must stay plain so they are wrapped (DL-6703).
type UntrustedDataReporter ¶ added in v1.0.0
type UntrustedDataReporter interface {
HasUntrustedData() bool
}
UntrustedDataReporter is an optional interface implemented by tools whose responses carry user-generated data from external systems (e.g. TheHive). When implemented and returning true, the middleware wraps designated fields in [UNTRUSTED_DATA] boundary tags so LLM clients can distinguish data from instructions.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package execute_automation implements the execute-automation MCP tool for running Cortex analyzers and responders and reading their execution status.
|
Package execute_automation implements the execute-automation MCP tool for running Cortex analyzers and responders and reading their execution status. |
|
Package manage implements the manage-entities MCP tool, exposing CRUD and workflow operations (create, update, delete, comment, promote, merge, apply-template) over TheHive entities.
|
Package manage implements the manage-entities MCP tool, exposing CRUD and workflow operations (create, update, delete, comment, promote, merge, apply-template) over TheHive entities. |
|
Package resource implements the get-resource MCP tool that exposes TheHive's hierarchical resources (schemas, metadata, docs, config) to clients.
|
Package resource implements the get-resource MCP tool that exposes TheHive's hierarchical resources (schemas, metadata, docs, config) to clients. |
|
Package search implements the MCP search tool that queries TheHive entities using the TheHive filter DSL.
|
Package search implements the MCP search tool that queries TheHive entities using the TheHive filter DSL. |