Value: add numberValue (Double?) that coerces .int and .double (closes #225)

[gsdali]

Closes #225.

Summary

Adds Value.numberValue: Double? that coerces both .int and .double to Double. Motivation in #225 — short version:

JSON has a single number type with no integer/floating-point distinction. Swift's JSONEncoder writes whole-number Doubles without a decimal point (Value.double(0) → JSON 0) and Value's init(from:) tries Int first (JSON 0 → Value.int(0)). So any consumer reading numeric tool arguments via arr[N].doubleValue silently fails for [0, 0, 1] (the natural unit-vector shape an LLM would emit) — works fine for [0.5, 0.5, 0.5] test fixtures, breaks in production.

numberValue returns the underlying scalar promoted to Double for .int(_) and .double(_); nil otherwise. Additive — no breaking changes.

Why on the SDK side

I hit this in OCCTMCP on a coordinate-array tool argument; the workaround is a one-line extension that every Swift MCP server is going to copy:

extension Value {
    var asDouble: Double? {
        if let d = doubleValue { return d }
        if let i = intValue { return Double(i) }
        return nil
    }
}

Better to ship it once on the SDK so consumers don't reinvent it (or, more likely, hit the silent-fail path before realising they need to).

Implementation

public var numberValue: Double? {
    switch self {
    case .int(let value):    return Double(value)
    case .double(let value): return value
    default:                 return nil
    }
}

Doc comment explicitly calls out the JSON whole-number-decodes-as-int gotcha so future readers learn why this exists alongside intValue / doubleValue.

Test plan

• swift build clean
• swift test — 557/557 tests pass (was 551; +6 in ValueTests)
• New ValueTests cover: int → Double, double → Double pass-through, nil for non-numeric cases, and the round-trip case that motivated this — encode Value.double(0) and assert decoded.doubleValue == nil (the gotcha), decoded.numberValue == 0.0 (the fix), plus a [0, 0, 1]-shaped coordinate-array round-trip end-to-end.

Out of scope

• A Bool-coercing accessor (no 0/1 ↔ true/false precedent in MCP schemas).
• Treating String numerics like "42" as numbers — schemas should reject those.
• A throwing variant — nil-returning matches the existing accessor style.

🤖 Generated with Claude Code