Effect's McpServer service: what a server offers and its
notifications (see pyfect.ai.mcp_server).
Attributes#
| Attribute | Type | Description |
|---|---|---|
skills | = SkillCatalog() | |
global_middleware | list[AnyMiddlewareFn] = [] | The middleware of every request ( |
tools | tuple[ToolEntry, ...] | Every registered tool, in registration order, hidden or not. |
resources | tuple[ResourceEntry, ...] | Every registered resource (skill files included), in registration order, hidden or not. |
resource_templates | tuple[ResourceTemplateEntry, ...] | Every registered resource template, in registration order, hidden or not. |
prompts | tuple[PromptEntry, ...] | Every registered prompt, in registration order, hidden or not. |
has_registrations | Presence | Whether there are tools, resources (or templates) and prompts. |
list_change_revision | int | The newest list change's; a new listener ignores it and older ones. |
subscribe_events | Effect[Subscription[Event], Never, Scope] | A listener's feed of what subscriptions carry, for its scope. |
Functions#
__init__#
__init__() -> Nonedef __init__(self) -> None:
self._tools: dict[str, ToolEntry] = {}
self._resources: dict[str, ResourceEntry] = {}
self._templates: dict[str, ResourceTemplateEntry] = {}
self._prompts: dict[str, PromptEntry] = {}
self.skills = SkillCatalog()
self._completions: dict[str, _Completion] = {}
self._invokes: dict[tuple[str, str], Invoke] = {}
self.global_middleware: list[AnyMiddlewareFn] = []
"""The middleware of every request (``Middleware.layer_global``)."""
self._peers: dict[int, Peer] = {}
self._ids = itertools.count(1)
self._events = PubSub[Event](Atomic(None, None), "dropping")
self._list_change_revision = 0
self._pending_changes: dict[str, _PendingChange] = {}add_tool#
add_tool(entry) -> Effect[None]Add (or replace, by name) a tool.
| Parameter | Type | Description |
|---|---|---|
entry | ToolEntry |
Returns Effect[None]
def add_tool(self, entry: ToolEntry) -> Effect[None]:
"""Add (or replace, by name) a tool."""
name = entry.tool["name"]
def add() -> None:
self._tools[name] = entry
self._invoke("tool", name, entry.services)
return sync(add).and_then(self.notify("notifications/tools/list_changed"))add_resource#
add_resource(entry) -> Effect[None]Add (or replace, by URI) a resource. A file of a registered skill is not replaced: that is a defect.
| Parameter | Type | Description |
|---|---|---|
entry | ResourceEntry |
Returns Effect[None]
def add_resource(self, entry: ResourceEntry) -> Effect[None]:
"""Add (or replace, by URI) a resource. A file of a registered skill
is not replaced: that is a defect."""
return self._add_resource(entry, skill_file=False)add_skill#
add_skill(registration, files) -> Effect[None, IllegalArgumentError]Register a skill: claim its files, then serve them as resources.
| Parameter | Type | Description |
|---|---|---|
registration | SkillRegistration | |
files | Sequence[ResourceEntry] |
Returns Effect[None, IllegalArgumentError]
def add_skill(
self, registration: SkillRegistration, files: Sequence[ResourceEntry]
) -> Effect[None, IllegalArgumentError]:
"""Register a skill: claim its files, then serve them as resources."""
def claim() -> Effect[None, IllegalArgumentError]:
refused = self.skills.register(registration, self._resources)
return succeed(None) if refused is None else fail(refused)
@gen
def run():
yield from suspend(claim)
for entry in files:
yield from self._add_resource(entry, skill_file=True)
return runadd_resource_template#
add_resource_template(entry) -> Effect[None]Add (or replace, by URI template) a resource template and its completions.
| Parameter | Type | Description |
|---|---|---|
entry | ResourceTemplateEntry |
Returns Effect[None]
def add_resource_template(self, entry: ResourceTemplateEntry) -> Effect[None]:
"""Add (or replace, by URI template) a resource template and its
completions."""
uri_template = entry.template["uriTemplate"]
def add() -> None:
self._templates[uri_template] = entry
invoke = self._invoke("template", uri_template, entry.services)
for name, handler in entry.completions.items():
key = f"resource/{uri_template}/{name}"
self._completions[key] = _Completion(handler, invoke, uri_template)
return sync(add).and_then(self.notify("notifications/resources/list_changed"))add_prompt#
add_prompt(entry) -> Effect[None]Add (or replace, by name) a prompt and its completions.
| Parameter | Type | Description |
|---|---|---|
entry | PromptEntry |
Returns Effect[None]
def add_prompt(self, entry: PromptEntry) -> Effect[None]:
"""Add (or replace, by name) a prompt and its completions."""
name = entry.prompt["name"]
def add() -> None:
self._prompts[name] = entry
invoke = self._invoke("prompt", name, entry.services)
for argument, handler in entry.completions.items():
self._completions[f"prompt/{name}/{argument}"] = _Completion(handler, invoke, name)
return sync(add).and_then(self.notify("notifications/prompts/list_changed"))list_tools#
list_tools(context) -> Effect[list[Tool], RequestRejected, McpRequestContext]The tools a tools/list request from context sees: those
EnabledWhen enables for its client and no visibility middleware
hides, in order. Fails with RequestRejected when middleware
rejects the list.
| Parameter | Type | Description |
|---|---|---|
context | RequestContext |
Returns Effect[list[Tool], RequestRejected, McpRequestContext]
def list_tools(
self, context: RequestContext
) -> Effect[list[Tool], RequestRejected, McpRequestContext]:
"""The tools a ``tools/list`` request from ``context`` sees: those
``EnabledWhen`` enables for its client and no visibility middleware
hides, in order. Fails with ``RequestRejected`` when middleware
rejects the list."""
return self._listed("tools/list", "tool", self._tools, lambda e: e.tool, context)list_resources#
list_resources(context) -> Effect[list[Resource], RequestRejected, McpRequestContext]The resources a resources/list request from context sees,
filtered and failing as in list_tools.
| Parameter | Type | Description |
|---|---|---|
context | RequestContext |
Returns Effect[list[Resource], RequestRejected, McpRequestContext]
def list_resources(
self, context: RequestContext
) -> Effect[list[Resource], RequestRejected, McpRequestContext]:
"""The resources a ``resources/list`` request from ``context`` sees,
filtered and failing as in ``list_tools``."""
return self._listed(
"resources/list", "resource", self._resources, lambda e: e.resource, context
)list_resource_templates#
list_resource_templates(context) -> Effect[list[ResourceTemplate], RequestRejected, McpRequestContext]The resource templates a resources/templates/list request from
context sees, filtered and failing as in list_tools.
| Parameter | Type | Description |
|---|---|---|
context | RequestContext |
Returns Effect[list[ResourceTemplate], RequestRejected, McpRequestContext]
def list_resource_templates(
self, context: RequestContext
) -> Effect[list[ResourceTemplate], RequestRejected, McpRequestContext]:
"""The resource templates a ``resources/templates/list`` request from
``context`` sees, filtered and failing as in ``list_tools``."""
return self._listed(
"resources/templates/list", "template", self._templates, lambda e: e.template, context
)list_prompts#
list_prompts(context) -> Effect[list[Prompt], RequestRejected, McpRequestContext]The prompts a prompts/list request from context sees,
filtered and failing as in list_tools.
| Parameter | Type | Description |
|---|---|---|
context | RequestContext |
Returns Effect[list[Prompt], RequestRejected, McpRequestContext]
def list_prompts(
self, context: RequestContext
) -> Effect[list[Prompt], RequestRejected, McpRequestContext]:
"""The prompts a ``prompts/list`` request from ``context`` sees,
filtered and failing as in ``list_tools``."""
return self._listed("prompts/list", "prompt", self._prompts, lambda e: e.prompt, context)find_tool#
find_tool(name, context) -> ToolEntry | NoneThe tool called name when EnabledWhen enables it for
context 's client, else None (visibility middleware is not
consulted).
| Parameter | Type | Description |
|---|---|---|
name | str | |
context | RequestContext |
Returns ToolEntry | None
def find_tool(self, name: str, context: RequestContext) -> ToolEntry | None:
"""The tool called ``name`` when ``EnabledWhen`` enables it for
``context`` 's client, else ``None`` (visibility middleware is not
consulted)."""
entry = self._tools.get(name)
return entry if entry is not None and _visible(entry.annotations, context) else Nonecall_tool_for#
call_tool_for(params, context, *, before_handle=lambda _: _VOID) -> Effect[CallToolResult | InputRequired, McpError | RequestRejected, RequestServices]The outcome of params 's call; an unknown tool is invalid
params, a hidden one rejected as unknown. before_handle runs once
the request's visibility accepted the tool, before its handler.
| Parameter | Type | Description |
|---|---|---|
params | CallToolParams | |
context | RequestContext | |
before_handle | Callable[[Tool], Effect[None, McpError]] = lambda _: _VOID |
Returns Effect[CallToolResult | InputRequired, McpError | RequestRejected, RequestServices]
def call_tool_for(
self,
params: CallToolParams,
context: RequestContext,
*,
before_handle: Callable[[Tool], Effect[None, McpError]] = lambda _: _VOID,
) -> Effect[
CallToolResult | InputRequired,
McpError | RequestRejected,
RequestServices,
]:
"""The outcome of ``params`` 's call; an unknown tool is invalid
params, a hidden one rejected as unknown. ``before_handle`` runs once
the request's visibility accepted the tool, before its handler."""
name = params["name"]
entry = self.find_tool(name, context)
if entry is None:
return fail(InvalidParams(f"Tool '{name}' not found"))
return self._invokes["tool", name](
suspend(lambda: before_handle(entry.tool)).and_then(
suspend(lambda: entry.handle(params.get("arguments")))
),
method="tools/call",
target=name,
payload=params,
hidden=RequestRejected(InvalidParams(f"Tool '{name}' not found")),
)read_resource_for#
read_resource_for(uri, context) -> Effect[ReadResourceResult, McpError | RequestRejected | ResourceNotFound, RequestServices]The read of uri: ResourceNotFound when nothing serves it,
or a visibility hides what does (a hidden resource does not fall
through to a template).
| Parameter | Type | Description |
|---|---|---|
uri | str | |
context | RequestContext |
Returns Effect[ReadResourceResult, McpError | RequestRejected | ResourceNotFound, RequestServices]
def read_resource_for(
self, uri: str, context: RequestContext
) -> Effect[ReadResourceResult, McpError | RequestRejected | ResourceNotFound, RequestServices]:
"""The read of ``uri``: ``ResourceNotFound`` when nothing serves it,
or a visibility hides what does (a hidden resource does not fall
through to a template)."""
entry = self._resources.get(uri)
if entry is not None and _visible(entry.annotations, context):
return self._invokes["resource", uri](
entry.handle,
method="resources/read",
target=uri,
payload={"uri": uri},
hidden=ResourceNotFound(uri),
)
for key, template in self._templates.items():
params = template.match(uri)
if params is not None and _visible(template.annotations, context):
return self._invokes["template", key](
suspend(lambda template=template, params=params: template.handle(uri, params)),
method="resources/read",
target=uri,
payload={"uri": uri},
hidden=ResourceNotFound(uri),
)
return fail(ResourceNotFound(uri))get_prompt_for#
get_prompt_for(name, arguments, context) -> Effect[GetPromptResult | InputRequired, McpError | RequestRejected, RequestServices]The prompt name filled with arguments for context, or
an InputRequired asking the client for more. An unknown, disabled
or hidden prompt fails with InvalidParams; a handler fails with
its McpError, rejecting middleware with RequestRejected.
| Parameter | Type | Description |
|---|---|---|
name | str | |
arguments | Mapping[str, str] | |
context | RequestContext |
Returns Effect[GetPromptResult | InputRequired, McpError | RequestRejected, RequestServices]
def get_prompt_for(
self, name: str, arguments: Mapping[str, str], context: RequestContext
) -> Effect[GetPromptResult | InputRequired, McpError | RequestRejected, RequestServices]:
"""The prompt ``name`` filled with ``arguments`` for ``context``, or
an ``InputRequired`` asking the client for more. An unknown, disabled
or hidden prompt fails with ``InvalidParams``; a handler fails with
its ``McpError``, rejecting middleware with ``RequestRejected``."""
entry = self._prompts.get(name)
not_found = InvalidParams(f"Prompt '{name}' not found")
if entry is None or not _visible(entry.annotations, context):
return fail(not_found)
return self._invokes["prompt", name](
suspend(lambda: entry.handle(arguments)),
method="prompts/get",
target=name,
payload={"name": name, "arguments": dict(arguments)},
hidden=not_found,
)skills_for#
skills_for(method, params, context) -> Effect[JsonObject, McpError, McpRequestContext]Answer one of the Skills extension's methods.
| Parameter | Type | Description |
|---|---|---|
method | str | |
params | JsonObject | |
context | RequestContext |
Returns Effect[JsonObject, McpError, McpRequestContext]
def skills_for(
self, method: str, params: JsonObject, context: RequestContext
) -> Effect[JsonObject, McpError, McpRequestContext]:
"""Answer one of the Skills extension's methods."""
return unwrap_rejected(
skills.serve(
self.skills, method, params, lambda annotations: _visible(annotations, context)
)
)complete_for#
complete_for(params) -> Effect[CompleteResult, InvalidParams | InternalError | RequestRejected, RequestServices]The completions of params 's prompt or template argument, at
most 100 (hasMore set when cut). An unknown reference or
argument, or a hidden one, fails with InvalidParams; a failing
handler with its InternalError, rejecting middleware with
RequestRejected.
| Parameter | Type | Description |
|---|---|---|
params | CompleteParams |
Returns Effect[CompleteResult, InvalidParams | InternalError | RequestRejected, RequestServices]
def complete_for(
self, params: CompleteParams
) -> Effect[CompleteResult, InvalidParams | InternalError | RequestRejected, RequestServices]:
"""The completions of ``params`` 's prompt or template argument, at
most 100 (``hasMore`` set when cut). An unknown reference or
argument, or a hidden one, fails with ``InvalidParams``; a failing
handler with its ``InternalError``, rejecting middleware with
``RequestRejected``."""
ref = params["ref"]
argument = params["argument"]
key = (
f"prompt/{ref['name']}/{argument['name']}"
if ref["type"] == "ref/prompt"
else f"resource/{ref['uri']}/{argument['name']}"
)
unknown = InvalidParams("Unknown completion reference or argument")
found = self._completions.get(key)
if found is None:
return fail(unknown)
context = params.get("context") or {}
completed = found.invoke(
suspend(lambda: found.handler(argument["value"], context)),
method="completion/complete",
target=found.target,
payload=params,
hidden=unknown,
)
return completed.map(_at_most_100)call_tool#
call_tool(params) -> Effect[CallToolResult, McpError, McpServerClient]Call a tool for the current session. Middleware rejecting it fails with its MCP error.
| Parameter | Type | Description |
|---|---|---|
params | CallToolParams |
Returns Effect[CallToolResult, McpError, McpServerClient]
def call_tool(
self, params: CallToolParams
) -> Effect[CallToolResult, McpError, McpServerClient]:
"""Call a tool for the current session. Middleware rejecting it
fails with its MCP error."""
return _with_request(
lambda context: unwrap_rejected(self.call_tool_for(params, context))
).flat_map(_complete)find_resource#
find_resource(uri) -> Effect[ReadResourceResult, McpError, McpServerClient]Read a resource for the current session.
| Parameter | Type | Description |
|---|---|---|
uri | str |
Returns Effect[ReadResourceResult, McpError, McpServerClient]
def find_resource(self, uri: str) -> Effect[ReadResourceResult, McpError, McpServerClient]:
"""Read a resource for the current session."""
def not_found(error: ResourceNotFound) -> Effect[Never, InvalidParams]:
return fail(InvalidParams(f"Resource '{error.uri}' not found"))
def read(context: RequestContext) -> Effect[ReadResourceResult, McpError, RequestServices]:
found = self.read_resource_for(uri, context).pipe(
catch_tag(ResourceNotFound, not_found)
)
return unwrap_rejected(found)
return _with_request(read)get_prompt_result#
get_prompt_result(name, arguments=None) -> Effect[GetPromptResult, McpError, McpServerClient]Get a prompt for the current session.
| Parameter | Type | Description |
|---|---|---|
name | str | |
arguments | Mapping[str, str] | None = None |
Returns Effect[GetPromptResult, McpError, McpServerClient]
def get_prompt_result(
self, name: str, arguments: Mapping[str, str] | None = None
) -> Effect[GetPromptResult, McpError, McpServerClient]:
"""Get a prompt for the current session."""
return _with_request(
lambda context: unwrap_rejected(self.get_prompt_for(name, arguments or {}, context))
).flat_map(_complete)completion#
completion(params) -> Effect[CompleteResult, McpError, McpServerClient]Complete an argument for the current session.
| Parameter | Type | Description |
|---|---|---|
params | CompleteParams |
Returns Effect[CompleteResult, McpError, McpServerClient]
def completion(
self, params: CompleteParams
) -> Effect[CompleteResult, McpError, McpServerClient]:
"""Complete an argument for the current session."""
return _with_request(lambda _: unwrap_rejected(self.complete_for(params)))connect#
connect(peer) -> NoneRegister a transport's connected client, so notifications reach
it (replacing one with its client_id).
| Parameter | Type | Description |
|---|---|---|
peer | Peer |
def connect(self, peer: Peer) -> None:
"""Register a transport's connected client, so notifications reach
it (replacing one with its ``client_id``)."""
self._peers[peer.client_id] = peernext_client_id#
next_client_id() -> intA new client id: 1, 2, 3, ... for this server.
Returns int
def next_client_id(self) -> int:
"""A new client id: 1, 2, 3, ... for this server."""
return next(self._ids)disconnect#
disconnect(client_id) -> NoneStop sending notifications to client client_id (a no-op when
it is not connected).
| Parameter | Type | Description |
|---|---|---|
client_id | int |
def disconnect(self, client_id: int) -> None:
"""Stop sending notifications to client ``client_id`` (a no-op when
it is not connected)."""
self._peers.pop(client_id, None)notify#
notify(method, params=None) -> Effect[None]Send a notification. A log message or progress sent while serving a request goes to that request's client. List changes of a kind made in one scheduling window go out once, after it. The others go to every connected client that wants them and every subscription that asked; a request waits for its own client's copy, so that it precedes the response.
| Parameter | Type | Description |
|---|---|---|
method | NotificationMethod | |
params | JsonObject | None = None |
Returns Effect[None]
def notify(self, method: NotificationMethod, params: JsonObject | None = None) -> Effect[None]:
"""Send a notification. A log message or progress sent while serving
a request goes to that request's client. List changes of a kind made
in one scheduling window go out once, after it. The others go to
every connected client that wants them and every subscription that
asked; a request waits for its own client's copy, so that it precedes
the response."""
body: JsonObject = {} if params is None else params
@gen
def run():
current = yield from service_option(RequestOutbound)
if method in _REQUEST_NOTIFICATIONS and current is not None:
yield from current.value(method, body)
return None
request = yield from service_option(McpRequestContext)
origin = None if request is None else request.value.client_id
if method in _LIST_CHANGES:
return (yield from self._list_changed(method, body, origin))
return (yield from self._publish(method, body, None, origin))
return runnotify_elicitation_complete#
notify_elicitation_complete(client_id, elicitation_id) -> Effect[None]Tell one client that its URL elicitation finished (a no-op when the client is gone).
| Parameter | Type | Description |
|---|---|---|
client_id | int | |
elicitation_id | str |
Returns Effect[None]
def notify_elicitation_complete(self, client_id: int, elicitation_id: str) -> Effect[None]:
"""Tell one client that its URL elicitation finished (a no-op when
the client is gone)."""
peer = self._peers.get(client_id)
if peer is None:
return _VOID
return peer.deliver("notifications/elicitation/complete", {"elicitationId": elicitation_id})On This Page
AttributesFunctions__init__add_tooladd_resourceadd_skilladd_resource_templateadd_promptlist_toolslist_resourceslist_resource_templateslist_promptsfind_toolcall_tool_forread_resource_forget_prompt_forskills_forcomplete_forcall_toolfind_resourceget_prompt_resultcompletionconnectnext_client_iddisconnectnotifynotify_elicitation_complete