KiY dZddlmZddlZddlmZddlmZddlm Z m Z ddl m Z ddl mZmZdd lmZdd lmZmZdd lmZdd lmZdd lmZmZmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z-m.Z.m/Z/m0Z0GddZ1y)z ServerTaskContext - Server-integrated task context with elicitation and sampling. This wraps the pure TaskContext and adds server-specific functionality: - Elicitation (task.elicit()) - Sampling (task.create_message()) - Status notifications )AnyN)TaskResultHandler) ServerSession)validate_sampling_tools!validate_tool_use_result_messages)McpError)"require_task_augmented_elicitationrequire_task_augmented_sampling) TaskContext) QueuedMessageTaskMessageQueue)Resolver) TaskStore)INVALID_REQUESTTASK_STATUS_INPUT_REQUIREDTASK_STATUS_WORKINGClientCapabilitiesCreateMessageResultCreateTaskResultElicitationCapabilityElicitRequestedSchema ElicitResult ErrorDataIncludeContextModelPreferences RequestIdResultSamplingCapabilitySamplingMessageServerNotificationTask TaskMetadataTaskStatusNotificationTaskStatusNotificationParamsTool ToolChoicec`eZdZdZdddedededededzf d Z e d e fd Z e d efd Z e d efd Zd2dZddde ded dfdZdddeded dfdZddde ded dfdZd2dZd2dZd2dZde ded efdZde de de d efdZddddddddd d!eed"ed#e dzd$edzd%e dzd&ee dzd'e!e e"fdzd(e#dzd)ee$dzd*e%dzd e&fd+Z'd,d-de ded.ed efd/Z(d,ddddddddd0 d!eed"ed.ed#e dzd$edzd%e dzd&ee dzd'e!e e"fdzd(e#dzd)ee$dzd*e%dzd e&fd1Z)y)3ServerTaskContextaE Server-integrated task context with elicitation and sampling. This wraps a pure TaskContext and adds server-specific functionality: - elicit() for sending elicitation requests to the client - create_message() for sampling requests - Status notifications via the session Example: async def my_task_work(task: ServerTaskContext) -> CallToolResult: await task.update_status("Starting...") result = await task.elicit( message="Continue?", requestedSchema={"type": "object", "properties": {"ok": {"type": "boolean"}}} ) if result.content.get("ok"): return CallToolResult(content=[TextContent(text="Done!")]) else: return CallToolResult(content=[TextContent(text="Cancelled")]) N)handlertaskstoresessionqueuer)c`t|||_||_||_||_||_y)aH Create a ServerTaskContext. Args: task: The Task object store: The task store session: The server session queue: The message queue for elicitation/sampling handler: The result handler for response routing (required for elicit/create_message) )r*r+N)r _ctx_session_queue_handler_store)selfr*r+r,r-r)s p/home/jay/workspace/scripts/.codegraph-venv/lib/python3.12/site-packages/mcp/server/experimental/task_context.py__init__zServerTaskContext.__init__Ms.& T7     returnc.|jjS)zThe task identifier.)r/task_idr4s r5r:zServerTaskContext.task_idhsyy   r7c.|jjS)zThe current task state.)r/r*r;s r5r*zServerTaskContext.taskmsyy~~r7c.|jjS)z(Whether cancellation has been requested.)r/ is_cancelledr;s r5r>zServerTaskContext.is_cancelledrsyy%%%r7c8|jjy)z"Request cancellation of this task.N)r/request_cancellationr;s r5r@z&ServerTaskContext.request_cancellationws &&(r7T)notifymessagerAcK|jj|d{|r|jd{yy7 7w)z Update the task's status message. Args: message: The new status message notify: Whether to send a notification to the client N)r/ update_status_send_notification)r4rBrAs r5rDzServerTaskContext.update_status}sCii%%g... ))+ + +  / +AAAAAAresultcK|jj|d{|r|jd{yy7 7w)z Mark the task as completed with the given result. Args: result: The task result notify: Whether to send a notification to the client N)r/completerE)r4rGrAs r5rIzServerTaskContext.completesCii  ((( ))+ + +  ) +rFerrorcK|jj|d{|r|jd{yy7 7w)z Mark the task as failed with an error message. Args: error: The error message notify: Whether to send a notification to the client N)r/failrE)r4rJrAs r5rLzServerTaskContext.failsAiinnU### ))+ + +  $ +rFcTK|jj}|jjt t t |j|j|j|j|j|j|jd{y7w)z.Send a task status notification to the client.)taskIdstatus statusMessage createdAt lastUpdatedAtttl pollInterval)paramsN)r/r*r0send_notificationr r#r$rNrOrPrQrRrSrT)r4r*s r5rEz$ServerTaskContext._send_notifications~yy~~mm-- &7#{{#{{&*&8&8"&..&*&8&8 HH%)%6%6     sBB( B&!B(c|jjttst t t dy)z)Check if the client supports elicitation.) elicitationz.Client does not support elicitation capabilitycoderBN)r0check_client_capabilityrrrrrr;s r5_check_elicitation_capabilityz/ServerTaskContext._check_elicitation_capabilitys?}}445GTiTk5lm(L nr7c|jjttst t t dy)z&Check if the client supports sampling.)samplingz+Client does not support sampling capabilityrYN)r0r[rrrrrr;s r5_check_sampling_capabilityz,ServerTaskContext._check_sampling_capabilitys?}}445GQcQe5fg(I hr7requestedSchemacXK|j|j td|jj |j t d{|jj|||j }|j}t}||jj|<td|||}|jj|j |d{ |jd{}|jj |j t d{t#j$|S77g7P7#t'j($r6|jj |j t d{7wxYww)a Send an elicitation request via the task message queue. This method: 1. Checks client capability 2. Updates task status to "input_required" 3. Queues the elicitation request 4. Waits for the response (delivered via tasks/result round-trip) 5. Updates task status back to "working" 6. Returns the result Args: message: The message to present to the user requestedSchema: Schema defining the expected response structure Returns: The client's response Raises: McpError: If client doesn't support elicitation capability NzEhandler is required for elicit(). Pass handler= to ServerTaskContext.rO)rBr`related_task_idrequesttyperBresolveroriginal_request_id)r\r2 RuntimeErrorr3 update_taskr:rr0_build_elicit_form_requestidr_pending_requestsr r1enqueuewaitrrmodel_validateanyioget_cancelled_exc_class)r4rBr`rd request_idrgqueued response_datas r5elicitzServerTaskContext.elicitsl4 **, == fg gkk%%dll;U%VVV--::+ LL;  !( -5Z6> '' 3 *   kk!!$,,777 "*--/1M++))$,,?R)S S S..}= =3 W& 82 S,,. ++))$,,?R)S S S   snAF*EBF*,E-F*2EE2E8E9EF*F*EEAF'F" F''F*urlelicitation_idcZK|j|j td|jj |j t d{|jj||||j }|j}t}||jj|<td|||}|jj|j |d{ |jd{}|jj |j t d{t#j$|S77g7P7#t'j($r6|jj |j t d{7wxYww)a Send a URL mode elicitation request via the task message queue. This directs the user to an external URL for out-of-band interactions like OAuth flows, credential collection, or payment processing. This method: 1. Checks client capability 2. Updates task status to "input_required" 3. Queues the elicitation request 4. Waits for the response (delivered via tasks/result round-trip) 5. Updates task status back to "working" 6. Returns the result Args: message: Human-readable explanation of why the interaction is needed url: The URL the user should navigate to elicitation_id: Unique identifier for tracking this elicitation Returns: The client's response indicating acceptance, decline, or cancellation Raises: McpError: If client doesn't support elicitation capability RuntimeError: If handler is not configured NzIhandler is required for elicit_url(). Pass handler= to ServerTaskContext.rb)rBrwrxrcrdre)r\r2rir3rjr:rr0_build_elicit_url_requestrlrrmr r1rnrorrrprqrr) r4rBrwrxrdrsrgrtrus r5 elicit_urlzServerTaskContext.elicit_url sn@ **, == jk kkk%%dll;U%VVV--99) LL :  !( -5Z6> '' 3 *   kk!!$,,777 "*--/1M++))$,,?R)S S S..}= =5 W( 82 S,,. ++))$,,?R)S S S  snAF+EBF+-E.F+3EE2E9E:EF+F+EEAF( F#!F((F+) system_promptinclude_context temperaturestop_sequencesmetadatamodel_preferencestools tool_choicemessages max_tokensr|r}r~rrrrrc K|j|jjr |jjjnd} t | | | t ||j td|jj|jtd{|jj||||||||| | |j } | j} t}||j j| <t!d| || }|j"j%|j|d{ |j'd{}|jj|jt(d{t+j,|S77h7Q7 #t/j0$r6|jj|jt(d{7wxYww)a Send a sampling request via the task message queue. This method: 1. Checks client capability 2. Updates task status to "input_required" 3. Queues the sampling request 4. Waits for the response (delivered via tasks/result round-trip) 5. Updates task status back to "working" 6. Returns the result Args: messages: The conversation messages for sampling max_tokens: Maximum tokens in the response system_prompt: Optional system prompt include_context: Context inclusion strategy temperature: Sampling temperature stop_sequences: Stop sequences metadata: Additional metadata model_preferences: Model selection preferences tools: Optional list of tools the LLM can use during sampling tool_choice: Optional control over tool usage behavior Returns: The sampling result from the client Raises: McpError: If client doesn't support sampling capability or tools ValueError: If tool_use or tool_result message structure is invalid NzMhandler is required for create_message(). Pass handler= to ServerTaskContext.rb) rrr|r}r~rrrrrrcrdre)r_r0 client_params capabilitiesrrr2rir3rjr:r_build_create_message_requestrlrrmr r1rnrorrrprqrr)r4rrr|r}r~rrrrr client_capsrdrsrgrtrus r5create_messagez ServerTaskContext.create_messagePsX '')BF--B]B]dmm11>>cg  UK@)(3 == no okk%%dll;U%VVV--==!'+#)/# LL>  !( -5Z6> '' 3 *   kk!!$,,777 "*--/1M++))$,,?R)S S S&55mD DC W6 82 S,,. ++))$,,?R)S S S   snB&H(F*)BHF-H F3F/2F3F1F3)H-H/F31F33AH8G;9HHi`rSrScK|jjr |jjjnd}t||j t d|j j|jtd{|jj|||jt|}|j}t}||jj|<td|||}|j j#|j|d{ |j%d{} t'j(| } | j*j,} |jj.j1| 23d{} 77z7c7 6|jj.j3| t4d{7} |j j|jt6d{7| S#t9j:$r6|j j|jt6d{7wxYww)aJ Send a task-augmented elicitation via the queue, then poll client. This is for use inside a task-augmented tool call when you want the client to handle the elicitation as its own task. The elicitation request is queued and delivered when the client calls tasks/result. After the client responds with CreateTaskResult, we poll the client's task until complete. Args: message: The message to present to the user requestedSchema: Schema defining the expected response structure ttl: Task time-to-live in milliseconds for the client's task Returns: The client's elicitation response Raises: McpError: If client doesn't support task-augmented elicitation RuntimeError: If handler is not configured Nz(handler is required for elicit_as_task()rbr)rBr`rcr*rdre)r0rrr r2rir3rjr:rrkr"rlrrmr r1rnrorrpr*rN experimental poll_taskget_task_resultrrrqrr)r4rBr`rSrrdrsrgrtru create_resultclient_task_id_rGs r5elicit_as_taskz ServerTaskContext.elicit_as_tasks6CG--B]B]dmm11>>cg *;7 == IJ Jkk%%dll;U%VVV--::+ LL#& ;  !( -5Z6> '' 3 *   kk!!$,,777 "*--/1M,;;MJM*//66N ==55??O  a; W& 82  O ==55EEF ++))$,,?R)S S SM,,. ++))$,,?R)S S S  sB I% F" BI%*F%+I%0HF'AHF+F)F+ H"I%%I%'H)F++.HG3H HHI%AI"II""I%) rSr|r}r~rrrrrc K|jjr |jjjnd} t| t | | | t ||j td|jj|jtd{|jj|||||||| | | |jt| } | j}t}||j j |<t#d| ||}|j$j'|j|d{ |j)d{}t+j,|}|j.j0}|jj2j5|23d{} 77z7c7 6|jj2j7|t8d{7}|jj|jt:d{7|S#t=j>$r6|jj|jt:d{7wxYww)a< Send a task-augmented sampling request via the queue, then poll client. This is for use inside a task-augmented tool call when you want the client to handle the sampling as its own task. The request is queued and delivered when the client calls tasks/result. After the client responds with CreateTaskResult, we poll the client's task until complete. Args: messages: The conversation messages for sampling max_tokens: Maximum tokens in the response ttl: Task time-to-live in milliseconds for the client's task system_prompt: Optional system prompt include_context: Context inclusion strategy temperature: Sampling temperature stop_sequences: Stop sequences metadata: Additional metadata model_preferences: Model selection preferences tools: Optional list of tools the LLM can use during sampling tool_choice: Optional control over tool usage behavior Returns: The sampling result from the client Raises: McpError: If client doesn't support task-augmented sampling or tools ValueError: If tool_use or tool_result message structure is invalid RuntimeError: If handler is not configured Nz0handler is required for create_message_as_task()rbr) rrr|r}r~rrrrrrcr*rdre) r0rrr rrr2rir3rjr:rrr"rlrrmr r1rnrorrpr*rNrrrrrrqrr)r4rrrSr|r}r~rrrrrrrdrsrgrtrurrrrGs r5create_message_as_taskz(ServerTaskContext.create_message_as_tasks4XCG--B]B]dmm11>>cg ' 4 UK@)(3 == QR Rkk%%dll;U%VVV--==!'+#)/# LL#&>  !( -5Z6> '' 3 *   kk!!$,,777 "*--/1M,;;MJM*//66N ==55??O  aM W8 82  O ==55EE#F ++))$,,?R)S S SM,,. ++))$,,?R)S S S  sB!J#G$B&J G JH5#G$AH58G <G =G H5JJH5 G  .H59G<:3H5-H0.H54J5AJ:I=;JJ)r8N)*__name__ __module__ __qualname____doc__r!rrr rr6propertystrr:r*boolr>r@rDrrIrLrEr\r_rrrvr{listrintrfloatdictrrr%r&rrrrr7r5r(r(5sJ<-1     #T)6!!!d&d&&) CG ,3 ,4 ,4 ,@D ,V , , ,8< , , , , *??/?  ?BCCC C  CT%)15$(+/*.59#')-\'\ \ Tz \ ($. \T\\S D(\sCx.4'\,d2\DzD \ $&\ \F LL/L  L  Lf$(15$(+/*.59#')-h'h h  h Tz h($.hT\hS D(hsCx.4'h,d2hDzD h $&h hr7r()2rtypingrrq+mcp.server.experimental.task_result_handlerrmcp.server.sessionrmcp.server.validationrrmcp.shared.exceptionsr*mcp.shared.experimental.tasks.capabilitiesr r %mcp.shared.experimental.tasks.contextr +mcp.shared.experimental.tasks.message_queuer r &mcp.shared.experimental.tasks.resolverr#mcp.shared.experimental.tasks.storer mcp.typesrrrrrrrrrrrrrrrrr r!r"r#r$r%r&r(rr7r5rs` I,\*>W;96oor7