toolfoundation

README

toolfoundation

Foundation layer for the ApertureStack AI tool ecosystem.

Installation

go get github.com/jonwraymond/toolfoundation

Packages

Package	Description
model	Canonical MCP tool schema definitions and validation
adapter	Protocol-agnostic tool format conversion (MCP, OpenAI, Anthropic)
version	Semantic versioning, constraints, compatibility matrices

Quick Start

Define a Tool

import (
    "github.com/jonwraymond/toolfoundation/model"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

tool := model.Tool{
    Namespace: "github",
    Tool: mcp.Tool{
        Name:        "list_repos",
        Description: "List repositories for a user",
        InputSchema: map[string]any{
            "type": "object",
            "properties": map[string]any{
                "username": map[string]any{"type": "string"},
            },
            "required": []string{"username"},
        },
    },
    Version: "1.0.0",
}

if err := tool.Validate(); err != nil {
    log.Fatal(err)
}

Convert Between Formats

import "github.com/jonwraymond/toolfoundation/adapter"

registry := adapter.DefaultRegistry()

// Convert MCP tool to OpenAI format
result, err := registry.Convert(tool, "mcp", "openai")
if err != nil {
    log.Fatal(err)
}

// Check for feature loss warnings
for _, w := range result.Warnings {
    log.Printf("Warning: %s", w)
}

openaiTool := result.Tool.(*adapter.OpenAITool)

Version Constraints

import "github.com/jonwraymond/toolfoundation/version"

v := version.MustParse("1.5.0")
constraint, _ := version.ParseConstraint("^1.0.0")

if constraint.Check(v) {
    fmt.Println("Version is compatible")
}

Documentation

• API Reference (pkg.go.dev)
• Tool Schemas
• Design Notes
• User Journey
• Contributing

Features

• MCP-aligned: Tool type embeds official MCP SDK types
• Protocol-agnostic: Convert between MCP, OpenAI, and Anthropic formats
• Feature loss visibility: Warnings when target format lacks source features
• JSON Schema validation: Built-in schema validation (2020-12 and draft-07)
• Minimal dependencies: Foundation layer with minimal external dependencies

License

MIT License - see LICENSE