Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

15.8 KB
Raw Blame
"""Server-side argument completion (`completion/complete`).

A FastMCP server answers completion requests through a single handler
registered with `@mcp.completion`. These tests cover both reference kinds
(prompt arguments and resource-template parameters), the capability
declaration, graceful handling of unrecognized references, and parity across
the handshake (`mode="legacy"`) and modern (`mode="auto"`) protocol eras.
"""

from __future__ import annotations

import threading
from typing import Any

import pytest
from mcp_types import (
    Completion,
    CompletionArgument,
    CompletionContext,
    PromptReference,
    ResourceTemplateReference,
)

from fastmcp import Client, FastMCP
from fastmcp.server.completions import normalize_completion

# Both protocol eras the connection may negotiate.
MODES = ["legacy", "auto"]


@pytest.fixture
def completion_server() -> FastMCP:
    """A server that completes a prompt argument and a template parameter."""
    mcp = FastMCP("completion-server")

    @mcp.prompt
    def poem(theme: str) -> str:
        return f"Write a poem about {theme}"

    @mcp.resource("data://item/{item_id}")
    def item(item_id: str) -> str:
        return f"item-{item_id}"

    @mcp.completion
    def complete(ref, argument, context):
        if isinstance(ref, PromptReference) and ref.name == "poem":
            if argument.name == "theme":
                options = ["nature", "love", "adventure"]
                return [o for o in options if o.startswith(argument.value)]
        if isinstance(ref, ResourceTemplateReference):
            if ref.uri == "data://item/{item_id}" and argument.name == "item_id":
                return ["1", "2", "3"]
        return None

    return mcp


@pytest.mark.parametrize("mode", MODES)
async def test_prompt_argument_completion_returns_candidates(completion_server, mode):
    async with Client(completion_server, mode=mode) as client:
        result = await client.complete(
            PromptReference(name="poem"),
            {"name": "theme", "value": "n"},
        )
    assert result.values == ["nature"]


@pytest.mark.parametrize("mode", MODES)
async def test_resource_template_completion_returns_candidates(completion_server, mode):
    ref = ResourceTemplateReference(uri="data://item/{item_id}")
    async with Client(completion_server, mode=mode) as client:
        result = await client.complete(ref, {"name": "item_id", "value": ""})
    assert result.values == ["1", "2", "3"]


@pytest.mark.parametrize("mode", MODES)
async def test_capability_declared_when_handler_registered(completion_server, mode):
    async with Client(completion_server, mode=mode) as client:
        capabilities = client.server_capabilities
    assert capabilities is not None
    assert capabilities.completions is not None


@pytest.mark.parametrize("mode", MODES)
async def test_capability_absent_without_handler(mode):
    mcp = FastMCP("no-completion")

    @mcp.prompt
    def poem(theme: str) -> str:
        return f"Write a poem about {theme}"

    async with Client(mcp, mode=mode) as client:
        capabilities = client.server_capabilities
    assert capabilities is not None
    assert capabilities.completions is None


@pytest.mark.parametrize("mode", MODES)
async def test_unregistered_ref_returns_empty_completion(completion_server, mode):
    async with Client(completion_server, mode=mode) as client:
        result = await client.complete(
            PromptReference(name="does-not-exist"),
            {"name": "theme", "value": "n"},
        )
    assert result.values == []


@pytest.mark.parametrize("mode", MODES)
async def test_unregistered_argument_returns_empty_completion(completion_server, mode):
    async with Client(completion_server, mode=mode) as client:
        result = await client.complete(
            PromptReference(name="poem"),
            {"name": "unknown_argument", "value": "x"},
        )
    assert result.values == []


@pytest.mark.parametrize("mode", MODES)
async def test_completion_context_reaches_handler(mode):
    """The already-supplied argument values arrive as the handler's context."""
    mcp = FastMCP("context-server")

    @mcp.prompt
    def compose(owner: str, repo: str) -> str:
        return f"{owner}/{repo}"

    seen: dict[str, str] = {}

    @mcp.completion
    def complete(ref, argument, context):
        if context is not None and context.arguments:
            seen.update(context.arguments)
        return ["fastmcp"]

    async with Client(mcp, mode=mode) as client:
        result = await client.complete(
            PromptReference(name="compose"),
            {"name": "repo", "value": "fast"},
            context_arguments={"owner": "prefecthq"},
        )
    assert result.values == ["fastmcp"]
    assert seen == {"owner": "prefecthq"}


@pytest.mark.parametrize("mode", MODES)
async def test_completion_object_passes_through_pagination_hints(mode):
    """Returning a Completion preserves its total / has_more hints."""
    mcp = FastMCP("hints-server")

    @mcp.prompt
    def poem(theme: str) -> str:
        return f"Write a poem about {theme}"

    @mcp.completion
    def complete(ref, argument, context):
        return Completion(values=["nature"], total=42, has_more=True)

    async with Client(mcp, mode=mode) as client:
        result = await client.complete(
            PromptReference(name="poem"),
            {"name": "theme", "value": "n"},
        )
    assert result.values == ["nature"]
    assert result.total == 42
    assert result.has_more is True


async def test_async_completion_handler_is_awaited():
    mcp = FastMCP("async-server")

    @mcp.prompt
    def poem(theme: str) -> str:
        return f"Write a poem about {theme}"

    @mcp.completion
    async def complete(ref, argument, context):
        return ["async-value"]

    async with Client(mcp) as client:
        result = await client.complete(
            PromptReference(name="poem"),
            {"name": "theme", "value": ""},
        )
    assert result.values == ["async-value"]


async def test_sync_completion_handler_runs_off_event_loop_thread():
    """A sync handler is offloaded to a threadpool so blocking work in it can't
    stall the event loop, matching how sync tools/prompts/resources run."""
    mcp = FastMCP("threadpool-server")

    @mcp.prompt
    def poem(theme: str) -> str:
        return f"Write a poem about {theme}"

    handler_thread: dict[str, int] = {}

    @mcp.completion
    def complete(ref, argument, context):
        handler_thread["ident"] = threading.get_ident()
        return ["value"]

    main_thread = threading.get_ident()
    async with Client(mcp) as client:
        result = await client.complete(
            PromptReference(name="poem"),
            {"name": "theme", "value": ""},
        )
    assert result.values == ["value"]
    assert handler_thread["ident"] != main_thread


def test_completion_decorator_registers_handler():
    """`@mcp.completion` (bare) registers the handler and the wire capability."""
    mcp = FastMCP("decorator-server")

    @mcp.completion
    def complete(ref, argument, context):
        return None

    assert mcp._completion_handler is complete
    assert "completion/complete" in mcp._mcp_server._request_handlers


def test_completion_decorator_called_form_registers_handler():
    """`@mcp.completion()` (called) registers the handler too."""
    mcp = FastMCP("decorator-server")

    @mcp.completion()
    def complete(ref, argument, context):
        return None

    assert mcp._completion_handler is complete
    assert "completion/complete" in mcp._mcp_server._request_handlers


@pytest.mark.parametrize(
    "value, expected",
    [
        (None, []),
        ([], []),
        (["a", "b"], ["a", "b"]),
        (("a", "b"), ["a", "b"]),
    ],
)
def test_normalize_completion_coerces_values(value, expected):
    assert normalize_completion(value).values == expected


def test_normalize_completion_passes_completion_through():
    completion = Completion(values=["x"], total=1)
    assert normalize_completion(completion) is completion


def test_normalize_completion_truncates_oversized_list_to_100():
    values = [str(i) for i in range(150)]
    completion = normalize_completion(values)
    assert len(completion.values) == 100
    assert completion.total == 150
    assert completion.has_more is True


def test_normalize_completion_truncates_oversized_completion_and_keeps_total():
    completion = normalize_completion(
        Completion(values=[str(i) for i in range(150)], total=500)
    )
    assert len(completion.values) == 100
    assert completion.total == 500
    assert completion.has_more is True


def test_normalize_completion_rejects_bare_string():
    # A bare str is excluded from the handler return type, so this passes it
    # through an Any-typed value to exercise the runtime guard for callers who
    # bypass type checking.
    bad: Any = "oops"
    with pytest.raises(TypeError, match="return a list of strings"):
        normalize_completion(bad)


def test_completion_argument_and_context_types_importable():
    """The completion authoring types are importable from mcp_types."""
    argument = CompletionArgument(name="theme", value="n")
    context = CompletionContext(arguments={"owner": "prefecthq"})
    assert argument.name == "theme"
    assert context.arguments == {"owner": "prefecthq"}


@pytest.mark.parametrize("mode", MODES)
async def test_completion_does_not_poison_a_response_cache(mode):
    """A completion must not make a caching layer store a listing that a
    generic-hook filter never saw (4.0.7 served hidden prompts this way)."""
    from fastmcp.server.middleware import Middleware
    from fastmcp.server.middleware.caching import ResponseCachingMiddleware

    class HideInternal(Middleware):
        async def on_request(self, context, call_next):
            result = await call_next(context)
            if context.method == "prompts/list":
                return [p for p in result if "internal" not in p.name]
            return result

    mcp = FastMCP(middleware=[ResponseCachingMiddleware(), HideInternal()])

    @mcp.prompt
    def public(x: str) -> str:
        return x

    @mcp.prompt
    def internal_admin(x: str) -> str:
        return x

    @mcp.completion
    def complete(ref, argument, context):
        return ["v"]

    async with Client(mcp, mode=mode) as first, Client(mcp, mode=mode) as second:
        await first.complete(PromptReference(name="public"), {"name": "x", "value": ""})
        listed = [p.name for p in await second.list_prompts()]
    assert listed == ["public"]


@pytest.mark.parametrize("mode", MODES)
async def test_generic_middleware_sees_one_request_per_completion(mode):
    """Rate limits, logging, and metrics must see a completion as one request
    (4.0.6 charged each completion two or three times)."""
    from fastmcp.server.middleware import Middleware

    seen: list[str] = []

    class Recorder(Middleware):
        async def on_request(self, context, call_next):
            seen.append(context.method)
            return await call_next(context)

    mcp = FastMCP(middleware=[Recorder()])

    @mcp.prompt
    def poem(theme: str) -> str:
        return theme

    @mcp.resource("notes://{path}")
    def note(path: str) -> str:
        return path

    @mcp.completion
    def complete(ref, argument, context):
        return ["v"]

    async with Client(mcp, mode=mode) as client:
        seen.clear()
        await client.complete(
            PromptReference(name="poem"), {"name": "theme", "value": ""}
        )
        await client.complete(
            ResourceTemplateReference(uri="notes://{path}"),
            {"name": "path", "value": ""},
        )
    assert seen == ["completion/complete", "completion/complete"]


def _gated_server(**kwargs: Any) -> FastMCP:
    mcp = FastMCP(**kwargs)

    @mcp.prompt(tags={"secret"})
    def hidden_prompt(x: str) -> str:
        return x

    @mcp.resource("notes://{path}", tags={"secret"})
    def hidden_note(path: str) -> str:
        return path

    @mcp.resource("public://{path}")
    def public_note(path: str) -> str:
        return path

    @mcp.completion
    def complete(ref, argument, context):
        return ["private/salary.md"]

    return mcp


async def _completions(mcp: FastMCP, mode: str) -> tuple[list, list, list]:
    async with Client(mcp, mode=mode) as client:
        prompt = await client.complete(
            PromptReference(name="hidden_prompt"), {"name": "x", "value": ""}
        )
        template = await client.complete(
            ResourceTemplateReference(uri="notes://{path}"),
            {"name": "path", "value": ""},
        )
        public = await client.complete(
            ResourceTemplateReference(uri="public://{path}"),
            {"name": "path", "value": ""},
        )
    return prompt.values, template.values, public.values


@pytest.mark.parametrize("mode", MODES)
async def test_disabled_references_complete_like_unknown_ones(mode):
    mcp = _gated_server()
    mcp.disable(tags={"secret"})
    assert await _completions(mcp, mode) == ([], [], ["private/salary.md"])


@pytest.mark.parametrize("mode", MODES)
async def test_auth_middleware_denied_references_complete_like_unknown_ones(mode):
    from fastmcp.server.middleware import AuthMiddleware

    mcp = _gated_server(
        middleware=[
            AuthMiddleware(
                auth=lambda ctx: ctx.component is None
                or "secret" not in ctx.component.tags
            )
        ]
    )
    assert await _completions(mcp, mode) == ([], [], ["private/salary.md"])


@pytest.mark.parametrize("mode", MODES)
@pytest.mark.parametrize("gate", ["none", "disable", "auth_middleware"])
async def test_query_only_template_completes_by_its_own_identifier(mode, gate):
    """A template's identifier does not match it as a URI when it only has
    query parameters, so completion must resolve the template itself."""
    from fastmcp.server.middleware import AuthMiddleware

    middleware = []
    if gate == "auth_middleware":
        middleware = [
            AuthMiddleware(
                auth=lambda ctx: ctx.component is None
                or "secret" not in ctx.component.tags
            )
        ]
    mcp = FastMCP(middleware=middleware)

    @mcp.resource("data://search{?q}")
    def search(q: str = "") -> str:
        return q

    @mcp.resource("data://hidden{?q}", tags={"secret"})
    def hidden(q: str = "") -> str:
        return q

    @mcp.completion
    def complete(ref, argument, context):
        return ["v"]

    if gate == "disable":
        mcp.disable(tags={"secret"})

    async with Client(mcp, mode=mode) as client:
        visible = await client.complete(
            ResourceTemplateReference(uri="data://search{?q}"),
            {"name": "q", "value": ""},
        )
        gated = await client.complete(
            ResourceTemplateReference(uri="data://hidden{?q}"),
            {"name": "q", "value": ""},
        )
    assert visible.values == ["v"]
    assert gated.values == ([] if gate != "none" else ["v"])


@pytest.mark.parametrize("mode", MODES)
async def test_versioned_template_completion_checks_the_listed_version(mode):
    """Completion authorizes the version clients list, not the first one
    registered."""
    from fastmcp.server.middleware import AuthMiddleware

    mcp = FastMCP(
        middleware=[
            AuthMiddleware(
                auth=lambda ctx: ctx.component is None
                or "secret" not in ctx.component.tags
            )
        ]
    )

    @mcp.resource("data://item/{id}", version="1", tags={"secret"})
    def item_v1(id: str) -> str:
        return id

    @mcp.resource("data://item/{id}", version="2")
    def item_v2(id: str) -> str:
        return id

    @mcp.completion
    def complete(ref, argument, context):
        return ["v"]

    async with Client(mcp, mode=mode) as client:
        result = await client.complete(
            ResourceTemplateReference(uri="data://item/{id}"),
            {"name": "id", "value": ""},
        )
    assert result.values == ["v"]