semverkit

Agentic-first semantic version parsing and comparison service.

Parse, validate, compare, bump, and sort semantic versions (semver.org). Range satisfaction checking with ^, ~, >=, <, ||, hyphen, and wildcards. Plain text API, agent-driven, single Go binary.

Quick Start

make build
./semverkit
# → listen on :8080

API Reference

Method	Endpoint	Description
GET	/parse/{version}	Parse semver into components
GET	/validate/{version}	Validate a semver string
GET	/compare/{v1}/{v2}	Compare two versions
GET	/bump/{version}/{type}	Bump version (major/minor/patch/prerelease)
GET	/satisfies/{version}/{range}	Check if version satisfies a range
GET	/latest?versions=v1,v2,v3	Find the highest version
GET	/sort?versions=v1,v2,v3&order=asc|desc	Sort versions
GET	/range/{range}	Parse and describe a range
GET	/between/{version}/{low}/{high}	Check if version is in [low, high]
GET	/diff/{v1}/{v2}	Show what changed between versions
POST	/mcp	MCP JSON-RPC 2.0 endpoint
GET	/help	Self-documenting operating manual

Examples

# Parse a version
curl http://localhost:8080/parse/1.2.3-alpha+build
# major=1 minor=2 patch=3 prerelease=alpha build=build prerelease=true valid=true

# Compare versions
curl http://localhost:8080/compare/1.0.0/2.0.0
# v1=1.0.0 v2=2.0.0 result=before

# Bump a version
curl http://localhost:8080/bump/1.2.3/patch
# input=1.2.3 type=patch result=1.2.4

# Check range satisfaction
curl http://localhost:8080/satisfies/1.5.0/^1.2.3
# version=1.5.0 range=^1.2.3 satisfies=true

# Find latest version
curl "http://localhost:8080/latest?versions=1.0.0,2.0.0,1.5.0"
# latest=2.0.0

# Sort versions
curl "http://localhost:8080/sort?versions=3.0.0,1.0.0,2.0.0&order=asc"
# 1.0.0
# 2.0.0
# 3.0.0

Range Syntax

Syntax	Meaning
^1.2.3	Compatible with 1.x.x (>=1.2.3 <2.0.0)
~1.2.3	Patch-level changes (>=1.2.3 <1.3.0)
>=1.0.0	Greater than or equal
<2.0.0	Less than
>=1.0.0 <2.0.0	Range (AND)
1.0.0 - 2.0.0	Hyphen range (>=1.0.0 <=2.0.0)
1.2.x	Wildcard (>=1.2.0 <1.3.0)
*	Any version
>=1.0.0 <2.0.0 || >=3.0.0 <4.0.0	OR groups

Response Format

• Plain text by default (one labeled line per record)
• JSON on demand: Accept: application/json or ?format=json
• Errors: error: message | hint: what to do next

Configuration

Source	Variable	Default	Description
Env	SEMVERKIT_ADDR	:8080	Listen address
Flag	-addr	:8080	Same as env

Build

make build    # CGO_ENABLED=0 go build -trimpath
make test     # go test -race ./...
make vet      # go vet ./...

License

MIT