apisurface

package
v0.48.3 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package apisurface generates the kombify API surface from one OpenAPI 3.1 contract. A product annotates its spec with x-kombify-* extensions; Generate validates the contract and builds a language-neutral Surface that marshals to api-surface.json and projects the product-native MCP tool-manifest.json, the Gateway MCP catalog fragment and the public OpenAPI document. Package apisurface/cli mounts the same Surface as cobra commands and package apisurface/mcpbind registers its tools on an MCP go-sdk server, so API, CLI and MCP stay one contract.

Root extension (required): 

x-kombify-surface:
  product: techstack
  capability: techstack.inventory.read
  envelope: data
  cli: { command: techstack }
  mcp: { transport: streamable-http, endpoint: /api/v1/mcp, protocolVersion: "2026-07-28" }

x-kombify-surface.mcp may add defaults (tools derived for operations without an MCP decision) and catalog (the Gateway catalog fragment).

Operation extensions: x-kombify-mcp, x-kombify-cli, x-kombify-confirmation, x-kombify-availability, x-kombify-internal and x-kombify-envelope. Parameters and body properties accept x-kombify-name. See README.md.

Index

Constants

View Source 
const (
	ActionRead            = "read"
	ActionReversibleWrite = "reversible_write"
	ActionExternalWrite   = "external_write"
	ActionDestructive     = "destructive"
	ActionCostBearing     = "cost_bearing"
)

Gateway action classes, ordered read < reversible_write < external_write < destructive / cost_bearing (kombify-Gateway MCP_ACTION_CLASSES).

View Source 
const (
	InPath   = "path"
	InQuery  = "query"
	InHeader = "header"
	InBody   = "body"
)

Argument locations.

View Source 
const (
	BodyProperties = "properties"
	BodyJSON       = "json"
	BodyFile       = "file"
)

Body modes.

View Source 
const CatalogFragmentKind = "kombify.mcp-catalog-fragment/v1"

CatalogFragmentKind identifies the Gateway MCP catalog fragment artifact.

View Source 
const SchemaVersion = "kombify.api-surface/v1"

SchemaVersion identifies the api-surface.json artifact format.

View Source 
const ToolManifestSchemaVersion = "kombify.tool-manifest/v1"

ToolManifestSchemaVersion identifies the product-native MCP tool manifest.

Variables

This section is empty.

Functions

func ActionClassFor 

func ActionClassFor(m *MCP) string

ActionClassFor returns the tool's Gateway action class: the explicit x-kombify-mcp.actionClass, else read for read-only tools, cost_bearing, destructive, external_write for open-world writes and reversible_write.

func KebabCase 

func KebabCase(s string) string

KebabCase converts an identifier or phrase to kebab-case with the same word boundaries as SnakeCase: "Stacks - Specs" becomes "stacks-specs".

func PublicOpenAPI 

func PublicOpenAPI(spec []byte, asYAML bool) ([]byte, error)

PublicOpenAPI projects a spec for published API reference documentation: operations marked x-kombify-internal: true are removed (path items left without operations are dropped, as are aliases of dropped paths) and every x-kombify-* key is stripped at every level, as are YAML comments. Everything else is kept; YAML output keeps the source key order, JSON output sorts keys.

func SnakeCase 

func SnakeCase(s string) string

SnakeCase converts an identifier to snake_case. Acronym boundaries are preserved: "getURLStatus" becomes "get_url_status", "serverId" becomes "server_id" and "X-Idempotency-Key" becomes "x_idempotency_key".

Types

type Annotations 

type Annotations struct {
	ReadOnlyHint    bool `json:"readOnlyHint"`
	DestructiveHint bool `json:"destructiveHint"`
	IdempotentHint  bool `json:"idempotentHint"`
	OpenWorldHint   bool `json:"openWorldHint"`
}

Annotations are the MCP tool behavior hints.

type Argument 

type Argument struct {
	Name        string         `json:"name"`
	In          string         `json:"in"`
	WireName    string         `json:"wireName,omitempty"`
	Required    bool           `json:"required,omitempty"`
	Description string         `json:"description,omitempty"`
	Schema      map[string]any `json:"schema,omitempty"`
}

Argument is one caller-supplied input. Name is the surface name shared by CLI flags and MCP tool properties; WireName is the HTTP name.

type Body 

type Body struct {
	ContentType string `json:"contentType"`
	Required    bool   `json:"required,omitempty"`
	Mode        string `json:"mode"`
}

Body describes the request body.

type CLI 

type CLI struct {
	Command []string `json:"command"`
	Aliases []string `json:"aliases,omitempty"`
	Args    []string `json:"args,omitempty"`
	Hidden  bool     `json:"hidden,omitempty"`
}

CLI binds the operation to a command path.

type Catalog 

type Catalog struct {
	ServerKey             string
	ConnectorFamily       string
	Upstream              CatalogUpstream
	PortalVisibilityGroup string
	RequiredScopes        []string
	FeaturePrefix         string
	QuotaPrefix           string
	AuditPrefix           string
}

Catalog is x-kombify-surface.mcp.catalog: how the product's tools enter the Gateway's public MCP catalog.

type CatalogFragment 

type CatalogFragment struct {
	Kind      string        `json:"kind"`
	ServerKey string        `json:"serverKey"`
	Source    CatalogSource `json:"source"`
	Tools     []CatalogTool `json:"tools"`
}

CatalogFragment is the product's contribution to the Gateway MCP catalog.

func (*CatalogFragment) Marshal 

func (f *CatalogFragment) Marshal() ([]byte, error)

Marshal encodes the fragment deterministically: 2-space indent, trailing newline, no HTML escaping.

type CatalogSource 

type CatalogSource struct {
	Product string `json:"product"`
	Path    string `json:"path"`
	SHA256  string `json:"sha256"`
}

CatalogSource binds the fragment to the spec it was generated from.

type CatalogTool 

type CatalogTool struct {
	ToolID                string           `json:"toolId"`
	ConnectorFamily       string           `json:"connectorFamily"`
	ServerKey             string           `json:"serverKey"`
	ToolName              string           `json:"toolName"`
	Alias                 string           `json:"alias"`
	Title                 string           `json:"title,omitempty"`
	Description           string           `json:"description,omitempty"`
	InputSchema           map[string]any   `json:"inputSchema"`
	Annotations           Annotations      `json:"annotations"`
	FeatureKey            string           `json:"featureKey"`
	EntitlementKey        string           `json:"entitlementKey"`
	FGAObject             string           `json:"fgaObject"`
	AuditEvent            string           `json:"auditEvent"`
	OperationIDs          []string         `json:"operationIds"`
	Risk                  string           `json:"risk"`
	ApprovalPolicy        string           `json:"approvalPolicy"`
	ActionClass           string           `json:"actionClass"`
	QuotaKey              string           `json:"quotaKey"`
	Upstream              CatalogUpstream  `json:"upstream"`
	PortalVisibilityGroup string           `json:"portalVisibilityGroup"`
	RequiredScopes        []string         `json:"requiredScopes"`
	CapabilityBundle      string           `json:"capabilityBundle"`
	RequiredCapabilities  []string         `json:"requiredCapabilities"`
	ResourceBinding       *ResourceBinding `json:"resourceBinding,omitempty"`
	CostBearing           bool             `json:"costBearing"`
	UpstreamKind          string           `json:"upstreamKind"`
	LiveEnabled           bool             `json:"liveEnabled"`
}

CatalogTool is one tool entry in the Gateway's live catalog format.

type CatalogUpstream 

type CatalogUpstream struct {
	Kind string `json:"kind"`
	Ref  string `json:"ref"`
}

CatalogUpstream names the backend the Gateway forwards tool calls to.

type HTTPBinding 

type HTTPBinding struct {
	Method string `json:"method"`
	Path   string `json:"path"`
}

HTTPBinding names the REST operation backing a tool.

type MCP 

type MCP struct {
	ToolName           string      `json:"toolName"`
	Title              string      `json:"title,omitempty"`
	RequiredCapability string      `json:"requiredCapability"`
	Annotations        Annotations `json:"annotations"`
	// CostBearing marks a tool whose call charges the user.
	CostBearing bool `json:"costBearing,omitempty"`
	// ActionClass is an explicit Gateway action class; empty means derived
	// (see ActionClassFor).
	ActionClass string `json:"actionClass,omitempty"`
	// ResourceBinding scopes authorization to the resource one argument
	// names (explicit tools only).
	ResourceBinding *ResourceBinding `json:"resourceBinding,omitempty"`
	// Derived marks a tool built from x-kombify-surface.mcp.defaults rather
	// than an explicit x-kombify-mcp object.
	Derived bool `json:"derived,omitempty"`
}

MCP binds the operation to an MCP tool.

type Operation 

type Operation struct {
	OperationID  string     `json:"operationId"`
	Method       string     `json:"method"`
	Path         string     `json:"path"`
	Summary      string     `json:"summary,omitempty"`
	Description  string     `json:"description,omitempty"`
	Tags         []string   `json:"tags,omitempty"`
	Availability string     `json:"availability,omitempty"`
	Deprecated   bool       `json:"deprecated,omitempty"`
	Confirmation string     `json:"confirmation,omitempty"`
	Mutating     bool       `json:"mutating,omitempty"`
	Arguments    []Argument `json:"arguments,omitempty"`
	Body         *Body      `json:"body,omitempty"`
	Output       *Output    `json:"output,omitempty"`
	CLI          CLI        `json:"cli"`
	MCP          *MCP       `json:"mcp,omitempty"`
	// MCPExcluded records the reviewed decision (x-kombify-mcp: false) that
	// the operation is not an agent tool.
	MCPExcluded bool `json:"mcpExcluded,omitempty"`
}

Operation is one exposed OpenAPI operation.

type Output 

type Output struct {
	ContentType string         `json:"contentType"`
	Envelope    string         `json:"envelope,omitempty"`
	Schema      map[string]any `json:"schema,omitempty"`
}

Output describes the first successful JSON response. Schema is the payload schema after Envelope has been unwrapped.

type Problem 

type Problem struct {
	OperationID string
	Rule        string
	Message     string
}

Problem is one contract violation. OperationID is empty for document-level problems.

func (Problem) String 

func (p Problem) String() string

type ResourceBinding 

type ResourceBinding struct {
	Argument  string `json:"argument"`
	Dimension string `json:"dimension"`
}

ResourceBinding names the surface argument that identifies the resource a call acts on and the authorization dimension it belongs to.

type Result 

type Result struct {
	Surface *Surface
	// ParityGaps lists operationIds that are exposed to API and CLI but have
	// no MCP decision: no x-kombify-mcp and no x-kombify-surface.mcp.defaults.
	ParityGaps []string
	// Excluded lists operationIds with the reviewed decision
	// x-kombify-mcp: false.
	Excluded []string
	// Catalog is x-kombify-surface.mcp.catalog, nil when absent. It feeds
	// Surface.CatalogFragment.
	Catalog *Catalog
}

Result is a generated surface plus the non-failing report.

func Generate 

func Generate(specPath string, spec []byte) (*Result, error)

Generate reads an OpenAPI 3.1 document (YAML or JSON) with x-kombify-* extensions and builds its Surface. specPath is recorded as the source path. Contract violations are returned together as a *ValidationError.

type RootCLI 

type RootCLI struct {
	Command string `json:"command,omitempty"`
}

RootCLI names the product binary.

type RootMCP 

type RootMCP struct {
	Transport       string `json:"transport,omitempty"`
	Endpoint        string `json:"endpoint,omitempty"`
	ProtocolVersion string `json:"protocolVersion,omitempty"`
}

RootMCP identifies the product-native MCP endpoint.

type Source 

type Source struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
}

Source binds the surface to the exact spec bytes it was generated from.

type Surface 

type Surface struct {
	SchemaVersion string      `json:"schemaVersion"`
	Product       string      `json:"product"`
	Source        Source      `json:"source"`
	Envelope      string      `json:"envelope,omitempty"`
	CLI           *RootCLI    `json:"cli,omitempty"`
	Capability    string      `json:"capability,omitempty"`
	MCP           *RootMCP    `json:"mcp,omitempty"`
	Operations    []Operation `json:"operations"`
}

Surface is the language-neutral projection of one product's OpenAPI contract. It is the single input for generated CLI commands and the MCP tool manifest.

func Parse 

func Parse(data []byte) (*Surface, error)

Parse decodes an api-surface.json artifact, typically embedded by a product binary.

func (*Surface) CatalogFragment 

func (s *Surface) CatalogFragment(c *Catalog) *CatalogFragment

CatalogFragment projects every MCP tool into the Gateway catalog format, tools sorted by toolName. Title, description and input schema are those of the tool manifest. Derived tools start with liveEnabled false so the Gateway curates them before they go live.

func (*Surface) Marshal 

func (s *Surface) Marshal() ([]byte, error)

Marshal encodes the surface deterministically: 2-space indent, trailing newline, no HTML escaping.

func (*Surface) ToolManifest 

func (s *Surface) ToolManifest() *ToolManifest

ToolManifest projects every MCP-exposed operation into the tool manifest, tools sorted by name. Output schemas are kept only for object payloads.

type ToolDefinition 

type ToolDefinition struct {
	Name               string         `json:"name"`
	Title              string         `json:"title,omitempty"`
	Description        string         `json:"description,omitempty"`
	RequiredCapability string         `json:"requiredCapability"`
	OperationID        string         `json:"operationId"`
	HTTP               HTTPBinding    `json:"http"`
	InputSchema        map[string]any `json:"inputSchema"`
	OutputSchema       map[string]any `json:"outputSchema,omitempty"`
	Annotations        Annotations    `json:"annotations"`
}

ToolDefinition binds one operation to HTTP and MCP.

type ToolManifest 

type ToolManifest struct {
	SchemaVersion string           `json:"schema_version"`
	Product       string           `json:"product"`
	Capability    string           `json:"capability,omitempty"`
	MCP           ToolManifestMCP  `json:"mcp"`
	Tools         []ToolDefinition `json:"tools"`
}

ToolManifest is the product-level MCP discovery document consumed by the product's native MCP server, discovery and Gateway validation.

func (*ToolManifest) Marshal 

func (m *ToolManifest) Marshal() ([]byte, error)

Marshal encodes the manifest deterministically: 2-space indent, trailing newline, no HTML escaping.

type ToolManifestMCP 

type ToolManifestMCP struct {
	Transport       string `json:"transport"`
	Endpoint        string `json:"endpoint"`
	ProtocolVersion string `json:"protocol_version"`
}

ToolManifestMCP identifies the transport endpoint and protocol version.

type ValidationError 

type ValidationError struct {
	Problems []Problem
}

ValidationError reports every contract violation found in one generation.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Package cli mounts an apisurface.Surface as cobra commands.
 Package cli mounts an apisurface.Surface as cobra commands.

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.