toolhive-core

module

v0.0.6 Latest Latest Go to latest Published: Feb 20, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/stacklok/toolhive-core

Links

Open Source Insights

README ¶

toolhive-core

The ToolHive Platform common libraries and specifications.

toolhive-core provides stable, well-tested Go utilities with explicit API guarantees for the ToolHive ecosystem. Projects like toolhive, dockyard, toolhive-registry, and toolhive-registry-server depend on this library for shared functionality.

Why toolhive-core?

The ToolHive ecosystem spans multiple Go repositories, and several of these projects need to share common utilities. Rather than having projects import internal packages from toolhive (which have no stability guarantees), toolhive-core provides:

Stability guarantees: Packages follow semantic versioning with explicit API commitments
Clear maturity levels: Each package is marked as Stable, Beta, or Alpha
Tested and documented: All packages meet minimum quality standards before inclusion
Independent versioning: Evolves on its own release cadence, decoupled from toolhive releases

Available Packages

Package	Stability	Description
`cel`	Alpha	Generic CEL expression compilation and evaluation
`env`	Stable	Environment variable abstraction with `Reader` interface
`httperr`	Stable	Wrap errors with HTTP status codes
`logging`	Alpha	Pre-configured `*slog.Logger` factory with consistent ToolHive defaults
`oci/skills`	Alpha	OCI artifact types, media types, and registry operations for skills
`recovery`	Beta	HTTP panic recovery middleware
`validation/http`	Stable	RFC 7230/8707 compliant HTTP header and URI validation
`validation/group`	Stable	Group name validation

Package Stability Levels

Each package is marked with a stability level:

Level	Meaning	API Guarantees
Stable	Production-ready, fully supported	No breaking changes without major version bump
Beta	Feature-complete, may have minor changes	Breaking changes possible with deprecation notice
Alpha	Experimental, subject to significant changes	No stability guarantees

Graduation Criteria

Packages in toolhive-core must meet formal criteria before inclusion. This ensures that shared packages are genuinely reusable, well-tested, and not tied to the internal workings of any specific project.

Guiding Principle

Packages must provide genuinely reusable value and be designed as reusable from the start. A package that requires knowledge of toolhive internals to use correctly is not a good candidate for graduation.

Fast Track (Simple Packages)

For small, focused packages with minimal dependencies (e.g., env, errors, validation):

Criterion	Requirement
Production usage	Deployed in production for ≥1 month
No internal dependencies	Cannot depend on non-graduated internal packages
No global state	No singletons, global variables for state, or `init()` side effects
Test coverage	≥70% line coverage
Documentation	Package-level godoc
Approval	GitHub issue approved by one maintainer

Standard Track (Complex Packages)

For packages with external dependencies, multiple types, or broader API surface:

Criterion	Requirement
Production usage	Deployed in production for ≥2 months without breaking changes
API stability	No breaking changes in the last 2 minor releases
Interface design	Uses Go interfaces for dependency injection and testability
Error handling	Returns typed errors; no panics except for programming bugs
No global state	No singletons, global variables for state, or `init()` side effects
Test coverage	≥70% line coverage with meaningful assertions
Documentation	Package-level godoc with usage examples
Linting	Passes `golangci-lint` with project configuration
Minimal dependencies	Only essential external dependencies
No circular imports	Must not create import cycles when extracted
No internal dependencies	Cannot depend on non-graduated internal packages
Stable external deps	External dependencies must be v1.0+ or widely adopted
Sponsorship	At least one maintainer sponsors the graduation
Approval	RFC or detailed GitHub issue reviewed and approved

Graduation Process

Proposal: Open a GitHub issue identifying the graduation candidate and proposed track (fast/standard)
Track determination: Maintainers confirm which track applies based on package complexity
Evaluation: Assess against the relevant track's criteria
Approval: Fast track requires one maintainer approval; standard track requires RFC or detailed issue review
Extraction: Move package to toolhive-core with necessary adaptations
Release: Tag a new semver release of toolhive-core
Migration: Update consuming projects to import from toolhive-core

Versioning

toolhive-core follows Semantic Versioning 2.0.0:

Major (vX.0.0): Breaking API changes
Minor (v0.X.0): New features, backward-compatible
Patch (v0.0.X): Bug fixes, backward-compatible

License

Apache-2.0 - See LICENSE for details.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cel Package cel provides a generic CEL expression engine for compiling and evaluating expressions against arbitrary data contexts.	Package cel provides a generic CEL expression engine for compiling and evaluating expressions against arbitrary data contexts.
env Package env provides an interface-based abstraction for environment variable access, enabling dependency injection and testing isolation.	Package env provides an interface-based abstraction for environment variable access, enabling dependency injection and testing isolation.
mocks Package mocks is a generated GoMock package.	Package mocks is a generated GoMock package.
httperr Package httperr provides error types with HTTP status codes for API error handling.	Package httperr provides error types with HTTP status codes for API error handling.
logging Package logging provides a pre-configured log/slog.Logger factory with consistent defaults for the ToolHive ecosystem.	Package logging provides a pre-configured log/slog.Logger factory with consistent defaults for the ToolHive ecosystem.
oci
skills Package skills provides OCI artifact types, media types, local storage, and remote registry operations for ToolHive skill packages.	Package skills provides OCI artifact types, media types, local storage, and remote registry operations for ToolHive skill packages.
skills/mocks Package mocks is a generated GoMock package.	Package mocks is a generated GoMock package.
permissions Package permissions provides types and utilities for managing container permissions and permission profiles in the ToolHive ecosystem.	Package permissions provides types and utilities for managing container permissions and permission profiles in the ToolHive ecosystem.
recovery Package recovery provides panic recovery middleware for HTTP handlers.	Package recovery provides panic recovery middleware for HTTP handlers.
registry
converters Package converters provides bidirectional conversion between toolhive registry formats and the upstream MCP (Model Context Protocol) ServerJSON format.	Package converters provides bidirectional conversion between toolhive registry formats and the upstream MCP (Model Context Protocol) ServerJSON format.
types Package registry contains the core type definitions for the MCP registry system.	Package registry contains the core type definitions for the MCP registry system.
validation
group Package group provides validation functions for group names.	Package group provides validation functions for group names.
http Package http provides security-focused validation functions for HTTP headers and URIs.	Package http provides security-focused validation functions for HTTP headers and URIs.