Coverage for mcpgateway / plugins / framework / protocols.py: 100%

1# -*- coding: utf-8 -*- 

2"""Location: ./mcpgateway/plugins/framework/protocols.py 

3Copyright 2026 

4SPDX-License-Identifier: Apache-2.0 

5Authors: Fred Araujo 

6 

7Protocol definitions for types that cross the gateway-framework boundary. 

8 

9These replace concrete imports of Message and PromptResult from 

10mcpgateway.common.models, allowing the framework to express structural 

11contracts without creating a dependency on the outer package. 

12 

13Examples: 

14 >>> from mcpgateway.plugins.framework.protocols import MessageLike, PromptResultLike 

15 >>> import typing 

16 >>> typing.runtime_checkable(MessageLike) # Already decorated 

17 <class 'mcpgateway.plugins.framework.protocols.MessageLike'> 

18""" 

19 

20# Standard 

21from typing import Any, Optional, Protocol, runtime_checkable, Sequence 

22 

23 

24@runtime_checkable 

25class MessageLike(Protocol): 

26 """Structural contract for message objects. 

27 

28 The framework never instantiates Message directly -- it receives 

29 them from the service layer. Any object with ``role`` and 

30 ``content`` attributes satisfies this protocol structurally. 

31 

32 Attributes: 

33 role: str or Role enum indicating the message sender. 

34 content: TextContent, ImageContent, or other content type. 

35 

36 Examples: 

37 >>> from types import SimpleNamespace 

38 >>> msg = SimpleNamespace(role="user", content="hello") 

39 >>> isinstance(msg, MessageLike) 

40 True 

41 """ 

42 

43 role: str 

44 content: Any 

45 

46 

47@runtime_checkable 

48class PromptResultLike(Protocol): 

49 """Structural contract for prompt result objects. 

50 

51 The framework never instantiates PromptResult directly -- it 

52 receives them from the service layer. Any object with 

53 ``messages`` and ``description`` attributes satisfies this 

54 protocol structurally. 

55 

56 Attributes: 

57 messages: Sequence of MessageLike objects. 

58 description: Optional description of the rendered result. 

59 

60 Examples: 

61 >>> from types import SimpleNamespace 

62 >>> result = SimpleNamespace(messages=[], description=None) 

63 >>> isinstance(result, PromptResultLike) 

64 True 

65 """ 

66 

67 messages: Sequence[MessageLike] 

68 description: Optional[str]