core: a protocol can be registered per client, and a client owns what it creates
Reference-implementation counterpart of typescript-utcp #52 and #54. The spec is generated from this repo's REQUIRED docstrings, so every new piece of surface carries one (checked with scripts/extract_required_docs.py).
The gap
A protocol registered in communication_protocols is one instance shared by every UtcpClient in the process, and so is any state it keeps. Right for a credential cache; wrong for connections. A caller creating a client per tenant, per user or per pooled connection was not actually isolating them — every client dialled into the same MCP session cache — and no client could tear its own connections down: the Python client had no close() at all.
The mechanism
- New registry
communication_protocol_factories, filled throughregister_communication_protocol_factory(type, factory).UtcpClient.createcalls a factory once per client and the client records the instance as owned. A factory wins over a shared instance of the same type, so a plugin migrates by moving its registration and callers change nothing. Shared instances are still looked up live, so registering one after a client exists keeps working (existing tests rely on it). - Teardown scoped to what the client owns. New
UtcpClient.close()(interface + implementation) closes the owned instances and leaves shared ones to the process. Every instance is closed even when one fails; the failures are then raised together asUtcpProtocolCloseError. create()adopts factories inside a cleanup guard. Nothing that needs closing is created in the constructor (it can't await). A factory that raises part-way leaves the earlier instances closable; any initialization failure closes them before re-raising; a failing cleanup is logged with the original error kept as the one the caller sees.CommunicationProtocol.close()joins the interface, a no-op by default, so the client can close any protocol uniformly.utcp-mcpregisters as a factory — sessions and stdio child processes belong to the client that opened them.utcp-httpstays shared: its OAuth cache is meant to be reused.
Versions
Core → 1.2.0 (new registry + close() on the client interface), utcp-mcp → 1.2.0 requiring utcp>=1.2.0.
Tests
Ten, all through the public surface (core/tests/client/test_client_protocol_ownership.py): per-client routing, factory over shared, late shared registration, unknown type names both registries, close() scoped to the own instance, close() waits for every instance even when one fails, failed create() closes what it created, a raising factory leaves earlier instances closed, a shared instance survives a failed create(), a failing cleanup is reported. Each guard mutation-checked — every mutation fails exactly its tests. Core 51/51, MCP 48/48, http 238, cli 62, text 11.
🤖 Generated with Claude Code
Summary by cubic
Protocols can now be registered per client, so each UtcpClient owns its protocol instances and can close them. Previously one protocol instance was shared by every client, which broke per-tenant isolation and left connections unclosed.
Refactors
- Added
communication_protocol_factories;UtcpClient.createinstantiates each registered factory per client, and factories registered later are adopted and owned on first use. - Added
UtcpClient.close()to close owned protocol instances; shared instances remain process-wide. - Added
CommunicationProtocol.close()as an interface method with a no-op default. - A failed
create()closes any owned instances before re-raising; close failures are collected inUtcpProtocolCloseError. register_manualswaits for every sibling registration to settle before raising, so a failedcreate()never closes a protocol another registration is still using.utcp-mcpandutcp-websocketnow register as factories;utcp-httpstays shared.
Migration
- Protocols whose state must not be shared between clients should switch from
register_communication_protocoltoregister_communication_protocol_factory. utcp,utcp-mcp, andutcp-websocketbecome 1.2.0, with the plugins requiringutcp>=1.2.0.