### Development Configuration Example

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Example .env file content for a typical development setup.

```env
LOG_LEVEL=DEBUG
FASTMCP_HOST=localhost
FASTMCP_PORT=8000
MCP_SERVER_TRANSPORT=stdio
HTTPX_TIMEOUT=10.0
HTTPX_VERIFY_SSL=True
```

--------------------------------

### Fetch Exchange Rates with HTTPHelperMixin

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/http-helper-mixin.md

This example shows how to use HTTPHelperMixin to get an httpx client and fetch data from an API. It then uses MCPMixin to format the response. Ensure MCPMixin and HTTPHelperMixin are imported.

```python
from frankfurtermcp.mixin import MCPMixin, HTTPHelperMixin

class FrankfurterMCP(MCPMixin, HTTPHelperMixin):
    """Combined usage of both mixins."""
    
    async def fetch_exchange_rates(self, ctx: Context, base: str):
        # Use HTTP helper to get configured client
        with self.get_httpx_client() as client:
            response = client.get(
                f"{self.frankfurter_api_url}/latest",
                params={"base": base}
            )
            response.raise_for_status()
            data = response.json()
        
        # Use MCP helper to format response
        return self.get_response_content(
            response=data,
            http_response=response
        )
```

--------------------------------

### Build and Start Docker Containers

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Build the Docker image, create the container, and start it using Docker Compose. This command starts the MCP server and potentially other services defined in docker-compose.yml.

```bash
docker compose up --build
```

--------------------------------

### Run MCP Server with uv

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Execute this command in the working directory to start the MCP server using uv. Ensure you have uv installed.

```bash
uv run frankfurtermcp
```

--------------------------------

### Docker Configuration Example

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Example .env file content for configuring the application within a Docker environment, specifying host, port, and transport.

```env
DOCKER_TMPFS_SIZE_MB=256
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=8000
MCP_SERVER_TRANSPORT=sse
CORS_MIDDLEWARE_ALLOW_ORIGINS=*
```

--------------------------------

### Example MCP Call for Greeting

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

An example of how to call the greeting tool via MCP, providing a name.

```json
{
  "name": "greet",
  "arguments": {
    "name": "Alice"
  }
}
```

--------------------------------

### Install Prek for Development

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Installs the 'prek' tool, which is required for development contributions to the FrankfurterMCP project. Ensure 'prek' is installed globally or accessible in your environment.

```bash
prek install
```

--------------------------------

### Example Response for Supported Currencies with Metadata

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

This example shows the response from the 'get_supported_currencies' tool, including the 'content' (list of currencies) and 'meta' information from the FrankfurterMCP client.

```json
{
  "content": ["AED", "AFN", "ALL", ...],
  "structured_content": {"result": "[\"AED\", \"AFN\", ...]"},
  "meta": {
    "frankfurtermcp": {
      "version": "0.4.5",
      "api_url": "https://api.frankfurter.dev/v1/currencies",
      "api_status_code": 200,
      "api_bytes_downloaded": 1024,
      "api_elapsed_time": 45000,
      "cached_response": false
    }
  }
}
```

--------------------------------

### RequestSizeLimitMiddleware Constructor Example

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/middleware.md

Demonstrates how to initialize the RequestSizeLimitMiddleware with a specific maximum body size limit in bytes.

```python
# Create middleware with 100KB limit
middleware = RequestSizeLimitMiddleware(app, max_body_size=102400)
```

--------------------------------

### Example Response for Latest Exchange Rates with Metadata

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

This example shows a successful response from the 'get_latest_exchange_rates' tool, including the exchange rates and metadata from the FrankfurterMCP client.

```json
{
  "content": {
    "base": "USD",
    "date": "2025-06-15",
    "rates": {...}
  },
  "structured_content": {
    "base": "USD",
    "date": "2025-06-15",
    "rates": {...}
  },
  "meta": {
    "frankfurtermcp": {
      "version": "0.4.5",
      "api_url": "https://api.frankfurter.dev/v1/latest?base=USD&symbols=EUR,GBP,JPY",
      "api_status_code": 200,
      "cached_response": false
    }
  }
}
```

--------------------------------

### Example Coverage Report Output

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

This is an example of the coverage report generated after running all tests. It displays benchmark results and file-level coverage statistics.

```text
---------------------------------------------------------------------------------------- benchmark: 2 tests ---------------------------------------------------------------------------------------
Name (time in ms)                         Min               Max              Mean            StdDev            Median               IQR            Outliers       OPS            Rounds  Iterations
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_get_historical_exchange_rates     4.4944 (1.0)      5.1512 (1.0)      4.7919 (1.0)      0.2460 (1.0)      4.7819 (1.0)      0.3249 (1.0)           2;0  208.6840 (1.0)           5           1
test_get_latest_exchange_rates         4.7937 (1.07)     5.6976 (1.11)     5.3257 (1.11)     0.3345 (1.36)     5.4182 (1.13)     0.3575 (1.10)          2;0  187.7702 (0.90)          5           1
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean
=============================================================== 15 passed in 4.09s ===============================================================
Name    Stmts   Miss    Cover   Missing
---------------------------------------
TOTAL     265      0  100.00%

6 files skipped due to complete coverage.
Test coverage complete.
```

--------------------------------

### FastMCP Application Setup with AppMetadata

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/common.md

Shows how to initialize the FastMCP application using metadata from AppMetadata, including name, summary, version, and project URL.

```python
from frankfurtermcp.common import AppMetadata
from fastmcp import FastMCP

app = FastMCP(
    name=AppMetadata.package_metadata["Name"],  # "frankfurtermcp"
    instructions=AppMetadata.package_metadata["Summary"],
    version=AppMetadata.package_metadata["Version"],  # "0.4.5"
    website_url=AppMetadata.PROJECT_URL,  # "https://github.com/..."
)
```

--------------------------------

### Install and Run MCP Server with pip

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Install the frankfurtermcp package using pip and then run the server module. This is useful for running the server from a PyPI package.

```bash
pip install frankfurtermcp
python -m frankfurtermcp.server
```

--------------------------------

### Install and Use LTS Node.js with NVM

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Installs and sets the Long Term Support (LTS) version of Node.js using Node Version Manager (nvm). Ensure nvm is installed before running these commands.

```bash
nvm install --lts
nvm use --lts
```

--------------------------------

### Example MCP Call for Latest Currency Conversion

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

Shows how to invoke the `convert_currency_latest` function within the MCP framework. This example specifies the amount and currencies for conversion.

```json
{
  "name": "convert_currency_latest",
  "arguments": {
    "amount": 100.0,
    "from_currency": "USD",
    "to_currency": "EUR"
  }
}
```

--------------------------------

### Registering Features with MCPMixin

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/mcp-mixin.md

Example demonstrating how to define a custom MCP server class inheriting from MCPMixin and registering its tools with a FastMCP instance.

```python
class MyMCPServer(MCPMixin):
    tools = [
        {"fn": "my_tool", "tags": ["example"]},
        {"fn": "another_tool", "tags": ["demo"]}
    ]
    
    async def my_tool(self, ctx: Context):
        return "result"
    
    async def another_tool(self, ctx: Context):
        return "result"

# Register the tools
mcp = FastMCP(name="my-server")
server = MyMCPServer()
server.register_features(mcp)
```

--------------------------------

### Example MCP Call for Currency Conversion

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

An example of how to call the currency conversion tool via MCP, specifying the amount, currencies, and a specific date.

```json
{
  "name": "convert_currency_specific_date",
  "arguments": {
    "amount": 100.0,
    "from_currency": "USD",
    "to_currency": "EUR",
    "specific_date": "2025-01-15"
  }
}
```

--------------------------------

### Package Script Entry Point

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/server.md

Defines the command-line entry point for the package installed via PyPI, allowing the server to be run directly from the terminal.

```toml
# pyproject.toml
[project.scripts]
frankfurtermcp = "frankfurtermcp.server:main"
```

--------------------------------

### StripUnknownArgumentsMiddleware Example Usage

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/middleware.md

Illustrates how the middleware filters unknown parameters from tool calls, ensuring only defined arguments are passed. The example assumes a tool schema and client-sent parameters.

```python
# Tool schema defines parameters: amount, from_currency, to_currency
# Client sends: amount, from_currency, to_currency, unknown_param
# 
# Middleware filters to: amount, from_currency, to_currency
# Logs: INFO - Unknown arguments for tool 'convert_currency_latest': ['unknown_param']

with context.fastmcp_context:
    tool = await context.fastmcp_context.fastmcp.get_tool("convert_currency_latest")
    # tool.parameters = {
    #     "properties": {
    #         "amount": {...},
    #         "from_currency": {...},
    #         "to_currency": {...}
    #     }
    # }
```

--------------------------------

### Get Configured httpx.Client Instance

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/http-helper-mixin.md

Obtain a pre-configured httpx.Client instance for making HTTP requests. This client is set up with SSL verification and timeout settings based on environment variables.

```python
from frankfurtermcp.mixin import HTTPHelperMixin

class MyService(HTTPHelperMixin):
    pass

service = MyService()

# Get a configured client
with service.get_httpx_client() as client:
    response = client.get("https://api.example.com/data")
    data = response.json()
    
    # Process data
    print(response.status_code)
    print(response.headers)
    print(data)
```

--------------------------------

### Example Response for Latest Currency Conversion

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

Provides an example of the complete response structure when using the `convert_currency_latest` endpoint, including content and metadata. The `meta` section contains information about the Frankfurter MCP service.

```json
{
  "content": {
    "from_currency": "USD",
    "to_currency": "EUR",
    "amount": 100.0,
    "converted_amount": 92.0,
    "exchange_rate": 0.92,
    "rate_date": "2025-06-15"
  },
  "meta": {
    "frankfurtermcp": {
      "version": "0.4.5",
      "cached_response": false
    }
  }
}
```

--------------------------------

### Example Greeting Response

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

Shows the structure of a response from the greeting tool, containing the greeting message.

```json
{
  "content": [{"type": "text", "text": "Hello, Alice from Frankfurter MCP!"}],
  "structured_content": {"result": "Hello, Alice from Frankfurter MCP!"}
}
```

--------------------------------

### Running Server via Python Module

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/server.md

Execute the server using the Python module command, useful for running the server directly from a Python installation.

```bash
python -m frankfurtermcp.server
```

--------------------------------

### Start Docker Containers in Detached Mode

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Build and start the Docker containers in detached mode (background). Use this if you want the server to run without keeping the terminal occupied.

```bash
docker compose up -d --build
```

--------------------------------

### Main Entry Point for Frankfurter MCP Server

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/server.md

Shows the standard Python entry point for starting the Frankfurter MCP server. This function handles the creation of the application and its execution based on environment variables for transport and HTTP configurations.

```python
# Start with default stdio transport
if __name__ == "__main__":
    from frankfurtermcp.server import main
    main()
```

--------------------------------

### Example MCP Call for Historical Exchange Rates

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

Demonstrates how to call the `get_historical_exchange_rates` function using the MCP framework. This example requests rates for EUR and GBP between two specified dates.

```json
{
  "name": "get_historical_exchange_rates",
  "arguments": {
    "base_currency": "USD",
    "start_date": "2025-01-01",
    "end_date": "2025-06-15",
    "symbols": ["EUR", "GBP"]
  }
}
```

--------------------------------

### Production Configuration (HTTP Transport)

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Example .env file content for production deployment using HTTP transport, including CORS and rate limiting settings.

```env
LOG_LEVEL=WARNING
FASTMCP_HOST=127.0.0.1
FASTMCP_PORT=8000
MCP_SERVER_TRANSPORT=sse
CORS_MIDDLEWARE_ALLOW_ORIGINS=example.com,app.example.com
RATE_LIMIT_MAX_REQUESTS_PER_SECOND=100.0
RATE_LIMIT_BURST_CAPACITY=200
REQUEST_SIZE_LIMIT_BYTES=104857600
UVICORN_LIMIT_CONCURRENCY=500
```

--------------------------------

### MCP Call for Supported Currencies

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

This is an example of an MCP client call to the 'get_supported_currencies' tool. It requires no arguments beyond the MCP context.

```json
{
  "name": "get_supported_currencies"
}
```

--------------------------------

### Request Schema for Historical Exchange Rates (From Start Date)

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

Defines the request structure for fetching historical exchange rates from a specified start date up to the latest available rates. Only `base_currency` and `start_date` are required.

```json
{
  "base_currency": "USD",
  "start_date": "2025-01-01"
}
```

--------------------------------

### Run Local API Server with Docker Compose

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Start the MCP server and the local Frankfurter API server using Docker Compose with the 'local_api' profile. This is useful for local development and testing.

```bash
FRANKFURTER_API_URL=http://frankfurter_api:8080/v1 docker compose --profile local_api up --build frankfurtermcp frankfurter_api
```

--------------------------------

### Custom Frankfurter API Configuration

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Example .env file content for configuring a custom or self-hosted Frankfurter API endpoint and adjusting HTTP client timeout.

```env
FRANKFURTER_API_URL=http://internal-api.company.local/v1
HTTPX_TIMEOUT=15.0
SSL_CERT_FILE=/etc/ssl/certs/company-ca.pem
```

--------------------------------

### OneOf Validation Example

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Configuration values such as LOG_LEVEL must be one of the predefined acceptable values. Validation is case-insensitive.

```python
# LOG_LEVEL must be one of the specified values
LOG_LEVEL = DEBUG    # ✓ Valid (case-insensitive)
LOG_LEVEL = INFO     # ✓ Valid
LOG_LEVEL = VERBOSE  # ✗ ValidationError
```

--------------------------------

### Run MCP Inspector with FrankfurterMCP

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Executes the MCP Inspector to connect to and test the FrankfurterMCP server. This command assumes Node.js is installed and npx is available.

```bash
npx @modelcontextprotocol/inspector uv run frankfurtermcp
```

--------------------------------

### Range Validation Example

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Configuration values like HTTPX_TIMEOUT are validated against specified ranges. Values outside the valid range will raise a ValidationError.

```python
# HTTPX_TIMEOUT must be between 5.0 and 60.0
HTTPX_TIMEOUT = 2.0  # ✗ ValidationError
HTTPX_TIMEOUT = 5.0  # ✓ Valid
HTTPX_TIMEOUT = 30.0 # ✓ Valid
HTTPX_TIMEOUT = 61.0 # ✗ ValidationError
```

--------------------------------

### MCP Call for Latest Exchange Rates

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

An example of an MCP client call to the 'get_latest_exchange_rates' tool, specifying the base currency and a list of target symbols.

```json
{
  "name": "get_latest_exchange_rates",
  "arguments": {
    "base_currency": "USD",
    "symbols": ["EUR", "GBP", "JPY"]
  }
}
```

--------------------------------

### Create and Run Frankfurter MCP App

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/server.md

Demonstrates how to create a FastMCP application instance using the `app()` function and then run it with different transports like stdio or serve it as an ASGI application.

```python
from frankfurtermcp.server import app

# Create the application
mcp_app = app()

# Use with different transports
mcp_app.run(transport="stdio")  # Run with stdio transport

# Or serve as HTTP/ASGI
from fastmcp import FastMCP
asgi = mcp_app.http_app(transport="sse")
```

--------------------------------

### Using httpx.Client as a Context Manager

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/http-helper-mixin.md

Demonstrates the recommended usage of the httpx.Client instance obtained from get_httpx_client() within a 'with' statement to ensure resources are properly managed and closed after use.

```python
with self.get_httpx_client() as client:
    # Make requests
    response = client.get("https://api.example.com/endpoint")
    response.raise_for_status()  # Raise exception on HTTP errors
```

--------------------------------

### Configure HTTP Client Timeout and SSL Verification

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Shows how to set the HTTPX_TIMEOUT and HTTPX_VERIFY_SSL configuration values when initializing an httpx.Client.

```python
from frankfurtermcp import EnvVar
import httpx

client = httpx.Client(
    timeout=EnvVar.HTTPX_TIMEOUT,
    verify=EnvVar.HTTPX_VERIFY_SSL
)
```

--------------------------------

### Using CurrencyConversionResponse

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/types.md

Demonstrates how to create an instance of the CurrencyConversionResponse model, serialize it to JSON for API responses, and access its fields. Ensure necessary imports are present.

```python
from frankfurtermcp.model import CurrencyConversionResponse

# Create instance
conversion = CurrencyConversionResponse(
    from_currency="USD",
    to_currency="EUR",
    amount=100.0,
    converted_amount=92.0,
    exchange_rate=0.92,
    rate_date="2025-06-15"
)

# Serialize to JSON (for API response)
json_data = conversion.model_dump()
# Output: {
#     "from_currency": "USD",
#     "to_currency": "EUR",
#     "amount": 100.0,
#     "converted_amount": 92.0,
#     "exchange_rate": 0.92,
#     "rate_date": "2025-06-15"
# }

# Serialize to JSON string
json_str = conversion.model_dump_json()

# Access fields
print(conversion.converted_amount)  # 92.0
print(conversion.exchange_rate)     # 0.92
```

--------------------------------

### Create and Serialize ResponseMetadata Instance

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/types.md

Demonstrates how to instantiate the ResponseMetadata model with specific values and then serialize it into a dictionary format, suitable for inclusion in a tool's metadata field.

```python
from frankfurtermcp.model import ResponseMetadata
from datetime import date

# Create metadata for a cached API response
metadata = ResponseMetadata(
    version="0.4.5",
    api_url="https://api.frankfurter.dev/v1/latest",
    api_status_code=200,
    api_bytes_downloaded=512,
    api_elapsed_time=45000,  # 45 milliseconds in microseconds
    cached_response=True
)

# Serialize to dict (for tool response meta field)
meta_dict = metadata.model_dump()

# Example meta dict structure
# {
#     "version": "0.4.5",
#     "api_url": "https://api.frankfurter.dev/v1/latest",
#     "api_status_code": 200,
#     "api_bytes_downloaded": 512,
#     "api_elapsed_time": 45000,
#     "cached_response": True
# }
```

--------------------------------

### Making Multiple Requests with the Same Client

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/http-helper-mixin.md

Illustrates how to perform multiple HTTP requests using the same httpx.Client instance obtained from get_httpx_client(). This allows for connection pooling and efficient reuse of resources.

```python
with self.get_httpx_client() as client:
    # First request
    rates = client.get("https://api.frankfurter.dev/v1/latest", 
                       params={"base": "USD"})
    
    # Second request
    historical = client.get("https://api.frankfurter.dev/v1/2025-01-01",
                            params={"base": "USD"})
    
    # Both requests use same client and connection pool
```

--------------------------------

### Get Supported Currencies

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/frankfurter-mcp.md

Retrieves a list of three-letter currency codes supported by the Frankfurter API. The tool is invoked by MCP clients.

```python
# The tool is invoked by MCP clients
# Returns: {"AED", "AFN", "ALL", "AMD", ..., "ZWL"}
```

--------------------------------

### Typical MCP Mixin Usage Pattern

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/mcp-mixin.md

Illustrates a common pattern for integrating MCPMixin with HTTPHelperMixin in a server class. This includes defining tools, performing HTTP requests within a context, and returning formatted responses.

```python
class MyServer(MCPMixin, HTTPHelperMixin):
    tools = [
        {"fn": "my_tool", "tags": ["example"]},
    ]
    
    async def my_tool(self, ctx: Context, param: str):
        # Perform work
        with self.get_httpx_client() as client:
            response = client.get("https://api.example.com/data")
            data = response.json()
        
        # Return formatted response with metadata
        return self.get_response_content(
            response=data,
            http_response=response
        )

# Initialize and register
mcp = FastMCP(name="my-server")
server = MyServer()
server.register_features(mcp)
```

--------------------------------

### Programmatic Server Configuration

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/server.md

Configure server host, port, transport, and CORS origins using environment variables before running the main server function. Ensure necessary imports are present.

```python
if __name__ == "__main__":
    import os
    
    # Configure via environment variables
    os.environ["FASTMCP_HOST"] = "127.0.0.1"
    os.environ["FASTMCP_PORT"] = "8000"
    os.environ["MCP_SERVER_TRANSPORT"] = "sse"
    os.environ["CORS_MIDDLEWARE_ALLOW_ORIGINS"] = "localhost,127.0.0.1"
    
    from frankfurtermcp.server import main
    main()
```

--------------------------------

### Get Response Content with Metadata

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/mcp-mixin.md

Illustrates the signature for the get_response_content method, which converts various response types into a ToolResult format, optionally including HTTP response metadata.

```python
from frankfurtermcp.model import CurrencyConversionResponse

```

--------------------------------

### Set Configuration via Shell Environment

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Configuration values can be set as shell environment variables before running the application. This method allows for dynamic configuration at runtime.

```bash
export LOG_LEVEL=DEBUG
export FASTMCP_HOST=127.0.0.1
export FASTMCP_PORT=9000
export MCP_SERVER_TRANSPORT=sse

# Then run the server
frankfurtermcp
```

--------------------------------

### Get Historical Exchange Rates

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/frankfurter-mcp.md

Retrieve historical exchange rates for a specified base currency and date range. Results are cached, and if exact dates are unavailable, the closest preceding date's rates are used.

```python
async def get_historical_exchange_rates(
    self,
    ctx: Context,
    base_currency: Annotated[ISO4217, Field(description="..." )],
    symbols: Annotated[list[ISO4217] | ISO4217 | None, Field(description="..." )] = None,
    specific_date: Annotated[date | None, Field(default=None, description="..." )] = None,
    start_date: Annotated[date | None, Field(default=None, description="..." )] = None,
    end_date: Annotated[date | None, Field(default=None, description="..." )] = None,
) -> ToolResult
```

```python
# Get rates for USD from 2025-01-01 to 2025-06-15
result = {
    "base": "USD",
    "start_date": "2025-01-01",
    "end_date": "2025-06-15",
    "rates": {
        "2025-01-01": {"EUR": 0.91, "GBP": 0.78, ...},
        "2025-01-02": {"EUR": 0.915, "GBP": 0.785, ...},
        ...
    }
}
```

--------------------------------

### Configure TTL and LRU Caches

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Illustrates how to use environment variables like TTL_CACHE_TTL_SECONDS and LRU_CACHE_MAX_SIZE to configure TTLCache and LRUCache instances.

```python
from frankfurtermcp import EnvVar, ttl_cache, lru_cache

# TTL cache with configured size and TTL
# TTL cache with configured size and TTL
ttl_cache = TTLCache(
    EnvVar.TTL_CACHE_MAX_SIZE,
    EnvVar.TTL_CACHE_TTL_SECONDS
)

# LRU cache with configured size
lru_cache = LRUCache(EnvVar.LRU_CACHE_MAX_SIZE)
```

--------------------------------

### Get Latest Exchange Rates

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/frankfurter-mcp.md

Fetches the latest exchange rates for specified currencies against a base currency. Results are cached with a default TTL of 15 minutes. This can be used for all supported currencies or filtered by specific symbols.

```python
# Returns rates for USD base currency for all supported currencies
# Or for specific symbols only
result = {
    "base": "USD",
    "date": "2025-06-15",
    "rates": {
        "EUR": 0.92,
        "GBP": 0.79,
        "JPY": 157.45,
        ...
    }
}
```

--------------------------------

### Using Package Name as Metadata Key

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/common.md

Illustrates how to use the AppMetadata.PACKAGE_NAME constant as a key for storing metadata within a tool response.

```python
from frankfurtermcp.common import AppMetadata

# Meta field in tool response uses the package name as key
tool_result.meta = {
    AppMetadata.PACKAGE_NAME: {  # Key is "frankfurtermcp"
        "version": "0.4.5",
        "api_url": "...",
        ...
    }
}
```

--------------------------------

### Response Schema for Historical Exchange Rates (Date Range)

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

Shows the structure of a response for historical rates over a date range. It includes the base currency, start and end dates, and a nested dictionary where keys are dates and values are rate objects.

```json
{
  "base": "USD",
  "start_date": "2025-01-01",
  "end_date": "2025-06-15",
  "rates": {
    "2025-01-01": {"EUR": 0.91, "GBP": 0.78},
    "2025-01-02": {"EUR": 0.915, "GBP": 0.785},
    ...
    "2025-06-15": {"EUR": 0.92, "GBP": 0.79}
  }
}
```

--------------------------------

### Register Middleware in FastMCP Application

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/middleware.md

Shows how to integrate both StripUnknownArgumentsMiddleware and RequestSizeLimitMiddleware into a FastMCP application during its initialization.

```python
# In frankfurtermcp/server.py:app() function

mcp_app = FastMCP(...)
mcp_obj = FrankfurterMCP()
app_with_features = mcp_obj.register_features(mcp_app)
```

--------------------------------

### greet

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/frankfurter-mcp.md

Provides a simple greeting message. This tool is primarily for internal testing and demonstrating middleware functionality.

```APIDOC
## greet

### Description
A simple greeting tool used primarily for internal testing and to demonstrate middleware functionality.

### Method
GET (assumed, as it retrieves a greeting)

### Endpoint
/greet

### Parameters
#### Query Parameters
- **name** (str | None) - Optional - Name for the greeting. Defaults to "World" if not provided.

### Response
#### Success Response (200)
- **message** (string) - The greeting message.

### Response Example
```json
"Hello, World from Frankfurter MCP!"
```

### Response Example with Name
```json
"Hello, Alice from Frankfurter MCP!"
```
```

--------------------------------

### Registering RateLimitingMiddleware with Environment Variables

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/middleware.md

Register `RateLimitingMiddleware` using `add_middleware`, configuring maximum requests per second and burst capacity via environment variables. Ensure the environment variables are set for desired rate limiting behavior.

```python
app_with_features.add_middleware(
    RateLimitingMiddleware(
        max_requests_per_second=EnvVar.RATE_LIMIT_MAX_REQUESTS_PER_SECOND,
        burst_capacity=EnvVar.RATE_LIMIT_BURST_CAPACITY,
    )
)
```

--------------------------------

### Load Configuration from .env File

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Environment variables can be defined in a .env file in the working directory. The Env() instance automatically loads these variables.

```env
LOG_LEVEL=DEBUG
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=8000
MCP_SERVER_TRANSPORT=sse
FRANKFURTER_API_URL=https://api.frankfurter.dev/v1
HTTPX_TIMEOUT=10.0
TTL_CACHE_TTL_SECONDS=1800
RATE_LIMIT_MAX_REQUESTS_PER_SECOND=20.0
REQUEST_SIZE_LIMIT_BYTES=204800
```

--------------------------------

### get_httpx_client

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/http-helper-mixin.md

Creates and returns a configured httpx.Client instance. This client is designed to be used as a context manager and respects various environment variables for SSL configuration, timeouts, and proxy settings.

```APIDOC
## get_httpx_client

### Description
Creates and returns a configured `httpx.Client` instance for making HTTP requests. This method is intended to be used within a `with` statement to ensure proper resource management.

### Method
`get_httpx_client(self) -> httpx.Client`

### Parameters
None

### Returns
`httpx.Client` - A fully configured HTTP client instance.

### Configuration Details
- **verify**: Configured by `EnvVar.HTTPX_VERIFY_SSL`. Can be `False` to disable verification or an SSL context for custom certificates.
- **follow_redirects**: Set to `True` to automatically follow HTTP redirects.
- **trust_env**: Set to `True` to respect environment variables like HTTP proxies.
- **timeout**: Configured by `EnvVar.HTTPX_TIMEOUT`. Defaults to 5.0 seconds, with a range of 5.0-60.0 seconds.
- **cafile**: Path to CA certificate file, sourced from `SSL_CERT_FILE` environment variable or certifi default.
- **capath**: Path to a directory containing CA certificates, sourced from `SSL_CERT_DIR` environment variable.

### SSL Configuration
SSL context is created using `ssl.create_default_context()`, loading CA certificates from `SSL_CERT_FILE`, `SSL_CERT_DIR`, or `certifi.where()`. If `HTTPX_VERIFY_SSL` is `False`, SSL verification is bypassed with a logged warning.

### Usage Example
```python
from frankfurtermcp.mixin import HTTPHelperMixin

class MyService(HTTPHelperMixin):
    pass

service = MyService()

with service.get_httpx_client() as client:
    response = client.get("https://api.example.com/data")
    data = response.json()
    print(response.status_code)
    print(data)
```

### Environment Variables
- `HTTPX_TIMEOUT` (float): Request timeout in seconds (default: 5.0, range: 5.0-60.0).
- `HTTPX_VERIFY_SSL` (bool): Enable/disable SSL certificate verification (default: True).
- `SSL_CERT_FILE` (str): Path to CA certificate file.
- `SSL_CERT_DIR` (str): Path to directory containing CA certificates.

These environment variables are read at client creation time.
```

--------------------------------

### Instantiate Frankfurter MCP Application Programmatically

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/README.md

Python code to import and create an instance of the Frankfurter MCP application.

```python
from frankfurtermcp.server import app, main
mcp_app = app()
```

--------------------------------

### MCP Server Configuration for stdio Transport (uv run)

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

JSON configuration for running the FrankfurterMCP server with the 'uv run' command and 'stdio' transport. This is suitable for integration with tools like Claude Desktop or VS Code.

```json
{
    "command": "uv",
    "args": [
        "run",
        "frankfurtermcp"
    ]
}
```

--------------------------------

### Greet

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

A simple greeting tool for testing and validation. It returns a personalized greeting message.

```APIDOC
## POST /greet

### Description
Provides a simple greeting, typically used for internal testing and middleware validation. It can include a custom name.

### Method
POST

### Endpoint
/greet

### Parameters
#### Request Body
- **name** (string) - Optional - The name to include in the greeting. Defaults to "World" if not provided.

### Request Example
```json
{
  "name": "Alice"
}
```

### Response
#### Success Response (200 OK)
- **content** (array) - Contains the greeting message.
- **structured_content** (object) - Contains the greeting result.

#### Response Example
```json
{
  "content": [{"type": "text", "text": "Hello, Alice from Frankfurter MCP!"}],
  "structured_content": {"result": "Hello, Alice from Frankfurter MCP!"}
}
```
```

--------------------------------

### Handling Different Response Types with get_response_content

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/mcp-mixin.md

Demonstrates how to use `get_response_content` with Pydantic models, dictionaries, and strings. Ensure the response type is supported.

```python
conversion = CurrencyConversionResponse(
    from_currency="USD",
    to_currency="EUR",
    amount=100.0,
    converted_amount=92.0,
    exchange_rate=0.92,
    rate_date="2025-06-15"
)
result = self.get_response_content(
    response=conversion,
    http_response=http_response,
    cached_response=True
)

# Response from dictionary
data = {"status": "ok", "value": 42}
result = self.get_response_content(response=data)

# Response from string
result = self.get_response_content(response="Hello, World!")
```

--------------------------------

### Registering MCP Tools

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/endpoints.md

Tools are registered using the 'tools' class variable on the FrankfurterMCP class. Each tool is defined as a dictionary with a 'fn' key specifying the function name.

```python
class FrankfurterMCP(MCPMixin, HTTPHelperMixin):
    tools = [
        {"fn": "get_supported_currencies", ...},
        {"fn": "get_latest_exchange_rates", ...},
        {"fn": "convert_currency_latest", ...},
        {"fn": "get_historical_exchange_rates", ...},
        {"fn": "convert_currency_specific_date", ...},
        {"fn": "greet", ...},
    ]
```

--------------------------------

### File Locations

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/MANIFEST.md

Lists the directory structure and the location of all documentation files within the project.

```markdown
/workspace/home/output/
├── README.md                      # Start here
├── INDEX.md                       # Navigation guide
├── MANIFEST.md                    # This file
├── configuration.md               # Configuration reference
├── types.md                       # Data models
├── endpoints.md                   # Tool definitions
└── api-reference/
    ├── frankfurter-mcp.md        # Main class
    ├── mcp-mixin.md              # Tool registration
    ├── http-helper-mixin.md      # HTTP client
    ├── middleware.md              # Request processing
    ├── server.md                 # App creation
    └── common.md                 # Metadata
```

--------------------------------

### Registering StripUnknownArgumentsMiddleware

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/middleware.md

Use `add_middleware` to register `StripUnknownArgumentsMiddleware` for automatically stripping unknown arguments from requests. This is a straightforward registration.

```python
app_with_features.add_middleware(StripUnknownArgumentsMiddleware())
```

--------------------------------

### Frankfurter MCP Class Hierarchy

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/README.md

Illustrates the class hierarchy of the Frankfurter MCP server, showing its inheritance from MCPMixin and HTTPHelperMixin.

```text
FrankfurterMCP
├── MCPMixin (tool/resource/prompt registration)
└── HTTPHelperMixin (HTTP client management)
```

--------------------------------

### Security Warning: Binding to 0.0.0.0

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/server.md

This warning is logged when the server is configured to listen on all network interfaces, which is not recommended for production due to security risks.

```text
The server is configured to listen on all IPs ('0.0.0.0'), which may expose it to 
external network traffic. This is not recommended for production deployments due to 
security risks. Should you need to expose the server to external traffic, consider 
using a reverse proxy with proper security measures in place.
```

--------------------------------

### Access Request Size Limit in Middleware

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

Demonstrates how to access the REQUEST_SIZE_LIMIT_BYTES environment variable to configure the RequestSizeLimitMiddleware.

```python
from frankfurtermcp import EnvVar

middleware = RequestSizeLimitMiddleware(
    app,
    max_body_size=EnvVar.REQUEST_SIZE_LIMIT_BYTES
)
```

--------------------------------

### Generate Test Coverage Report

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Invoke the `just test-coverage` command to run all tests and generate a comprehensive coverage report. The report includes metrics like statements, misses, and coverage percentage.

```bash
just test-coverage
```

--------------------------------

### Use Self-Hosted Frankfurter API

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/README.md

Configure environment variables to use a self-hosted Frankfurter API. This involves specifying the API URL and providing a path to the SSL certificate file.

```env
FRANKFURTER_API_URL=http://internal-api.company.local/v1
SSL_CERT_FILE=/etc/ssl/certs/company-ca.pem
```

--------------------------------

### Load Configuration from Custom Path

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/configuration.md

To load environment variables from a specific directory other than the current working directory, change the current working directory before importing the EnvVar class.

```python
import os
os.chdir("/path/to/config/directory")

from frankfurtermcp import EnvVar
```

--------------------------------

### MCP Server Configuration for stdio Transport (python3.12 module)

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

JSON configuration for running the FrankfurterMCP server using a specific Python interpreter and module. This is an alternative to the 'uv run' command for systems requiring direct Python execution.

```json
{
    "command": "python3.12",
    "args": [
        "-m",
        "frankfurtermcp.server"
    ]
}
```

--------------------------------

### get_supported_currencies

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/README.md

Returns a list of three-letter ISO 4217 currency codes supported by the tool.

```APIDOC
## get_supported_currencies

### Description
Returns a list of three-letter ISO 4217 currency codes.

### Method
GET (Assumed, as it retrieves data and requires no parameters)

### Endpoint
/get_supported_currencies

### Parameters

No parameters required.

### Response
#### Success Response (200)
- A list of strings, where each string is a three-letter ISO 4217 currency code.

#### Response Example
```json
["USD", "EUR", "GBP"]
```
```

--------------------------------

### Run Tests with Pytest

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/README.md

Execute all provided test cases using pytest. Add the `--capture=tee-sys` flag for additional console output.

```bash
uv run --group test pytest tests/
```

--------------------------------

### RequestSizeLimitMiddleware dispatch Method

Source: https://github.com/anirbanbasu/frankfurtermcp/blob/master/_autodocs/api-reference/middleware.md

Processes HTTP requests, checking the Content-Length header against the configured max_body_size. Returns a 413 response if the limit is exceeded.

```python
async def dispatch(self, request, call_next)
```