server#

KernelFoundry MCP server allowing to use components of the pipeline as tools

Functions

build_and_test(folder_path[, ctx])

Builds and tests a task defined in a directory.

get_kernel_from_db(kernel_id[, ...])

Fetches the full record for one kernel found via search_kernels_in_db.

main([_internal_comm_path_arg])

Start the KernelFoundry MCP server.

search_kernels_in_db([task_name_contains, ...])

Searches the shared KernelFoundry kernel database for previously generated kernels.

submit_task(folder_path[, ctx])

Submits a task for multi-iteration kernel optimization.

Classes

BuildAndTestResult(*, success, job_id, ...)

Structured result returned by the build_and_test MCP tool.

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_test MCP tool.

success: bool#
job_id: int#
eval_log: str#
runtime_stats: dict[str, Any]#
speedup: float | str#
best_kernel_id: int | None#
error: str | None#
graph_url: str | None#
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 with get_kernel_from_db(id) to fetch the full source and evaluation log.

Always restricted to kernels with status == "correct" and speedup > 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:

dict

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:

dict

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_url is 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, requires max_iters > 0 in 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:

dict

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:

BuildAndTestResult

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.