kernel-retrieval-mcp
kernel-retrieval-mcp is a thin library for exposing a retrievalbase retriever through an MCP server built with FastMCP.
It gives you a small integration layer:
- load a retriever from typed settings
- register a
retrieve(query: str)MCP tool - normalize retrieved points into a stable evidence payload
- run the server over
stdio,http,sse, orstreamable-http
This package is intentionally narrow. It does not implement embedding, vector storage, or ranking itself; those concerns are delegated to retrievalbase.
What It Does
At runtime, MCPRunner:
- creates a
FastMCPapp namedmcp - builds a
DenseRetrieverfrom the configuredretriever.engine - builds an evidence formatter from
evidence.module_path - exposes a
retrieveMCP tool - returns results in this shape:
{
"retrieval": {
"evidence": [
{
"score": 0.91,
"page_content": "first chunk",
"metadata": {
"source": "doc-1",
"page": 1
}
}
]
}
}
Installation
uv add kernel-retrieval-mcp
Or with pip:
pip install kernel-retrieval-mcp
Requirements:
- Python
>=3.11,<3.13 - a compatible
retrievalbaseretriever configuration
Core API
The package surface is intentionally small:
kernel_retrieval_mcp.MCPRunnerkernel_retrieval_mcp.EvidenceBuilderkernel_retrieval_mcp.utils.get_runner
Use MCPRunner when you want to instantiate the server directly from a settings object. Use get_runner() when you want to bootstrap the runner from YAML by class path.
Quickstart
1. Define a runner settings class
You usually create a project-specific runner that pins the concrete retriever and evidence-builder settings you want to support.
from retrievalbase.evaluation.settings import DenseRetrieverSettings
from kernel_retrieval_mcp import MCPRunner
from kernel_retrieval_mcp.settings import EvidenceBuilderSettings, MCPRunnerSettings
class MyEvidenceSettings(EvidenceBuilderSettings):
pass
class MyRunnerSettings(
MCPRunnerSettings[
DenseRetrieverSettings,
MyEvidenceSettings,
]
):
pass
class MyRunner(MCPRunner[MyRunnerSettings]):
pass
2. Instantiate and run it
from my_project.runner import MyRunner
runner = MyRunner.from_settings()
runner.run()
If you prefer to load the runner class from YAML:
from kernel_retrieval_mcp.utils import get_runner
runner = get_runner("config/config.yaml")
runner.run()
Configuration
get_runner() expects a YAML file with a top-level module_path pointing to your runner class. from_settings() relies on Pydantic settings resolution provided by retrievalbase, which defaults to /config/config.yaml.
A minimal project layout looks like this:
my_project/
runner.py
config/
config.yaml
Example config/config.yaml:
module_path: my_project.runner.MyRunner
server:
transport: http
host: 127.0.0.1
port: 8080
retriever:
limit: 8
reranker_limit: null
engine:
module_path: retrievalbase.evaluation.retrievers.dense.DenseRetriever
reranker: null
embedder:
module_path: my_project.embedder.MyEmbedder
model_name: my-embedding-model
vector_store:
module_path: my_project.vector_store.MyVectorStore
processor:
module_path: my_project.processor.MyProcessor
evidence:
module_path: my_project.evidence.MyEvidenceBuilder
Notes:
serveris owned by this package.retriever.engineis aretrievalbaseretriever settings object.- nested fields under
enginedepend on the retriever class you choose.
Custom Evidence Builders
The default EvidenceBuilder returns score, page_content, and metadata for each retrieved point. If your MCP clients need citations, document IDs, or a different payload contract, subclass it and override build.
from typing import Any
from kernel_retrieval_mcp import EvidenceBuilder
from kernel_retrieval_mcp.settings import EvidenceBuilderSettings
class CitationEvidenceSettings(EvidenceBuilderSettings):
pass
class CitationEvidenceBuilder(EvidenceBuilder[CitationEvidenceSettings]):
def build(self, points) -> dict[str, Any]:
return {
"retrieval": {
"evidence": [
{
"score": point.score,
"text": point.document.page_content,
"source": point.document.metadata.get("source"),
"page": point.document.metadata.get("page"),
}
for point in points
]
}
}
Development
Install dev dependencies:
make dev-install
Useful commands:
make format
make lint
make type-check
make test
make test-cov
make ci
Metadata
Release files for kernel-retrieval-mcp 2.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kernel_retrieval_mcp-2.0.1.tar.gz | 174.4 kB | Without provenance | Details for kernel_retrieval_mcp-2.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kernel_retrieval_mcp-2.0.1-py3-none-any.whl | Python 3 | none | any | Details for kernel_retrieval_mcp-2.0.1-py3-none-any.whl |
Total release size: 179.8 kB
Release files / kernel_retrieval_mcp-2.0.1.tar.gz
| Download URL | kernel_retrieval_mcp-2.0.1.tar.gz |
|---|---|
| Size | 174.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cac6c92024ccc0a2c8dff6bb607c97b7d2370a7b95142aa9c3466f450881f5a8
|
|
BLAKE2b-256 checksum How to use checksums |
8abbfa3bed6189807bdb71248211a1c4d098b55f23012fd8ee0864239c341ba1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.17 {"installer":{"name":"uv","version":"0.11.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / kernel_retrieval_mcp-2.0.1-py3-none-any.whl
| Download URL | kernel_retrieval_mcp-2.0.1-py3-none-any.whl |
|---|---|
| Size | 5.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eeb86543589e5ea64a1272a3752e8de116d6ed067c6af73ae4ff8ad99efe9f2c
|
|
BLAKE2b-256 checksum How to use checksums |
dacdd15bf12258a5641343f012c1e71babae5ba9d5f808d11a4961aebdac79d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.17 {"installer":{"name":"uv","version":"0.11.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for kernel-retrieval-mcp 2.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.