@@ -5,45 +5,159 @@ import chimp.client.transport.{BidirectionalTransport, Transport}
55import chimp .protocol .*
66import io .circe .Json
77
8+ /** A Model Context Protocol (MCP) client that has completed the initialization handshake with a server.
9+ *
10+ * Exposes the server's advertised capabilities and identity, and provides methods for sending client-initiated requests and notifications
11+ * over the underlying [[chimp.client.transport.Transport ]].
12+ *
13+ * For bidirectional interaction (server-initiated requests, resource subscriptions, notification listeners), use
14+ * [[BidirectionalMcpClient ]] instead.
15+ */
816trait McpClient [F [_]]:
17+ /** Sends a `ping` request to the server. */
918 def ping (): F [Unit ]
19+
20+ /** Closes the underlying transport and releases any resources held by this client. */
1021 def close (): F [Unit ]
1122
23+ /** Capabilities advertised by the server during the initialization handshake. */
1224 def serverCapabilities : ServerCapabilities
25+
26+ /** Server implementation name and version, received during the initialization handshake. */
1327 def serverInfo : Implementation
1428
29+ /** Lists tools exposed by the server.
30+ *
31+ * @param cursor
32+ * Optional pagination cursor returned by a previous call; by default uses `None` and starts from the beginning.
33+ */
1534 def listTools (cursor : Option [Cursor ] = None ): F [ListToolsResponse ]
35+
36+ /** Invokes a tool on the server.
37+ *
38+ * @param name
39+ * The tool's name, as reported by [[listTools ]].
40+ * @param arguments
41+ * JSON object containing the tool's input, matching its declared input schema.
42+ */
1643 def callTool (name : String , arguments : Json ): F [CallToolResult ]
1744
45+ /** Lists prompt templates exposed by the server.
46+ *
47+ * @param cursor
48+ * Optional pagination cursor returned by a previous call; by default uses `None` and starts from the beginning.
49+ */
1850 def listPrompts (cursor : Option [Cursor ] = None ): F [ListPromptsResult ]
51+
52+ /** Retrieves a prompt template by name, substituting the given arguments.
53+ *
54+ * @param name
55+ * The prompt's name, as reported by [[listPrompts ]].
56+ * @param arguments
57+ * Values for the prompt template's arguments; defaults to empty.
58+ */
1959 def getPrompt (name : String , arguments : Map [String , String ] = Map .empty): F [GetPromptResult ]
2060
61+ /** Lists resources exposed by the server.
62+ *
63+ * @param cursor
64+ * Optional pagination cursor returned by a previous call; by default uses `None` and starts from the beginning.
65+ */
2166 def listResources (cursor : Option [Cursor ] = None ): F [ListResourcesResult ]
67+
68+ /** Lists resource templates exposed by the server.
69+ *
70+ * @param cursor
71+ * Optional pagination cursor returned by a previous call; by default uses `None` and starts from the beginning.
72+ */
2273 def listResourceTemplates (cursor : Option [Cursor ] = None ): F [ListResourceTemplatesResult ]
74+
75+ /** Reads the contents of a resource identified by its URI. */
2376 def readResource (uri : String ): F [ReadResourceResult ]
2477
78+ /** Requests completion suggestions for an argument of a prompt or resource template reference. */
2579 def complete (ref : CompleteRef , argument : CompleteArgument ): F [CompleteResult ]
2680
81+ /** Sets the minimum severity level for log messages the server should forward to this client. */
2782 def setLoggingLevel (level : LoggingLevel ): F [Unit ]
2883
84+ /** Sends a progress notification for a previously issued request that advertised a progress token.
85+ *
86+ * @param token
87+ * The progress token associated with the in-flight request.
88+ * @param progress
89+ * Current progress value; the unit is opaque and chosen by the sender.
90+ * @param total
91+ * Optional total value, used by the receiver to compute a percentage.
92+ * @param message
93+ * Optional human-readable description of the current step.
94+ */
2995 def sendProgress (token : ProgressToken , progress : Double , total : Option [Double ] = None , message : Option [String ] = None ): F [Unit ]
96+
97+ /** Sends a `cancelled` notification, asking the server to stop processing a previously issued request.
98+ *
99+ * @param requestId
100+ * Identifier of the request to cancel.
101+ * @param reason
102+ * Optional human-readable explanation.
103+ */
30104 def sendCancelled (requestId : RequestId , reason : Option [String ] = None ): F [Unit ]
31105
106+ /** An [[McpClient ]] used over a [[chimp.client.transport.BidirectionalTransport ]], which additionally supports server-initiated
107+ * interactions: subscribing to resource updates, notifying the server about changes to the client's roots, and handling notifications
108+ * pushed by the server.
109+ */
32110trait BidirectionalMcpClient [F [_]] extends McpClient [F ]:
111+ /** Subscribes to updates for the resource identified by the given URI. The server will emit `resources/updated` notifications, which can
112+ * be observed via [[onServerNotification ]].
113+ */
33114 def subscribeResource (uri : String ): F [Unit ]
115+
116+ /** Cancels a subscription previously created with [[subscribeResource ]]. */
34117 def unsubscribeResource (uri : String ): F [Unit ]
118+
119+ /** Notifies the server that the list of roots exposed by this client has changed. */
35120 def sendRootsListChanged (): F [Unit ]
121+
122+ /** Registers a listener for notifications pushed by the server (e.g. resource updates, tool/prompt list changes, log messages). */
36123 def onServerNotification (listener : ServerNotificationListener [F ]): F [Unit ]
37124
38125object McpClient :
126+ /** Creates an unidirectional [[McpClient ]] over the given [[chimp.client.transport.Transport ]] and performs the initialization handshake
127+ * with the server.
128+ *
129+ * @param transport
130+ * The transport carrying JSON-RPC messages between client and server.
131+ * @param clientInfo
132+ * Implementation name and version advertised to the server during initialization.
133+ * @param protocolVersion
134+ * Protocol version proposed during initialization; defaults to the latest version supported by chimp.
135+ */
39136 def apply [F [_]](
40137 transport : Transport [F ],
41138 clientInfo : Implementation ,
42- protocolVersion : ProtocolVersion
139+ protocolVersion : ProtocolVersion = ProtocolVersion . Latest
43140 ): F [McpClient [F ]] =
44141 McpClientImpl .create(transport, clientInfo, protocolVersion)
45142
46- def apply [F [_]](
143+ /** Creates a [[BidirectionalMcpClient ]] over the given [[chimp.client.transport.BidirectionalTransport ]] and performs the initialization
144+ * handshake. The optional handlers determine which client capabilities (roots, sampling, elicitation) are advertised to the server; only
145+ * capabilities backed by a handler are enabled.
146+ *
147+ * @param transport
148+ * The bidirectional transport carrying JSON-RPC messages in both directions.
149+ * @param clientInfo
150+ * Implementation name and version advertised to the server during initialization.
151+ * @param rootsHandler
152+ * Optional handler invoked when the server requests the client's roots; enables the `roots` capability when provided.
153+ * @param samplingHandler
154+ * Optional handler invoked when the server requests an LLM completion via sampling; enables the `sampling` capability when provided.
155+ * @param elicitationHandler
156+ * Optional handler invoked when the server requests user input via elicitation; enables the `elicitation` capability when provided.
157+ * @param protocolVersion
158+ * Protocol version proposed during initialization; defaults to the latest version supported by chimp.
159+ */
160+ def bidirectional [F [_]](
47161 transport : BidirectionalTransport [F ],
48162 clientInfo : Implementation ,
49163 rootsHandler : Option [() => F [ListRootsResult ]] = None ,
0 commit comments