Context API

Access runtime MCP capabilities—logging, progress, resource access, sampling—inside any Hyperia tool, resource, or prompt.

When you decorate a Python function as a tool/resource/prompt, it executes inside an MCP request‑scope. Hyperia exposes that scope via the Context object so your code can talk back to the client, stream progress, or even call the client’s LLM.

What Is Context?

The object provides:

  • Logging – debug/info/warning/error back to the caller.

  • Progress reporting – live percentage updates for long tasks.

  • Resource access – read other resources on the server.

  • LLM sampling – let the client’s model generate text/images mid‑function.

  • Request meta – IDs, client origin, etc.

  • Advanced hooks – raw session objects and server instance when absolutely needed.

Injecting Context

Add a parameter typed Context anywhere in the signature. Hyperia will inject it.

from hyperia import Hyperia, Context

mcp = Hyperia("CtxDemo")

@mcp.tool()
async def process_file(uri: str, ctx: Context) -> str:
    await ctx.info(f"Processing {uri}")
    ...

Rules

  • Parameter name doesn’t matter; the type hint does.

  • Omit it if you don’t need context.

  • Most methods are async; declare your function async def.

  • Context only exists during a request; calling methods outside raises errors. For unit tests you can type‑hint Context | None = None.

Context in Resources & Prompts

@mcp.resource("resource://{user}/profile")
async def profile(user: str, ctx: Context):
    return {"user": user, "request_id": ctx.request_id}

@mcp.prompt()
async def report(kind: str, ctx: Context) -> str:
    return f"Please compile a {kind} report. ReqID: {ctx.request_id}"

Dependency Helper get_context()

If a deep utility function can’t accept an extra param, retrieve the active context dynamically (server‑side only):

from hyperia.server.dependencies import get_context

async def helper():
    ctx = get_context()    # only valid inside a request
    await ctx.debug("Helper called")

Calling get_context() outside a request → RuntimeError.

Capabilities

1. Logging

@mcp.tool()
async def analyse(data: list[float], ctx: Context):
    await ctx.debug("Starting analysis")
    avg = sum(data)/len(data) if data else 0
    await ctx.info(f"Average={avg}")
    return avg
Method
Use

ctx.debug(msg)

Verbose trace

ctx.info(msg)

Normal progress

ctx.warning(msg)

Non‑fatal issues

ctx.error(msg)

Errors

ctx.log(level, msg, logger_name=None)

Custom level/logger

2. Progress Reporting

@mcp.tool()
async def process(items: list[str], ctx: Context):
    total = len(items)
    for i, itm in enumerate(items):
        await ctx.report_progress(i, total)
        await asyncio.sleep(0.05)
    await ctx.report_progress(total, total)

Signature: ctx.report_progress(progress: float, total: float | None = None). Client must send a progressToken or updates are ignored.

3. Resource Access

@mcp.tool()
async def summarise(uri: str, ctx: Context):
    res = await ctx.read_resource(uri)
    text = res[0].content if res else ""
    ...

Returns a list of ReadResourceContents; usually read content of first part.

4. LLM Sampling

@mcp.tool()
async def sentiment(text: str, ctx: Context):
    resp = await ctx.sample(
        messages=f"Classify the sentiment of: {text}",
        system_prompt="Return only: positive, negative, or neutral.",
        temperature=0.0,
    )
    return resp.text.strip().lower()

Signature: ctx.sample(messages, system_prompt=None, temperature=None, max_tokens=None) → returns TextContent or ImageContent.

5. Request Info

@mcp.tool()
async def info(ctx: Context):
    return {"req": ctx.request_id, "client": ctx.client_id}

Advanced Accessors

@mcp.tool()
async def server_name(ctx: Context):
    srv = ctx.Hyperia  # server instance
    return srv.name

Also available: ctx.session, ctx.request_context for low‑level operations (use sparingly).

HTTP Request (Starlette) (Server builds with ASGI)

ctx.get_http_request() is deprecated → use hyperia.server.dependencies.get_http_request() inside ASGI stacks if needed.

Server Behaviour Flags

Duplicate Context Injection

Context itself does not have duplication rules, but note you can configure duplicate tools/resources/prompts via on_duplicate_* settings at server init as shown in earlier chapters.

PreviousPromptsNextProxy Servers

Last updated