[Server] ServerBuilder Method Naming Creates Semantic Confusion

[butschster]

Hey team! 👋

I was diving into the ServerBuilder class and noticed something that might be worth discussing around method naming conventions. The current implementation uses with* prefixes for methods that actually mutate the existing object:

// Current implementation in ServerBuilder
public function withTool(/* ... */): self
{
    $this->manualTools[] = compact(/* ... */); // Mutates the current instance
    return $this;
}

public function withLogger(LoggerInterface $logger): self
{
    $this->logger = $logger; // Mutates the current instance
    return $this;
}

The Potential Issue

In the PHP ecosystem, the with* prefix has become conventionally associated with immutable operations that return new instances (think PSR-7 HTTP messages, Carbon dates, etc.), while the actual behavior here is mutable. This semantic mismatch might lead to some confusion for developers who expect immutable behavior.

Here's what developers might expect vs. what actually happens:

// What developers might expect (immutable)
$builder1 = ServerBuilder::make();
$builder2 = $builder1->withLogger($customLogger);
// $builder1 and $builder2 would be different instances

// What actually happens (mutable)  
$builder1 = ServerBuilder::make();
$builder2 = $builder1->withLogger($customLogger);
// $builder1 and $builder2 are the same instance

Is there a specific reason for choosing the with* naming, or would you be open to exploring alternatives? Happy to create a PR!

Let me know what you think! 🚀

[chr-hertel]

what's the difference to your issue #43?

[CodeWithKyrian]

@chr-hertel , this is about the confusing use of with* in the builder. It’s the same concern he raised earlier in php-mcp/server#65, which I agreed with then. It’s separate from #43, which is about the static make method on the Server.

I agree with you again here @butschster. We should either update the builder’s with* methods to return new builder instances, or switch to set*. I'm leaning towards the former.