build_search_docs_result#

scikitplot.mcp.build_search_docs_result(query, chunks, *, max_results=20)[source]#

Format retrieval results as an MCP tools/call response with citations.

The returned keys mirror an MCP CallToolResult wire shape for callers that need it directly. A high-level MCP SDK server should normally return a typed Python object and let the SDK build the protocol result.

Parameters:
querystr

The original query (echoed in structured output for traceability).

chunkslist of RetrievedChunk

Retrieval results, best first.

max_resultsint, optional

Upper bound on results actually emitted. Must be a non-negative integer; zero is a request for no results. A value above MAX_RESULTS is clamped to it rather than refused.

Returns:
dict

An MCP tool-result object:

{
    "content": [{"type": "text", "text": ...}, ...],
    "structuredContent": {
        "query": ...,
        "count": ...,
        "passages": [...],
        "citations": [...],
        "message": null | str,
    },
    "isError": False,
}

The content blocks are human/model-readable, each carrying its citation marker; structuredContent.citations is the machine-usable list (source_uri already scheme-validated). Status text for an empty result is stored in message rather than passages. Untrusted chunk text is control-stripped and length-capped.

Parameters:
Return type:

dict[str, Any]

Notes

  • Read-only. search_docs needs no user confirmation. Any sensitive or write tool added later MUST require explicit confirmation per MCP guidance — see the design doc; this function is not that path.

  • Retrieved text is explicitly untrusted data: it is sanitised here, and the server layer marks it so the model treats it as context, not instructions.