server#
KernelFoundry MCP server allowing to use components of the pipeline as tools
Functions
|
Builds and tests a task defined in a directory. |
|
Fetches the full record for one kernel found via |
|
Start the KernelFoundry MCP server. |
|
Searches the shared KernelFoundry kernel database for previously generated kernels. |
|
Submits a task for multi-iteration kernel optimization. |
Classes
|
Structured result returned by the |
- class kernelfoundry.mcp_server.server.BuildAndTestResult(*, success: bool, job_id: int, eval_log: str, runtime_stats: dict[str, ~typing.Any] = <factory>, speedup: float | str = 'N/A', best_kernel_id: int | None = None, error: str | None = None, graph_url: str | None = None)[source]#
Structured result returned by the
build_and_testMCP tool.- model_config: ClassVar[ConfigDict] = {}#
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- async kernelfoundry.mcp_server.server.search_kernels_in_db(task_name_contains: str | None = None, task_name: str | None = None, output_code_contains: str | None = None, output_code_terms: list[str] | None = None, output_language: str | None = None, gpu_arch_contains: str | None = None, gpu_arch: str | None = None, max_runtime: float | None = None, min_speedup: float | None = None, max_speedup: float | None = None, limit: int = 20, offset: int = 0, ctx: ~fastmcp.server.context.Context | None = <fastmcp.server.dependencies._OptionalCurrentContext object>) dict[str, Any][source]#
Searches the shared KernelFoundry kernel database for previously generated kernels.
Every task run through KernelFoundry (
submit_task/build_and_test) writes one row per generated kernel to a shared database. Use this tool to find prior kernels matching a task or code pattern – e.g. to see how other kernels solved a similar problem, or to check whether a given optimization construct has already been tried. Follow up on interesting matches withget_kernel_from_db(id)to fetch the full source and evaluation log.Always restricted to kernels with
status == "correct"andspeedup > 0.5(ratio over reference, e.g. 1.5 = 1.5x faster) – below 1.0x since a kernel can still be good if compared against an especially strong native reference. Results are diversified across task_name (each task’s best kernel first, then each task’s second-best, and so on) rather than plain speedup order, since one job produces many near-identical iterations of the same task. All other filters are optional and combined with AND.- Parameters:
task_name – Case-insensitive exact match on the task name.
task_name_contains – Case-insensitive substring match on the task name, e.g. “gemm”.
output_code_contains – Case-insensitive substring match on the generated kernel source, e.g. “dpas” to find kernels using that intrinsic.
output_code_terms – Case-insensitive search terms; every term must occur in the generated kernel source.
output_language – Exact match (case-insensitive), e.g. “sycl”, “cuda”, “triton”, “cm” (C for Metal).
gpu_arch_contains – Case-insensitive substring match on the GPU architecture string, e.g. “bmg” (matches both a plain “bmg” value and combos like “bmg,lnl”).
gpu_arch – Case-insensitive exact match on the GPU architecture string.
max_runtime – Upper bound on runtime, in milliseconds.
min_speedup – Lower bound on speedup ratio (on top of the always-applied >0.5x floor), e.g. 1.5 = 1.5x faster than native.
max_speedup – Upper bound on speedup ratio, e.g. 1.5 = 1.5x faster than native.
limit – Max rows to return, clamped to [1, 100]. Defaults to 20.
offset – Zero-based row offset, for paging through results beyond limit.
- Returns:
A dictionary with the following keys:
success (bool): Whether the search completed successfully.
total_count (int): Total number of matching rows across all pages.
results (list[dict]): One compact entry per match with keys id, uuid, task_name, job_name, input_language, output_language, runtime (milliseconds), speedup (ratio, e.g. 1.5 = 1.5x faster than native), gpu_arch, timestamp, and output_code_preview (the code is truncated – call
get_kernel_from_db(id)for the full source).error (str | None): Error message if the search failed.
- Return type:
- async kernelfoundry.mcp_server.server.get_kernel_from_db(kernel_id: int, include_profiler_data: bool = False, ctx: ~fastmcp.server.context.Context | None = <fastmcp.server.dependencies._OptionalCurrentContext object>) dict[str, Any][source]#
Fetches the full record for one kernel found via
search_kernels_in_db.- Parameters:
kernel_id – Database ID of the kernel (the “id” field from search_kernels_in_db results).
include_profiler_data – If True, also include the detailed profiler timeline JSON blobs, which can be large. Defaults to False.
- Returns:
A dictionary with the following keys:
- success (bool): Whether the lookup completed successfully.
- kernel (dict | None): Kernel metadata, output_code, eval_log, runtime_stats,
optimization_profile, and other compact fields, or None if no kernel with that ID exists. Large prompt/answer text is omitted.
error (str | None): Error message if the lookup failed.
- Return type:
- async kernelfoundry.mcp_server.server.submit_task(folder_path: str, ctx: ~fastmcp.server.context.Context = <fastmcp.server.dependencies._CurrentContext object>) dict[str, Any][source]#
Submits a task for multi-iteration kernel optimization.
Runs the full optimization loop (many LLM iterations), either locally or, if a
server_urlis configured, on the KernelFoundry server. Returns results for the best kernel found, ranked by composite performance score (perf_score + speedup).Unlike
build_and_test, this tool does not support internal communication and, when running locally, requiresmax_iters > 0in the task’s config.- Parameters:
folder_path (str) – Absolute or relative path to the folder containing the custom task.
- Returns:
A dictionary with the following keys:
success (bool): Whether the job completed successfully.
job_id (int): The ID of the submitted job.
eval_log (str): The evaluation log of the best kernel found.
runtime_stats (dict): Runtime statistics from the best kernel execution.
speedup (float | str): Runtime improvement of the best kernel or “N/A”.
best_kernel_id (int | None): Database ID of the best kernel.
graph_url (str | None): Link to the KernelFoundry graph UI showing this task’s full iteration history. Always share this link with the user after reporting results.
- Side effect:
The best kernel’s code is written back into the task folder, replacing the content between the
[EVOLVE_START]and[EVOLVE_END]markers.
- Return type:
- async kernelfoundry.mcp_server.server.build_and_test(folder_path: str, ctx: ~fastmcp.server.context.Context = <fastmcp.server.dependencies._CurrentContext object>) BuildAndTestResult[source]#
Builds and tests a task defined in a directory.
If a server URL is configured, this submits the task archive to the KernelFoundry server and waits for results. Otherwise it evaluates the task locally.
Note: this tool only builds and tests the current kernel, it does not run the full multi-iteration optimization loop. Optimization-related parameters in config.yaml are ignored.
Returns a structured result containing success status, job ID, evaluation log, runtime statistics, speedup, best-kernel ID (optional), potential errors, and a URL to the KernelFoundry UI showing the graph of how the kernel evolved. If the URL is present and not None, share the link with the user after reporting results.
- Parameters:
folder_path (str) – Absolute or relative path to the folder containing the custom task.
- Returns:
The build and test result with the following fields:
success (bool): Whether the job completed successfully.
job_id (int): The ID of the submitted job.
eval_log (str): The evaluation log from the job execution.
runtime_stats (dict): Runtime statistics from kernel execution.
speedup (float | str): Runtime improvement metric or “N/A” if not available.
error (str, optional): Error message if the job failed.
graph_url (str | None): Link to the KernelFoundry graph UI showing this task’s full iteration history.
- Return type:
- kernelfoundry.mcp_server.server.main(_internal_comm_path_arg: str | None = None) None[source]#
Start the KernelFoundry MCP server.
Initializes logging and starts the Model Context Protocol server, which provides tools for building and testing kernel optimization tasks. Optionally configures internal communication via file-based handoff if a communication path is provided.
- Parameters:
_internal_comm_path_arg (str | None) – Optional path for file-based internal communication. If provided, the server will use this directory for handoff with another process instead of HTTP-based communication with a remote server. Defaults to None.