568748e4bfThis PR adds a Go tool that extracts the ServerDetail schema from
openapi.yaml and generates server.schema.json, ensuring the two specs
stay in sync.
## Key Changes
### New Tooling
- **Go tool** at `tools/extract-server-schema/` that auto-discovers all
schemas referenced by ServerDetail and extracts them from OpenAPI
- **make targets**: `generate-schema` (generates schema) and
`check-schema` (verifies sync)
- `check-schema` is now included in `make validate` and `make check`
### Preserved Validation Constraints
The initial auto-generated schema lost many important validation rules
and descriptive guidance from the hand-crafted version. The OpenAPI spec
has been updated to preserve:
**Security & Descriptions:**
- Command injection security warning on Arguments
- Detailed field descriptions with usage guidance
- `placeholder` field for Input schema
**Validation Constraints:**
- `fileSha256` pattern validation (`^[a-f0-9]{64}$`)
- Package version restrictions (minLength: 1, no "latest")
- `transport` as required field in Package
- ServerDetail `name` pattern and length constraints (3-200 chars)
- Description, title, and version length limits
**Documentation:**
- Repository field descriptions (url, source, id, subfolder)
- PositionalArgument `valueHint` explains transport URL substitution
- Updated examples to match hand-crafted version (Weather API theme)
**Intentional Changes:**
- Removed `additionalProperties` constraints for flexibility
- Updated schema title to be more descriptive
- Added `$comment` noting auto-generation
See the commit "Preserve validation constraints in auto-generated
server.schema.json" for details.
### Fixed Missing Package.transport
- Added `transport` field to OpenAPI Package schema (was in Go model at
`pkg/model/types.go:30` but missing from OpenAPI)
- Split transport types into three separate schemas with proper
discriminated unions:
- `StdioTransport` - Only requires `type: stdio`
- `StreamableHttpTransport` - Requires `type` and `url`, supports
`headers`
- `SseTransport` - Requires `type` and `url`, supports `headers`
- `Package.transport` uses `anyOf` with all three types
- `ServerDetail.remotes` uses `anyOf` with only remote types (no stdio)
### Other Improvements
- Added `GOTOOLCHAIN=auto` to Makefile for Go 1.25 compatibility
- Added `DRIFT_ANALYSIS.md` documenting all schema drift issues found
between specs
## Benefits
**Single Source of Truth**: The OpenAPI spec now serves as the
authoritative schema definition, with server.schema.json automatically
derived from it.
**Better Validation**: All critical validation rules (patterns, length
constraints, required fields) and security warnings are preserved in the
generated schema.
**Improved Developer Experience**:
- Schema changes only need to be made in one place (openapi.yaml)
- CI validation ensures specs never drift apart
- Clear auto-generation comment prevents manual edits
## Validation
✅ All 20 examples validate correctly
✅ Lint passes with 0 issues
✅ Schema is in sync with OpenAPI
✅ All validation constraints from hand-crafted schema preserved
---------
Co-authored-by: Claude <noreply@anthropic.com>
90 lines
3.3 KiB
Makefile
90 lines
3.3 KiB
Makefile
.PHONY: help build test test-unit test-integration test-endpoints test-publish test-all lint lint-fix validate validate-schemas validate-examples check dev-compose clean publisher generate-schema check-schema
|
|
|
|
# Default target
|
|
help: ## Show this help message
|
|
@echo "Available targets:"
|
|
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " %-20s %s\n", $$1, $$2}'
|
|
|
|
# Build targets
|
|
build: ## Build the registry application with version info
|
|
@mkdir -p bin
|
|
go build -ldflags="-X main.Version=dev-$(shell git rev-parse --short HEAD) -X main.GitCommit=$(shell git rev-parse HEAD) -X main.BuildTime=$(shell date -u +%Y-%m-%dT%H:%M:%SZ)" -o bin/registry ./cmd/registry
|
|
|
|
publisher: ## Build the publisher tool with version info
|
|
@mkdir -p bin
|
|
go build -ldflags="-X main.Version=dev-$(shell git rev-parse --short HEAD) -X main.GitCommit=$(shell git rev-parse HEAD) -X main.BuildTime=$(shell date -u +%Y-%m-%dT%H:%M:%SZ)" -o bin/mcp-publisher ./cmd/publisher
|
|
|
|
# Schema generation targets
|
|
generate-schema: ## Generate server.schema.json from openapi.yaml
|
|
@mkdir -p bin
|
|
go build -o bin/extract-server-schema ./tools/extract-server-schema
|
|
@./bin/extract-server-schema
|
|
|
|
check-schema: ## Check if server.schema.json is in sync with openapi.yaml
|
|
@mkdir -p bin
|
|
go build -o bin/extract-server-schema ./tools/extract-server-schema
|
|
@./bin/extract-server-schema -check
|
|
|
|
# Test targets
|
|
test-unit: ## Run unit tests with coverage (requires PostgreSQL)
|
|
@echo "Starting PostgreSQL for unit tests..."
|
|
@docker compose up -d postgres
|
|
@echo "Waiting for PostgreSQL to be ready..."
|
|
@sleep 3
|
|
@echo "Running unit tests..."
|
|
go test -v -race -coverprofile=coverage.out -covermode=atomic ./internal/...
|
|
go tool cover -html=coverage.out -o coverage.html
|
|
@echo "Coverage report generated: coverage.html"
|
|
@echo "Stopping PostgreSQL..."
|
|
@docker compose down postgres
|
|
|
|
test: ## Run unit tests (use 'make test-all' to run all tests)
|
|
@echo "⚠️ Running unit tests only. Use 'make test-all' to run both unit and integration tests."
|
|
@$(MAKE) test-unit
|
|
|
|
test-integration: ## Run integration tests
|
|
./tests/integration/run.sh
|
|
|
|
test-endpoints: ## Test API endpoints (requires running server)
|
|
./scripts/test_endpoints.sh
|
|
|
|
test-publish: ## Test publish endpoint (requires BEARER_TOKEN env var)
|
|
./scripts/test_publish.sh
|
|
|
|
test-all: test-unit test-integration ## Run all tests (unit and integration)
|
|
|
|
# Validation targets
|
|
validate-schemas: ## Validate JSON schemas
|
|
./tools/validate-schemas.sh
|
|
@$(MAKE) check-schema
|
|
|
|
validate-examples: ## Validate examples against schemas
|
|
./tools/validate-examples.sh
|
|
|
|
validate: validate-schemas validate-examples ## Run all validation checks
|
|
|
|
# Lint targets
|
|
lint: ## Run linter (includes formatting)
|
|
golangci-lint run --timeout=5m
|
|
|
|
lint-fix: ## Run linter with auto-fix (includes formatting)
|
|
golangci-lint run --fix --timeout=5m
|
|
|
|
# Combined targets
|
|
check: dev-down lint validate test-all ## Run all checks (lint, validate, unit tests) and ensure dev environment is down
|
|
@echo "All checks passed!"
|
|
|
|
# Development targets
|
|
dev-compose: ## Start development environment with Docker Compose (builds image automatically)
|
|
docker compose up --build
|
|
|
|
dev-down: ## Stop development environment
|
|
docker compose down
|
|
|
|
# Cleanup
|
|
clean: ## Clean build artifacts and coverage files
|
|
rm -rf bin
|
|
rm -f coverage.out coverage.html
|
|
|
|
|
|
.DEFAULT_GOAL := help
|