registeruz-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Model Context Protocol (MCP) server for Slovak registry of financial statements from Slovak Ministry Of Finance based on the API documentation.

Development Commands

# Install dependencies
uv sync

# Run the MCP server (STDIO transport - default)
uv run python registeruz_mcp.py

# Run with FastMCP CLI
uv run fastmcp run registeruz_mcp.py

# Run with HTTP transport
uv run fastmcp run registeruz_mcp.py --transport http --port 8000

# Inspect server (view tools, resources, prompts)
uv run fastmcp inspect registeruz_mcp.py

# Development mode with MCP Inspector
uv run fastmcp dev registeruz_mcp.py

# Run tests
uv run pytest
uv run pytest -v  # verbose
uv run pytest --cov=.  # with coverage

Architecture

• Framework: FastMCP v2.14+ for building MCP servers
• Python: 3.12 (managed via mise)
• Package manager: uv

The main server implementation is in registeruz_mcp.py.

FastMCP Patterns

Tools

Tools are functions that LLMs can call. Define with @mcp.tool decorator:

@mcp.tool
def my_tool(param: str) -> str:
    """Tool description shown to LLM."""
    return result

# With tags and annotations
@mcp.tool(tags={"public"}, annotations={"readOnlyHint": True})
async def async_tool(param: str) -> dict:
    return {"result": param}

Resources

Resources expose data to LLMs via URIs:

@mcp.resource("resource://config")
def get_config() -> dict:
    return {"version": "1.0"}

# Resource templates with parameters
@mcp.resource("data://{item_id}/details")
def get_item(item_id: str) -> dict:
    return {"id": item_id}

Prompts

Reusable message templates:

@mcp.prompt
def analyze_prompt(data: str) -> str:
    return f"Please analyze: {data}"

Context and Dependencies

Access request context and inject dependencies: