GitHub

McpServerService

API reference for McpServerService.

Effect's McpServer service: what a server offers and its notifications (see pyfect.ai.mcp_server).

Attributes

AttributeTypeDescription
skills= SkillCatalog()
global_middlewarelist[AnyMiddlewareFn] = []

The middleware of every request (Middleware.layer_global).

toolstuple[ToolEntry, ...]

Every registered tool, in registration order, hidden or not.

resourcestuple[ResourceEntry, ...]

Every registered resource (skill files included), in registration order, hidden or not.

resource_templatestuple[ResourceTemplateEntry, ...]

Every registered resource template, in registration order, hidden or not.

promptstuple[PromptEntry, ...]

Every registered prompt, in registration order, hidden or not.

has_registrationsPresence

Whether there are tools, resources (or templates) and prompts.

list_change_revisionint

The newest list change's; a new listener ignores it and older ones.

subscribe_eventsEffect[Subscription[Event], Never, Scope]

A listener's feed of what subscriptions carry, for its scope.

Functions

__init__

__init__() -> None
def __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.

ParameterTypeDescription
entryToolEntry

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.

ParameterTypeDescription
entryResourceEntry

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.

ParameterTypeDescription
registrationSkillRegistration
filesSequence[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 run

add_resource_template

add_resource_template(entry) -> Effect[None]

Add (or replace, by URI template) a resource template and its completions.

ParameterTypeDescription
entryResourceTemplateEntry

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.

ParameterTypeDescription
entryPromptEntry

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.

ParameterTypeDescription
contextRequestContext

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.

ParameterTypeDescription
contextRequestContext

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.

ParameterTypeDescription
contextRequestContext

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.

ParameterTypeDescription
contextRequestContext

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 | None

The tool called name when EnabledWhen enables it for context 's client, else None (visibility middleware is not consulted).

ParameterTypeDescription
namestr
contextRequestContext

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 None

call_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.

ParameterTypeDescription
paramsCallToolParams
contextRequestContext
before_handleCallable[[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).

ParameterTypeDescription
uristr
contextRequestContext

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.

ParameterTypeDescription
namestr
argumentsMapping[str, str]
contextRequestContext

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.

ParameterTypeDescription
methodstr
paramsJsonObject
contextRequestContext

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.

ParameterTypeDescription
paramsCompleteParams

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.

ParameterTypeDescription
paramsCallToolParams

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.

ParameterTypeDescription
uristr

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.

ParameterTypeDescription
namestr
argumentsMapping[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.

ParameterTypeDescription
paramsCompleteParams

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) -> None

Register a transport's connected client, so notifications reach it (replacing one with its client_id).

ParameterTypeDescription
peerPeer
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] = peer

next_client_id

next_client_id() -> int

A 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) -> None

Stop sending notifications to client client_id (a no-op when it is not connected).

ParameterTypeDescription
client_idint
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.

ParameterTypeDescription
methodNotificationMethod
paramsJsonObject | 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 run

notify_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).

ParameterTypeDescription
client_idint
elicitation_idstr

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})