cmcp_client.h File Reference

Asynchronous MCP client: handshake, list/call/read/subscribe, cancellation, progress, sampling, roots, elicitation. More...

#include "cmcp_types.h"
#include "cmcp_transport.h"
#include "cmcp_session.h"

Go to the source code of this file.

Data Structures
struct	cmcp_tool_result_t
struct	cmcp_tool_handle_t
struct	cmcp_root_t

Typedefs
typedef struct cmcp_client	cmcp_client_t
typedef void(*	cmcp_notification_fn) (const char *method, const cmcp_json_t *params, void *userdata)
typedef void(*	cmcp_progress_fn) (double progress, double total, const char *message, void *userdata)
typedef int(*	cmcp_sampling_handler_fn) (const cmcp_json_t *params, void *userdata, cmcp_json_t **out_result)
typedef int(*	cmcp_elicitation_handler_fn) (const cmcp_json_t *params, void *userdata, cmcp_json_t **out_result)

Enumerations
enum	cmcp_tool_outcome_t { CMCP_TOOL_OK = 0 , CMCP_TOOL_ERR_TOOL_LEVEL = 1 , CMCP_TOOL_ERR_PROTOCOL = 2 , CMCP_TOOL_ERR_CANCELLED = 3 }

Functions
void	cmcp_tool_result_clear (cmcp_tool_result_t *r)
cmcp_client_t *	cmcp_client_new (const char *name, const char *version)
void	cmcp_client_free (cmcp_client_t *c)
void	cmcp_client_set_capabilities (cmcp_client_t *c, const cmcp_client_capabilities_t *caps)
int	cmcp_client_set_description (cmcp_client_t *c, const char *description)
void	cmcp_client_set_notification_handler (cmcp_client_t *c, cmcp_notification_fn fn, void *userdata)
int	cmcp_client_handshake (cmcp_client_t *c, cmcp_transport_t *t)
int	cmcp_client_connect_stdio (cmcp_client_t *c, const char *path, char *const argv[], char *const envp[])
int	cmcp_client_call_async (cmcp_client_t *c, const char *method, cmcp_json_t *params, long long *out_id)
int	cmcp_client_wait (cmcp_client_t *c, long long id, cmcp_rpc_message_t *out_response)
int	cmcp_client_request (cmcp_client_t *c, const char *method, cmcp_json_t *params, cmcp_rpc_message_t *out_response)
int	cmcp_client_notify (cmcp_client_t *c, const char *method, cmcp_json_t *params)
int	cmcp_client_cancel (cmcp_client_t *c, long long id, const char *reason)
int	cmcp_client_call_async_progress (cmcp_client_t *c, const char *method, cmcp_json_t *params, cmcp_progress_fn fn, void *userdata, long long *out_id)
int	cmcp_client_tools_list (cmcp_client_t *c, cmcp_session_tool_t **out_tools, size_t *out_n)
int	cmcp_client_resources_list (cmcp_client_t *c, cmcp_session_resource_t **out_resources, size_t *out_n)
int	cmcp_client_prompts_list (cmcp_client_t *c, cmcp_session_prompt_t **out_prompts, size_t *out_n)
int	cmcp_client_resource_read (cmcp_client_t *c, const char *uri, char **out_text, size_t *out_n)
int	cmcp_client_prompt_get (cmcp_client_t *c, const char *name, cmcp_json_t *args, cmcp_json_t **out_messages)
cmcp_tool_result_t	cmcp_client_tool_call (cmcp_client_t *c, const char *name, cmcp_json_t *args)
cmcp_tool_handle_t	cmcp_client_tool_call_async (cmcp_client_t *c, const char *name, cmcp_json_t *args)
cmcp_tool_result_t	cmcp_client_tool_wait (cmcp_tool_handle_t h)
int	cmcp_client_tool_call_text (cmcp_client_t *c, const char *name, cmcp_json_t *args, char **out_text, cmcp_rpc_error_t **out_rpc_err)
void	cmcp_client_set_sampling_handler (cmcp_client_t *c, cmcp_sampling_handler_fn fn, void *userdata)
cmcp_json_t *	cmcp_sampling_text_result (const char *text, const char *model, const char *stop_reason)
void	cmcp_client_set_elicitation_handler (cmcp_client_t *c, cmcp_elicitation_handler_fn fn, void *userdata)
cmcp_json_t *	cmcp_elicitation_result (const char *action, cmcp_json_t *content)
int	cmcp_client_set_roots (cmcp_client_t *c, const cmcp_root_t *roots, size_t n)
int	cmcp_client_notify_roots_changed (cmcp_client_t *c)
int	cmcp_client_set_log_level (cmcp_client_t *c, cmcp_log_level_t level)
const cmcp_server_capabilities_t *	cmcp_client_server_caps (const cmcp_client_t *c)
const char *	cmcp_client_server_name (const cmcp_client_t *c)
const char *	cmcp_client_server_version (const cmcp_client_t *c)
const char *	cmcp_client_server_description (const cmcp_client_t *c)
const char *	cmcp_client_server_protocol (const cmcp_client_t *c)

Detailed Description

Asynchronous MCP client: handshake, list/call/read/subscribe, cancellation, progress, sampling, roots, elicitation.

The client owns a transport and a reader thread that demultiplexes responses by id against an in-flight table. Every call is async at the wire level — cmcp_client_call_async returns immediately with a handle, and cmcp_client_wait blocks for completion; many calls can be in flight concurrently and they complete in any order. cmcp_client_request is sync sugar over the async pair.

Client-side handlers (notification routing, sampling, elicitation) run on the reader thread; from inside one, non-blocking calls are fine but the blocking pair (request/wait) deadlocks — see the "Thread-safety contract" section below for the full rules. cmcp_client_set_roots advertises filesystem scope to the server; cmcp_client_cancel issues a notifications/cancelled for an in-flight call.

For multi-server agents see cmcp_session.h, which aggregates several already-handshaken clients under a single primitive surface.

Definition in file cmcp_client.h.

Typedef Documentation

cmcp_client_t

typedef struct cmcp_client cmcp_client_t

Definition at line 31 of file cmcp_client.h.

cmcp_notification_fn

typedef void(* cmcp_notification_fn) (const char *method, const cmcp_json_t *params, void *userdata)

Definition at line 216 of file cmcp_client.h.

cmcp_progress_fn

typedef void(* cmcp_progress_fn) (double progress, double total, const char *message, void *userdata)

Definition at line 313 of file cmcp_client.h.

cmcp_sampling_handler_fn

typedef int(* cmcp_sampling_handler_fn) (const cmcp_json_t *params, void *userdata, cmcp_json_t **out_result)

Definition at line 508 of file cmcp_client.h.

cmcp_elicitation_handler_fn

typedef int(* cmcp_elicitation_handler_fn) (const cmcp_json_t *params, void *userdata, cmcp_json_t **out_result)

Definition at line 549 of file cmcp_client.h.

Enumeration Type Documentation

cmcp_tool_outcome_t

enum cmcp_tool_outcome_t

Enumerator
CMCP_TOOL_OK
CMCP_TOOL_ERR_TOOL_LEVEL
CMCP_TOOL_ERR_PROTOCOL
CMCP_TOOL_ERR_CANCELLED

Definition at line 50 of file cmcp_client.h.

Function Documentation

cmcp_tool_result_clear()

void cmcp_tool_result_clear

(

cmcp_tool_result_t *

r

)

cmcp_client_new()

cmcp_client_t * cmcp_client_new	(	const char *	name,
		const char *	version
	)

cmcp_client_free()

void cmcp_client_free

(

cmcp_client_t *

c

)

cmcp_client_set_capabilities()

void cmcp_client_set_capabilities	(	cmcp_client_t *	c,
		const cmcp_client_capabilities_t *	caps
	)

cmcp_client_set_description()

int cmcp_client_set_description	(	cmcp_client_t *	c,
		const char *	description
	)

cmcp_client_set_notification_handler()

void cmcp_client_set_notification_handler	(	cmcp_client_t *	c,
		cmcp_notification_fn	fn,
		void *	userdata
	)

cmcp_client_handshake()

int cmcp_client_handshake	(	cmcp_client_t *	c,
		cmcp_transport_t *	t
	)

cmcp_client_connect_stdio()

int cmcp_client_connect_stdio	(	cmcp_client_t *	c,
		const char *	path,
		char *const	argv[],
		char *const	envp[]
	)

cmcp_client_call_async()

int cmcp_client_call_async	(	cmcp_client_t *	c,
		const char *	method,
		cmcp_json_t *	params,
		long long *	out_id
	)

cmcp_client_wait()

int cmcp_client_wait	(	cmcp_client_t *	c,
		long long	id,
		cmcp_rpc_message_t *	out_response
	)

cmcp_client_request()

int cmcp_client_request	(	cmcp_client_t *	c,
		const char *	method,
		cmcp_json_t *	params,
		cmcp_rpc_message_t *	out_response
	)

cmcp_client_notify()

int cmcp_client_notify	(	cmcp_client_t *	c,
		const char *	method,
		cmcp_json_t *	params
	)

cmcp_client_cancel()

int cmcp_client_cancel	(	cmcp_client_t *	c,
		long long	id,
		const char *	reason
	)

cmcp_client_call_async_progress()

int cmcp_client_call_async_progress	(	cmcp_client_t *	c,
		const char *	method,
		cmcp_json_t *	params,
		cmcp_progress_fn	fn,
		void *	userdata,
		long long *	out_id
	)

cmcp_client_tools_list()

int cmcp_client_tools_list	(	cmcp_client_t *	c,
		cmcp_session_tool_t **	out_tools,
		size_t *	out_n
	)

cmcp_client_resources_list()

int cmcp_client_resources_list	(	cmcp_client_t *	c,
		cmcp_session_resource_t **	out_resources,
		size_t *	out_n
	)

cmcp_client_prompts_list()

int cmcp_client_prompts_list	(	cmcp_client_t *	c,
		cmcp_session_prompt_t **	out_prompts,
		size_t *	out_n
	)

cmcp_client_resource_read()

int cmcp_client_resource_read	(	cmcp_client_t *	c,
		const char *	uri,
		char **	out_text,
		size_t *	out_n
	)

cmcp_client_prompt_get()

int cmcp_client_prompt_get	(	cmcp_client_t *	c,
		const char *	name,
		cmcp_json_t *	args,
		cmcp_json_t **	out_messages
	)

cmcp_client_tool_call()

cmcp_tool_result_t cmcp_client_tool_call	(	cmcp_client_t *	c,
		const char *	name,
		cmcp_json_t *	args
	)

cmcp_client_tool_call_async()

cmcp_tool_handle_t cmcp_client_tool_call_async	(	cmcp_client_t *	c,
		const char *	name,
		cmcp_json_t *	args
	)

cmcp_client_tool_wait()

cmcp_tool_result_t cmcp_client_tool_wait

(

cmcp_tool_handle_t

h

)

cmcp_client_tool_call_text()

int cmcp_client_tool_call_text	(	cmcp_client_t *	c,
		const char *	name,
		cmcp_json_t *	args,
		char **	out_text,
		cmcp_rpc_error_t **	out_rpc_err
	)

cmcp_client_set_sampling_handler()

void cmcp_client_set_sampling_handler	(	cmcp_client_t *	c,
		cmcp_sampling_handler_fn	fn,
		void *	userdata
	)

cmcp_sampling_text_result()

cmcp_json_t * cmcp_sampling_text_result	(	const char *	text,
		const char *	model,
		const char *	stop_reason
	)

cmcp_client_set_elicitation_handler()

void cmcp_client_set_elicitation_handler	(	cmcp_client_t *	c,
		cmcp_elicitation_handler_fn	fn,
		void *	userdata
	)

cmcp_elicitation_result()

cmcp_json_t * cmcp_elicitation_result	(	const char *	action,
		cmcp_json_t *	content
	)

cmcp_client_set_roots()

int cmcp_client_set_roots	(	cmcp_client_t *	c,
		const cmcp_root_t *	roots,
		size_t	n
	)

cmcp_client_notify_roots_changed()

int cmcp_client_notify_roots_changed

(

cmcp_client_t *

c

)

cmcp_client_set_log_level()

int cmcp_client_set_log_level	(	cmcp_client_t *	c,
		cmcp_log_level_t	level
	)

cmcp_client_server_caps()

const cmcp_server_capabilities_t * cmcp_client_server_caps

(

const cmcp_client_t *

c

)

cmcp_client_server_name()

const char * cmcp_client_server_name

(

const cmcp_client_t *

c

)

cmcp_client_server_version()

const char * cmcp_client_server_version

(

const cmcp_client_t *

c

)

cmcp_client_server_description()

const char * cmcp_client_server_description

(

const cmcp_client_t *

c

)

cmcp_client_server_protocol()

const char * cmcp_client_server_protocol

(

const cmcp_client_t *

c

)