scikitplot.mcp#

Composable documentation retrieval for Model Context Protocol (MCP) servers.

The default import surface is independent of the MCP SDK, pydantic, and the optional corpus/vector dependencies. Importing scikitplot.mcp pulls only the SDK-free retrieval core (contracts, fusion, the in-memory demo retriever) and the pydantic-free capability/runtime-status helpers, so it works on the Legacy Retrieval tier (Python 3.8+) with a base install.

The server layer (SearchService, create_server, and the pydantic output models SearchDocsOutput / CitationOutput) is imported lazily on first access. It requires the [mcp] extra (pydantic always; mcp>=2.0.0,<3 on Python >= 3.10). No models, indexes, files, or network connections are opened at import time.

User guide. See the Model Context Protocol Retrieval section for further details.

MCP: Capabilities#

assert_capability_vocabulary_matches_corpus

Verify this module's capability vocabulary still matches Corpus's.

effective_server_capabilities

Return the effective surface for a specific server configuration.

server_capabilities

Return the static / potential tool/resource inventory, without importing the MCP SDK — safe on any interpreter, including the Legacy Retrieval tier.

server_runtime_status

Report, without importing the MCP SDK, whether the protocol server can run in this interpreter — so callers can degrade gracefully to the SDK-free retrieval layer instead of catching an exception from create_server.

MCP: Core#

Class inheritance

Inheritance diagram of DocsRetriever, RetrievedChunk, SearchCoordinator

DOC_ID_RE

Compiled regular expression object.

MAX_CHUNK_CHARS

int([x]) -> integer int(x, base=10) -> integer

MAX_QUERY_CHARS

int([x]) -> integer int(x, base=10) -> integer

MAX_RESOURCE_CHARS

int([x]) -> integer int(x, base=10) -> integer

MAX_RESULTS

int([x]) -> integer int(x, base=10) -> integer

RESOURCE_METADATA_ALLOWANCE

int([x]) -> integer int(x, base=10) -> integer

DocsRetriever

Structural contract every retrieval backend must satisfy.

RetrievedChunk

One retrieved passage with the metadata needed to cite it.

SearchCoordinator

Validated, concurrency-bounded search orchestration, free of wire models.

build_search_docs_result

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

is_valid_doc_id

Return whether value is an acceptable document identifier.

MCP: Corpus Index Retriever#

Class inheritance

Inheritance diagram of CorpusAnnoyRetriever, CorpusIndexRetriever

CorpusAnnoyRetriever

Docs dense retriever backed by an embedder + a vector index + a document lookup.

CorpusIndexRetriever

Text-level retriever over a corpus RetrievalIndex: hybrid by default.

Embedder

Anything that turns a query string into a vector (e.g. corpus EmbeddingEngine).

VectorIndex

Anything that returns (doc_id, score) pairs for a query vector.

MCP: Corpus Hybrid Retriever#

Class inheritance

Inheritance diagram of Bm25Retriever, HybridRetriever

DEFAULT_RRF_K

int([x]) -> integer int(x, base=10) -> integer

Bm25Retriever

Lexical retriever (FTS/BM25) leg backed by a full-text search seam.

HybridRetriever

Fuse several retrievers into one via Reciprocal Rank Fusion.

reciprocal_rank_fusion

Fuse weighted ranked lists into a single key -> score map.

MCP: Demo#

DemoDocument

One in-memory document used by InMemoryBm25Retriever.

InMemoryBm25Retriever

A compact BM25 implementation suitable for demos and small corpora.

builtin_demo_retriever

Return a tiny corpus that explains the sample's own mechanism.

MCP: Outcome#

Class inheritance

Inheritance diagram of LegRecord, RetrievalOutcome

CANCELLED

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

DEGRADED

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

EMPTY

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

FAILED

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

SUCCESS

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

LegRecord

How one retrieval leg fared.

RetrievalOutcome

Ranked hits plus the story of how they were obtained.

assert_matches_corpus

Verify this module's vocabulary still matches Corpus's.

to_corpus_status

Resolve a status string to scikitplot.corpus.RetrievalStatus.

MCP: Server#

CitationOutput

Stable source metadata for one returned passage.

SearchDocsOutput

Structured output schema automatically advertised by MCP SDK v2.

SearchService

Wire adapter: bounded, validated search returning pydantic tool models.

create_server

Create an official MCP Python SDK v2 MCPServer instance.

MCP: Command Line and Validation#

RuntimeConfig

Validated effective CLI configuration.

main

require_count

Return value as a non-negative count within its declared maximum.

require_index

Return value as a position valid in [0, count).