ipinfo-mcp-server 0.1.9__py3-none-any.whl

ipinfo_mcp/__main__.py

@@ -0,0 +1,3 @@
+from ipinfo_mcp.server import main
+
+main()

ipinfo_mcp/auth.py

@@ -0,0 +1,20 @@
+import contextlib
+
+from fastmcp import Context
+from fastmcp.server.dependencies import get_http_request
+
+
+def get_request_token(ctx: Context) -> str | None:
+    """
+    Get the API token for the current request.
+
+    In HTTP mode: reads Bearer token from the Authorization request header.
+    In stdio mode: falls back to the IPINFO_TOKEN env var stored in lifespan context.
+    """
+    with contextlib.suppress(RuntimeError):
+        request = get_http_request()
+        auth = request.headers.get("authorization", "")
+        if auth.lower().startswith("bearer "):
+            return auth[7:].strip() or None
+        return None
+    return ctx.lifespan_context.get("api_token")

ipinfo_mcp/cache.py

@@ -0,0 +1,81 @@
+import hashlib
+import time
+
+from ipinfo_mcp.types import LiteResponse, LookupResponse, ResproxyResponse
+
+# Any single-IP response that can be cached
+CachedResponse = LiteResponse | LookupResponse | ResproxyResponse | dict[str, object]
+
+# How long an entry stays fresh, in seconds.
+DEFAULT_TTL = 3600.0
+
+
+class IPCache:
+    """
+    In-memory cache of per-IP responses, scoped by token and namespace.
+
+    Namespaces: "lite", "lookup", "resproxy".
+
+    Entries are scoped also using the token that fetched them. The cache is process
+    wide, so if we don't use the token as part of the key we would hand one token's
+    results to another.
+
+    Entries expire after ttl seconds. Expiry is checked on read, and an expired
+    entry is dropped as we find it, so nothing sweeps the store in the background.
+    """
+
+    def __init__(self, ttl: float = DEFAULT_TTL) -> None:
+        self._ttl = ttl
+        # Each entry is (stored_at, data), stored_at coming from a monotonic clock
+        # so that a system clock change can't make an entry look fresh forever.
+        self._store: dict[tuple[str, str, str], tuple[float, CachedResponse]] = {}
+
+    @staticmethod
+    def _hash_token(token: str) -> str:
+        """
+        We don't want to store the token directly, though we still need
+        to scope by token so we derive an hash from it and use it as part
+        of the hash key.
+        """
+        return hashlib.sha256(token.encode()).hexdigest()[:32]
+
+    def _get_fresh(self, key: tuple[str, str, str]) -> CachedResponse | None:
+        """Read an entry by key, dropping and reporting it as a miss if it expired."""
+        entry = self._store.get(key)
+        if entry is None:
+            return None
+
+        stored_at, data = entry
+        if time.monotonic() > stored_at + self._ttl:
+            del self._store[key]
+            return None
+
+        return data
+
+    def get(self, token: str, namespace: str, ip: str) -> CachedResponse | None:
+        """Get this token's cached data for an IP in a namespace. Returns None on miss."""
+        return self._get_fresh((self._hash_token(token), namespace, ip))
+
+    def put(self, token: str, namespace: str, ip: str, data: CachedResponse) -> None:
+        """Store data for an IP in a namespace, scoped to this token."""
+        self._store[(self._hash_token(token), namespace, ip)] = (time.monotonic(), data)
+
+    def get_many(self, token: str, namespace: str, ips: list[str]) -> tuple[dict[str, CachedResponse], list[str]]:
+        """Look up multiple IPs for this token. Returns (cached_results, cache_misses)."""
+        token_hash = self._hash_token(token)
+        cached: dict[str, CachedResponse] = {}
+        misses: list[str] = []
+        for ip in ips:
+            data = self._get_fresh((token_hash, namespace, ip))
+            if data is not None:
+                cached[ip] = data
+            else:
+                misses.append(ip)
+        return cached, misses
+
+    def put_many(self, token: str, namespace: str, items: dict[str, CachedResponse]) -> None:
+        """Store multiple IP results in a namespace, scoped to this token."""
+        token_hash = self._hash_token(token)
+        stored_at = time.monotonic()
+        for ip, data in items.items():
+            self._store[(token_hash, namespace, ip)] = (stored_at, data)

ipinfo_mcp/client.py

@@ -0,0 +1,89 @@
+import logging
+from importlib.metadata import version
+from typing import cast
+
+import httpx
+
+from ipinfo_mcp.types import BatchResponse, MeResponse
+
+logger = logging.getLogger(__name__)
+
+# Maximum number of IPs the batch endpoint accepts
+MAX_BATCH_SIZE = 1000
+
+USER_AGENT = f"IPinfoClient/MCP/{version('ipinfo-mcp-server')}"
+
+
+class IPinfoClient:
+    """
+    Async HTTP client for the IPinfo API.
+
+    Uses the unified /batch endpoint
+    (e.g. "lite/8.8.8.8", "1.1.1.1", "resproxy/2.2.2.2").
+    """
+
+    def __init__(self, base_url: str, legacy_base_url: str) -> None:
+        self._base_url: str = base_url.rstrip("/")
+        self._legacy_base_url: str = legacy_base_url.rstrip("/")
+        self._http: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> "IPinfoClient":
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"Accept": "application/json", "User-Agent": USER_AGENT},
+            timeout=httpx.Timeout(30.0, connect=10.0),
+        )
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        if self._http:
+            await self._http.aclose()
+
+    @property
+    def http(self) -> httpx.AsyncClient:
+        if self._http is None:
+            raise RuntimeError("Client not initialized. Use 'async with' context manager.")
+        return self._http
+
+    async def batch(self, keys: list[str], *, token: str | None = None) -> BatchResponse:
+        """
+        Send a batch request.
+
+        Keys can be prefixed with the endpoint type:
+        - "lite/8.8.8.8" for lite lookups
+        - "8.8.8.8" for full lookups
+        - "resproxy/8.8.8.8" for residential proxy checks
+
+        Response keys match input keys.
+        HTTP errors (403, 429, etc.) are propagated as httpx.HTTPStatusError.
+        """
+        headers: dict[str, str] = {}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        logger.info("POST /batch keys=%d", len(keys))
+        response = await self.http.post("/batch", json=keys, headers=headers)
+        _ = response.raise_for_status()
+        result: BatchResponse = cast(BatchResponse, response.json())
+        return result
+
+    async def me(self, *, token: str | None = None) -> MeResponse:
+        """
+        Get account info and quota via GET /me.
+
+        Note: /me only exists on ipinfo.io, not api.ipinfo.io,
+        so this uses a direct request to the legacy base URL.
+        HTTP errors are propagated as httpx.HTTPStatusError.
+        """
+        headers: dict[str, str] = {"Accept": "application/json", "User-Agent": USER_AGENT}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        logger.info("GET /me")
+        async with httpx.AsyncClient(
+            base_url=self._legacy_base_url,
+            headers=headers,
+            timeout=httpx.Timeout(30.0, connect=10.0),
+        ) as http:
+            response = await http.get("/me")
+            _ = response.raise_for_status()
+            result: MeResponse = cast(MeResponse, response.json())
+            return result

ipinfo_mcp/errors.py

@@ -0,0 +1,121 @@
+from typing import Literal, TypedDict, cast
+
+import httpx
+
+from ipinfo_mcp.cache import CachedResponse
+
+ErrorCode = Literal[
+    "ACCESS_DENIED",
+    "RATE_LIMITED",
+    "INVALID_TOKEN",
+    "NO_TOKEN",
+    "API_ERROR",
+    "UNKNOWN",
+]
+
+
+class ErrorResponse(TypedDict, total=False):
+    code: ErrorCode
+    message: str
+    suggestion: str
+
+
+# We use this mapping to try and infer an error code from the error message
+# received by the REST API.
+# Getting an error code makes it easier to give the model suggestions on how
+# to communicate the error to the user.
+_MESSAGE_ERROR_CODES_MAPPING: list[tuple[str, ErrorCode]] = [
+    ("does not have access", "ACCESS_DENIED"),
+    ("not allowed access from this source", "ACCESS_DENIED"),
+    ("do not have permission", "ACCESS_DENIED"),
+    ("reached your limit", "RATE_LIMITED"),
+    ("too many requests", "RATE_LIMITED"),
+    ("entered your token correctly", "INVALID_TOKEN"),
+    ("unknown token", "INVALID_TOKEN"),
+    ("invalid token", "INVALID_TOKEN"),
+    ("token required", "NO_TOKEN"),
+    ("authentication required", "NO_TOKEN"),
+]
+
+_SUGGESTIONS: dict[ErrorCode, str] = {
+    "ACCESS_DENIED": "Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
+    "RATE_LIMITED": "Tell the user they can upgrade their tier at https://ipinfo.io/pricing",
+    "INVALID_TOKEN": "Tell the user to check their token at https://ipinfo.io/account/token",
+    "NO_TOKEN": "The user didn't set IPINFO_TOKEN. They can get a free token at https://ipinfo.io/signup",
+    "UNKNOWN": "An unforseen error happened, tell the user to report it to https://ipinfo.io/",
+}
+
+
+def _find_error_code(message: str) -> ErrorCode:
+    for chunk, code in _MESSAGE_ERROR_CODES_MAPPING:
+        if chunk in message:
+            return code
+    return "UNKNOWN"
+
+
+def extract_error(entry: CachedResponse) -> ErrorResponse | None:
+    """
+    Pull the error message out of a single batch endpoint response.
+
+    Return None if no error is found.
+
+    The batch endpoint embeds each sub-request's response body verbatim. Nearly all
+    of them carry a flat "error" string, but the generic error handler and the
+    invalid-response guard reply with a bare "message" instead, so fall back to it.
+    """
+    payload = cast(dict[str, str], entry)
+    message = payload.get("error") or payload.get("message")
+    if not message:
+        return None
+    error_code = _find_error_code(message)
+    return ErrorResponse(
+        code=error_code,
+        message=message,
+        suggestion=_SUGGESTIONS[error_code],
+    )
+
+
+def handle_api_error(
+    exc: httpx.HTTPStatusError,
+    *,
+    feature_name: str = "",
+) -> ErrorResponse:
+    """
+    Convert an HTTP error into a user-friendly error response dict.
+
+    Args:
+        exc: The HTTP status error from httpx.
+        feature_name: Human-readable name of the feature that failed.
+    """
+    status = exc.response.status_code
+
+    if status == 403:
+        message = (
+            f"You don't have access to {feature_name}." if feature_name else "You don't have access to this feature."
+        )
+        return ErrorResponse(
+            code="ACCESS_DENIED",
+            message=message,
+            suggestion="Tell the user they can get access by upgrading at https://ipinfo.io/pricing",
+        )
+
+    if status == 429:
+        return ErrorResponse(
+            code="RATE_LIMITED",
+            message="Rate limit exceeded.",
+            suggestion="Tell the user they can upgrade their tier at https://ipinfo.io/pricing",
+        )
+
+    return ErrorResponse(
+        code="API_ERROR",
+        message=f"IPinfo API returned status {status}.",
+    )
+
+
+def no_token_error() -> ErrorResponse:
+    """Error response when no IPINFO_TOKEN is configured."""
+    return ErrorResponse(
+        code="NO_TOKEN",
+        message="No API token configured.",
+        suggestion="The user didn't set IPINFO_TOKEN. They can get a free token at https://ipinfo.io/signup",
+    )