Add tooling to auto-generate server.schema.json from OpenAPI spec (#629)

This 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>

Makefile

@@ -1,4 +1,4 @@
-.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
+.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
@@ -14,6 +14,17 @@ 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..."
@@ -45,6 +56,7 @@ 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