Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

3.5 KB
Raw Blame
"""Tool registry for the MCP server.

Each tool is a Python coroutine registered via the @tool decorator. The
registry holds (name → ToolSpec) for /mcp's `tools/list` and `tools/call`.
"""
from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any, Awaitable, Callable

from sqlalchemy.ext.asyncio import AsyncSession

from mcp_server.auth import CallContext


ToolHandler = Callable[..., Awaitable[Any]]


@dataclass
class ToolSpec:
    name: str
    description: str
    parameters: dict[str, Any]  # JSON Schema (object)
    handler: ToolHandler
    # Optional. When True, the tool produces a preview (no DB writes); the
    # frontend asks the user to confirm before applying. Drives UI hints.
    is_proposal: bool = False
    tags: list[str] = field(default_factory=list)


REGISTRY: dict[str, ToolSpec] = {}


def tool(
    name: str,
    *,
    description: str,
    parameters: dict[str, Any],
    is_proposal: bool = False,
    tags: list[str] | None = None,
) -> Callable[[ToolHandler], ToolHandler]:
    """Decorator. The handler must be an async function with signature
    `async def handler(session: AsyncSession, ctx: CallContext, **kwargs)`.
    """
    def deco(fn: ToolHandler) -> ToolHandler:
        if name in REGISTRY:
            raise RuntimeError(f"duplicate tool registration: {name}")
        REGISTRY[name] = ToolSpec(
            name=name,
            description=description,
            parameters=parameters,
            handler=fn,
            is_proposal=is_proposal,
            tags=list(tags or []),
        )
        return fn
    return deco


def list_tools(*, legacy: bool = True) -> list[dict[str, Any]]:
    """MCP tool list payload, in registration order (the spec asks for a
    deterministic order so clients can cache the list).

    Securo's per-tool extras travel under a vendor-prefixed `_meta` key, the
    place the spec gives them. Legacy responses also keep the old top-level
    `_securo` object: during a rolling deploy the backend's agent runtime can
    briefly be one version behind the mcp-server, and it read that field.
    Modern responses leave it out, since `Tool` defines no such property.
    """
    from mcp_server.protocol import TOOL_META_KEY, tool_annotations

    out: list[dict[str, Any]] = []
    for s in REGISTRY.values():
        extras = {"is_proposal": s.is_proposal, "tags": s.tags}
        item: dict[str, Any] = {
            "name": s.name,
            "description": s.description,
            "inputSchema": s.parameters,
            "annotations": tool_annotations(s.name, is_proposal=s.is_proposal),
            "_meta": {TOOL_META_KEY: extras},
        }
        if legacy:
            item["_securo"] = extras
        out.append(item)
    return out


async def call_tool(
    session: AsyncSession,
    ctx: CallContext,
    name: str,
    arguments: dict[str, Any] | None,
) -> Any:
    spec = REGISTRY.get(name)
    if spec is None:
        raise KeyError(f"unknown tool: {name}")
    from app.core.app_clock import use_timezone
    from mcp_server.tools._helpers import resolve_workspace_id

    # A token minted before workspaces existed carries no `ws_id`; the tool
    # resolves the default workspace itself, and a caller with none at all
    # still gets the application timezone rather than an error here.
    try:
        workspace_id = await resolve_workspace_id(session, ctx)
    except ValueError:
        workspace_id = None
    async with use_timezone(session, workspace_id):
        return await spec.handler(session=session, ctx=ctx, **(arguments or {}))