yera.tools.mcp.catalogue

Rebuildable SQLite catalogue for discovered MCP tools.

Symbols

class MCPServerRecord — Metadata retained for one imported MCP server.
class MCPToolRecord — Metadata retained for one tool discovered from an MCP server.
class SQLiteMCPCatalogue — Cache discovered MCP metadata in a persistent, rebuildable database.

MCPServerRecord

Metadata retained for one imported MCP server.

Fields

name
type: str (required)
url
type: str (required)

Methods


MCPServerRecord.__init__

__init__(
    name: str,
    url: str,
) → None

MCPToolRecord

Metadata retained for one tool discovered from an MCP server.

Fields

server_name
type: str (required)
name
type: str (required)
input_schema
type: dict[str, object] (required)
title
type: str | None = None
description
type: str | None = None
output_schema
type: dict[str, object] | None = None
annotations
type: dict[str, object] | None = None
icons
type: tuple[dict[str, object], ...] = ()
execution
type: dict[str, object] | None = None
meta
type: dict[str, object] | None = None

Methods

from_discovered_tool — Build a catalogue record from MCP discovery metadata.

MCPToolRecord.from_discovered_tool

from_discovered_tool(
    server_name: str,
    tool: Tool,
) → Self

Build a catalogue record from MCP discovery metadata.

Parameters

server_name
type: str

Yera's configured name for the supplying server.

tool
type: Tool

Tool definition returned by the MCP server.

Returns

type: Self

A serializable catalogue record retaining the discovered metadata.

MCPToolRecord.__init__

__init__(
    server_name: str,
    name: str,
    input_schema: dict[str, object],
    title: str | None = None,
    description: str | None = None,
    output_schema: dict[str, object] | None = None,
    annotations: dict[str, object] | None = None,
    icons: tuple[dict[str, object], ...] = (),
    execution: dict[str, object] | None = None,
    meta: dict[str, object] | None = None,
) → None

SQLiteMCPCatalogue

Cache discovered MCP metadata in a persistent, rebuildable database.

Methods

__init__ — Configure a persistent, rebuildable MCP catalogue.
__enter__ — Open the catalogue, rebuilding unsupported schemas.
__exit__ — Close the catalogue connection.
replace_server — Atomically replace one server and all its discovered tools.
remove_server — Atomically remove one server and all its discovered tools.
server — Return one configured catalogue server.
tools_for_server — Return one server's imported tools ordered by tool name.

SQLiteMCPCatalogue.__init__

__init__(
    path: Path | None = None,
) → None

Configure a persistent, rebuildable MCP catalogue.

Parameters

path
type: Path | None = None

SQLite database path, or None to use Yera's standard mcp.db location.

SQLiteMCPCatalogue.__enter__

__enter__() → SQLiteMCPCatalogue

Open the catalogue, rebuilding unsupported schemas.

Returns

type: SQLiteMCPCatalogue

This catalogue with an initialised database connection.

SQLiteMCPCatalogue.__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) → None

Close the catalogue connection.

Parameters

exc_type
type: type[BaseException] | None

Type of an exception leaving the context, or None.

exc_value
type: BaseException | None

Exception leaving the context, or None.

traceback
type: TracebackType | None

Traceback for the exception, or None.

SQLiteMCPCatalogue.replace_server

replace_server(
    server: MCPServerRecord,
    tools: list[MCPToolRecord],
) → None

Atomically replace one server and all its discovered tools.

The transaction is rolled back if persistence fails.

Parameters

server
type: MCPServerRecord

Server metadata to create or replace.

tools
type: list[MCPToolRecord]

Complete discovered tool set for the server.

Raises

RuntimeError

If the catalogue is not open.

ValueError

If a tool belongs to a different server.

SQLiteMCPCatalogue.remove_server

remove_server(
    server_name: str,
) → None

Atomically remove one server and all its discovered tools.

The transaction is rolled back if persistence fails.

Parameters

server_name
type: str

Configured name of the server to remove.

Raises

RuntimeError

If the catalogue is not open.

SQLiteMCPCatalogue.server

server(
    server_name: str,
) → MCPServerRecord | None

Return one configured catalogue server.

Parameters

server_name
type: str

Name of the server to retrieve.

Returns

type: MCPServerRecord | None

The server record, or None when it is absent.

Raises

RuntimeError

If the catalogue is not open.

SQLiteMCPCatalogue.tools_for_server

tools_for_server(
    server_name: str,
) → list[MCPToolRecord]

Return one server's imported tools ordered by tool name.

Parameters

server_name
type: str

Configured name of the server whose tools should be returned.

Returns

type: list[MCPToolRecord]

Imported tool records ordered by tool name, or an empty list when the server has no imported tools.

Raises

RuntimeError

If the catalogue is not open.