microfish 0.1.0__py3-none-any.whl

microfish/auth.py

@@ -0,0 +1,92 @@
+import contextlib
+import hmac
+from collections.abc import Iterator
+from contextvars import ContextVar
+
+from starlette.middleware import Middleware
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from microfish.settings import Settings
+
+current_tinyfish_api_key: ContextVar[str | None] = ContextVar(
+    "current_tinyfish_api_key",
+    default=None,
+)
+current_mcp_authenticated: ContextVar[bool] = ContextVar(
+    "current_mcp_authenticated",
+    default=False,
+)
+
+
+class AuthenticationError(ValueError):
+    pass
+
+
+def parse_bearer_token(authorization: str | None) -> str | None:
+    if not authorization:
+        return None
+    scheme, separator, token = authorization.strip().partition(" ")
+    if separator != " " or scheme.lower() != "bearer":
+        return None
+    cleaned = token.strip()
+    return cleaned or None
+
+
+def require_api_key() -> str:
+    token = current_tinyfish_api_key.get()
+    if not token:
+        raise AuthenticationError("Missing Authorization Bearer token")
+    return token
+
+
+def require_mcp_authentication() -> None:
+    if not current_mcp_authenticated.get():
+        raise AuthenticationError("Missing or invalid Authorization Bearer token")
+
+
+@contextlib.contextmanager
+def local_mcp_authentication() -> Iterator[None]:
+    tinyfish_context = current_tinyfish_api_key.set(None)
+    mcp_context = current_mcp_authenticated.set(True)
+    try:
+        yield
+    finally:
+        current_tinyfish_api_key.reset(tinyfish_context)
+        current_mcp_authenticated.reset(mcp_context)
+
+
+def mask_token(token: str | None) -> str:
+    if not token:
+        return "<empty>"
+    if len(token) <= 8:
+        return "<redacted>"
+    return f"{token[:4]}...{token[-4:]}"
+
+
+class BearerTokenMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, settings: Settings) -> None:
+        super().__init__(app)
+        self.settings = settings
+
+    @classmethod
+    def as_starlette_middleware(cls, settings: Settings) -> Middleware:
+        return Middleware(cls, settings=settings)
+
+    async def dispatch(self, request, call_next):
+        token = parse_bearer_token(request.headers.get("authorization"))
+        tinyfish_context = current_tinyfish_api_key.set(None)
+        mcp_context = current_mcp_authenticated.set(False)
+        try:
+            if self.settings.polling_enabled:
+                expected = self.settings.mcp_auth_token
+                authenticated = expected is None or (
+                    token is not None and hmac.compare_digest(token, expected)
+                )
+                current_mcp_authenticated.set(authenticated)
+            else:
+                current_tinyfish_api_key.set(token)
+                current_mcp_authenticated.set(token is not None)
+            return await call_next(request)
+        finally:
+            current_tinyfish_api_key.reset(tinyfish_context)
+            current_mcp_authenticated.reset(mcp_context)

microfish/server.py

@@ -0,0 +1,87 @@
+import argparse
+import contextlib
+
+import uvicorn
+from mcp.server.fastmcp import FastMCP
+from starlette.applications import Starlette
+from starlette.responses import JSONResponse
+from starlette.routing import Mount, Route
+
+from microfish.auth import BearerTokenMiddleware, local_mcp_authentication
+from microfish.settings import Settings, load_settings
+from microfish.tinyfish_client import TinyFishClient
+from microfish.tools import TinyFishToolExecutor, register_tools
+
+
+async def health_check(request):
+    return JSONResponse({"status": "ok"})
+
+
+def create_mcp(settings: Settings, client: TinyFishClient | None = None) -> FastMCP:
+    mcp = FastMCP(
+        "microfish",
+        stateless_http=True,
+        json_response=True,
+        streamable_http_path=settings.mcp_path,
+    )
+    resolved_client = client or TinyFishClient.from_settings(settings)
+    register_tools(mcp, TinyFishToolExecutor(settings, resolved_client))
+    return mcp
+
+
+def create_app(settings: Settings | None = None, client: TinyFishClient | None = None) -> Starlette:
+    resolved_settings = settings or load_settings()
+    mcp = create_mcp(resolved_settings, client)
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app):
+        async with mcp.session_manager.run():
+            yield
+
+    return Starlette(
+        routes=[
+            Route("/health", health_check, methods=["GET"]),
+            Mount("/", app=mcp.streamable_http_app()),
+        ],
+        middleware=[BearerTokenMiddleware.as_starlette_middleware(resolved_settings)],
+        lifespan=lifespan,
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(prog="microfish")
+    parser.add_argument("--transport", choices=("http", "stdio"), default=None)
+    return parser.parse_args()
+
+
+def settings_from_args() -> Settings:
+    settings = load_settings()
+    args = parse_args()
+    if args.transport is None:
+        return settings
+    return settings.model_copy(update={"transport": args.transport})
+
+
+def run_http(settings: Settings) -> None:
+    uvicorn.run(
+        create_app(settings),
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level,
+    )
+
+
+def run_stdio(settings: Settings) -> None:
+    if not settings.polling_enabled:
+        raise RuntimeError("stdio transport requires TINYFISH_KEYS")
+    mcp = create_mcp(settings)
+    with local_mcp_authentication():
+        mcp.run(transport="stdio")
+
+
+def main() -> None:
+    settings = settings_from_args()
+    if settings.transport == "stdio":
+        run_stdio(settings)
+        return
+    run_http(settings)

microfish/settings.py

@@ -0,0 +1,65 @@
+from typing import Annotated, Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
+
+TransportMode = Literal["http", "stdio"]
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="MICROFISH_", populate_by_name=True)
+
+    host: str = "0.0.0.0"
+    port: int = 8000
+    mcp_path: str = "/mcp"
+    transport: TransportMode = "http"
+    tinyfish_search_url: str = "https://api.search.tinyfish.ai"
+    tinyfish_fetch_url: str = "https://api.fetch.tinyfish.ai"
+    request_timeout_seconds: float = Field(default=30.0, gt=0)
+    log_level: str = "info"
+    tinyfish_keys: Annotated[list[str], NoDecode] = Field(
+        default_factory=list,
+        validation_alias="TINYFISH_KEYS",
+        repr=False,
+    )
+    mcp_auth_token: str | None = Field(
+        default=None,
+        validation_alias="MCP_AUTH_TOKEN",
+        repr=False,
+    )
+
+    @field_validator("tinyfish_keys", mode="before")
+    @classmethod
+    def parse_tinyfish_keys(cls, value: object) -> list[str]:
+        if value is None:
+            return []
+        if isinstance(value, str):
+            return [key.strip() for key in value.split(",") if key.strip()]
+        if isinstance(value, list):
+            return [str(key).strip() for key in value if str(key).strip()]
+        return []
+
+    @field_validator("mcp_auth_token", mode="before")
+    @classmethod
+    def normalize_mcp_auth_token(cls, value: object) -> str | None:
+        if value is None:
+            return None
+        cleaned = str(value).strip()
+        return cleaned or None
+
+    @field_validator("transport", mode="before")
+    @classmethod
+    def normalize_transport(cls, value: object) -> object:
+        if value is None:
+            return "http"
+        if isinstance(value, str):
+            return value.strip().lower()
+        return value
+
+    @property
+    def polling_enabled(self) -> bool:
+        return bool(self.tinyfish_keys)
+
+
+def load_settings() -> Settings:
+    return Settings()

microfish/tinyfish_client.py

@@ -0,0 +1,209 @@
+from typing import Any, Literal
+
+import httpx
+from pydantic import BaseModel, Field, HttpUrl, field_validator
+
+from microfish.settings import Settings
+
+
+class TinyFishApiError(RuntimeError):
+    def __init__(self, status_code: int, code: str, message: str) -> None:
+        super().__init__(f"TinyFish API error {status_code} {code}: {message}")
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "ok": False,
+            "error": {
+                "status_code": self.status_code,
+                "code": self.code,
+                "message": self.message,
+            },
+        }
+
+
+class SearchRequest(BaseModel):
+    query: str = Field(
+        min_length=1,
+        max_length=2000,
+        description="Search query for TinyFish Search.",
+    )
+    location: str | None = Field(
+        default=None,
+        description="Country code for geo-targeted results.",
+    )
+    language: str | None = Field(
+        default=None,
+        description="Language code for result language.",
+    )
+    page: int = Field(
+        default=0,
+        ge=0,
+        le=10,
+        description="Page number for pagination, starting from 0.",
+    )
+    include_thumbnail: bool = Field(
+        default=False,
+        description="When true, include thumbnail_url in search results when available.",
+    )
+
+    def to_query_params(self) -> dict[str, Any]:
+        params = self.model_dump(exclude_none=True)
+        params["include_thumbnail"] = "true" if self.include_thumbnail else "false"
+        return params
+
+
+class FetchRequest(BaseModel):
+    urls: list[HttpUrl] = Field(
+        min_length=1,
+        max_length=10,
+        description="Array of URLs to fetch. Each URL is processed independently.",
+    )
+    format: Literal["markdown", "html", "json"] = Field(
+        default="markdown",
+        description="Output format for extracted content.",
+    )
+    include_html_head: bool = Field(
+        default=False,
+        description="When true and format is html, include a complete HTML document head.",
+    )
+    links: bool = Field(
+        default=False,
+        description="Extract outbound links from each page.",
+    )
+    image_links: bool = Field(
+        default=False,
+        description="Extract image URLs from each page.",
+    )
+
+    @field_validator("urls")
+    @classmethod
+    def reject_duplicate_urls(cls, urls: list[HttpUrl]) -> list[HttpUrl]:
+        normalized = [str(url) for url in urls]
+        if len(normalized) != len(set(normalized)):
+            raise ValueError("urls must not contain duplicates")
+        return urls
+
+
+UsageStatus = Literal["completed", "failed"]
+
+
+class SearchUsageRequest(BaseModel):
+    start_after: str | None = Field(
+        default=None, description="Return records created after this time."
+    )
+    end_before: str | None = Field(
+        default=None, description="Return records created before this time."
+    )
+    status: UsageStatus | None = Field(
+        default=None, description="Filter by completed or failed status."
+    )
+    limit: int = Field(
+        default=100, ge=1, le=1000, description="Page size for search usage records."
+    )
+    page: int = Field(default=1, ge=1, description="Usage page number, starting from 1.")
+
+
+class FetchUsageRequest(BaseModel):
+    start_after: str | None = Field(
+        default=None, description="Return records created after this time."
+    )
+    end_before: str | None = Field(
+        default=None, description="Return records created before this time."
+    )
+    status: UsageStatus | None = Field(
+        default=None, description="Filter by completed or failed status."
+    )
+    limit: int = Field(default=20, ge=1, le=100, description="Page size for fetch usage records.")
+    page: int = Field(default=1, ge=1, description="Usage page number, starting from 1.")
+
+
+class TinyFishClient:
+    def __init__(
+        self,
+        search_url: str,
+        fetch_url: str,
+        timeout_seconds: float,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.search_url = search_url.rstrip("/")
+        self.fetch_url = fetch_url.rstrip("/")
+        self.timeout = httpx.Timeout(timeout_seconds)
+        self.http_client = http_client
+
+    @classmethod
+    def from_settings(cls, settings: Settings) -> "TinyFishClient":
+        return cls(
+            search_url=settings.tinyfish_search_url,
+            fetch_url=settings.tinyfish_fetch_url,
+            timeout_seconds=settings.request_timeout_seconds,
+        )
+
+    async def search(self, api_key: str, request: SearchRequest) -> dict[str, Any]:
+        return await self._request(
+            "GET",
+            self.search_url,
+            api_key,
+            params=request.to_query_params(),
+        )
+
+    async def fetch_content(self, api_key: str, request: FetchRequest) -> dict[str, Any]:
+        payload = request.model_dump(mode="json")
+        return await self._request("POST", self.fetch_url, api_key, json=payload)
+
+    async def get_search_usage(self, api_key: str, request: SearchUsageRequest) -> dict[str, Any]:
+        return await self._request(
+            "GET",
+            f"{self.search_url}/usage",
+            api_key,
+            params=request.model_dump(exclude_none=True),
+        )
+
+    async def list_fetch_usage(self, api_key: str, request: FetchUsageRequest) -> dict[str, Any]:
+        return await self._request(
+            "GET",
+            f"{self.fetch_url}/usage",
+            api_key,
+            params=request.model_dump(exclude_none=True),
+        )
+
+    async def _request(self, method: str, url: str, api_key: str, **kwargs: Any) -> dict[str, Any]:
+        headers = {"X-API-Key": api_key}
+        client = self.http_client or httpx.AsyncClient(timeout=self.timeout)
+        close_client = self.http_client is None
+        try:
+            response = await client.request(method, url, headers=headers, **kwargs)
+            return self._parse_response(response)
+        except httpx.TimeoutException as exc:
+            raise TinyFishApiError(504, "TIMEOUT", "TinyFish request timed out") from exc
+        except httpx.HTTPError as exc:
+            raise TinyFishApiError(502, "UPSTREAM_ERROR", str(exc)) from exc
+        finally:
+            if close_client:
+                await client.aclose()
+
+    def _parse_response(self, response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise TinyFishApiError(
+                response.status_code, "INVALID_JSON", response.text[:200]
+            ) from exc
+
+        if response.is_error:
+            error = payload.get("error") if isinstance(payload, dict) else None
+            code = str(error.get("code", "HTTP_ERROR")) if isinstance(error, dict) else "HTTP_ERROR"
+            message = (
+                str(error.get("message", response.reason_phrase))
+                if isinstance(error, dict)
+                else response.reason_phrase
+            )
+            raise TinyFishApiError(response.status_code, code, message)
+
+        if not isinstance(payload, dict):
+            raise TinyFishApiError(
+                response.status_code, "INVALID_RESPONSE", "Expected a JSON object"
+            )
+        return {"ok": True, "data": payload}

microfish/tool_policy.py

@@ -0,0 +1,167 @@
+from dataclasses import dataclass
+
+FREE_TOOL_NAMES = frozenset(
+    {
+        "search",
+        "fetch_content",
+        "get_search_usage",
+        "list_fetch_usage",
+    }
+)
+
+BLOCKED_TOOL_NAMES = frozenset(
+    {
+        "run_web_automation",
+        "run_web_automation_async",
+        "get_run",
+        "list_runs",
+        "cancel_run",
+        "poll_status",
+        "get_steps",
+        "discover_run",
+        "batch_create",
+        "batch_status",
+        "batch_cancel",
+        "create_browser_session",
+        "list_browser_sessions",
+    }
+)
+
+
+@dataclass(frozen=True)
+class ToolDecision:
+    name: str
+    group: str
+    retained: bool
+    evidence: str
+    risk: str
+
+
+TOOL_MATRIX = (
+    ToolDecision(
+        "search",
+        "Web Search",
+        True,
+        "TinyFish Search API is documented as a free ranked search endpoint",
+        "low",
+    ),
+    ToolDecision(
+        "fetch_content",
+        "Content Extraction",
+        True,
+        "TinyFish Fetch API is documented as a free content extraction endpoint "
+        "supporting up to 10 URLs",
+        "low",
+    ),
+    ToolDecision(
+        "get_search_usage",
+        "Web Search",
+        True,
+        "Search usage endpoint lists historical Search API records without starting automation",
+        "low",
+    ),
+    ToolDecision(
+        "list_fetch_usage",
+        "Content Extraction",
+        True,
+        "Fetch usage endpoint lists historical Fetch API records without starting automation",
+        "low",
+    ),
+    ToolDecision(
+        "run_web_automation",
+        "Agent Automation",
+        False,
+        "Agent automation is a credits-backed surface outside the Search and Fetch gateway",
+        "blocked",
+    ),
+    ToolDecision(
+        "run_web_automation_async",
+        "Agent Automation",
+        False,
+        "Async Agent automation is a credits-backed surface outside the Search and Fetch gateway",
+        "blocked",
+    ),
+    ToolDecision(
+        "get_run",
+        "Automation Run Tracking",
+        False,
+        "Automation run metadata belongs to the Agent surface and is not a Search or Fetch API",
+        "blocked",
+    ),
+    ToolDecision(
+        "list_runs",
+        "Automation Run Tracking",
+        False,
+        "Automation run listing belongs to the Agent surface and is not a Search or Fetch API",
+        "blocked",
+    ),
+    ToolDecision(
+        "cancel_run",
+        "Automation Run Tracking",
+        False,
+        "Automation run cancellation controls Agent jobs and exceeds the free gateway boundary",
+        "blocked",
+    ),
+    ToolDecision(
+        "poll_status",
+        "Automation Run Tracking",
+        False,
+        "Polling run status depends on Agent automation runs and must not be exposed by microfish",
+        "blocked",
+    ),
+    ToolDecision(
+        "get_steps",
+        "Automation Run Tracking",
+        False,
+        "Run step inspection depends on Agent automation runs and must not be exposed by microfish",
+        "blocked",
+    ),
+    ToolDecision(
+        "discover_run",
+        "Automation Run Tracking",
+        False,
+        "Run discovery depends on Agent automation sessions and must not be exposed by microfish",
+        "blocked",
+    ),
+    ToolDecision(
+        "batch_create",
+        "Batch Automation",
+        False,
+        "Batch creation starts automation work outside the Search and Fetch gateway",
+        "blocked",
+    ),
+    ToolDecision(
+        "batch_status",
+        "Batch Automation",
+        False,
+        "Batch status reads automation work outside the Search and Fetch gateway",
+        "blocked",
+    ),
+    ToolDecision(
+        "batch_cancel",
+        "Batch Automation",
+        False,
+        "Batch cancellation controls automation work outside the Search and Fetch gateway",
+        "blocked",
+    ),
+    ToolDecision(
+        "create_browser_session",
+        "Browser Sessions",
+        False,
+        "Browser sessions belong to the Browser API, "
+        "which is outside the free Search and Fetch surfaces",
+        "blocked",
+    ),
+    ToolDecision(
+        "list_browser_sessions",
+        "Browser Sessions",
+        False,
+        "Browser session listing belongs to the Browser API, "
+        "which is outside the free Search and Fetch surfaces",
+        "blocked",
+    ),
+)
+
+
+def retained_tool_names() -> set[str]:
+    return {decision.name for decision in TOOL_MATRIX if decision.retained}

microfish/tools.py

@@ -0,0 +1,237 @@
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Annotated, Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field, ValidationError
+
+from microfish.auth import AuthenticationError, require_api_key, require_mcp_authentication
+from microfish.settings import Settings
+from microfish.tinyfish_client import (
+    FetchRequest,
+    FetchUsageRequest,
+    SearchRequest,
+    SearchUsageRequest,
+    TinyFishApiError,
+    TinyFishClient,
+)
+from microfish.tool_policy import FREE_TOOL_NAMES, retained_tool_names
+
+
+def error_payload(code: str, message: str, details: Any | None = None) -> dict[str, Any]:
+    return {"ok": False, "error": {"code": code, "message": message, "details": details}}
+
+
+def safe_call_error(exc: Exception) -> dict[str, Any]:
+    if isinstance(exc, AuthenticationError):
+        return error_payload("AUTHENTICATION_REQUIRED", str(exc))
+    if isinstance(exc, ValidationError):
+        return error_payload("INVALID_INPUT", "Input validation failed", exc.errors())
+    if isinstance(exc, TinyFishApiError):
+        return exc.to_payload()
+    return error_payload("INTERNAL_ERROR", "Unexpected tool error")
+
+
+def assert_policy_consistent() -> None:
+    retained = retained_tool_names()
+    if retained != FREE_TOOL_NAMES:
+        raise RuntimeError("Tool policy and allowlist are inconsistent")
+
+
+class TinyFishKeyPool:
+    def __init__(self, keys: list[str], max_extra_retries: int = 3) -> None:
+        if not keys:
+            raise ValueError("TinyFish key pool requires at least one key")
+        self._keys = keys
+        self._max_attempts = min(len(keys), max_extra_retries + 1)
+        self._next_index = 0
+        self._lock = asyncio.Lock()
+
+    async def next_attempt_keys(self) -> list[str]:
+        async with self._lock:
+            start_index = self._next_index
+            self._next_index = (self._next_index + 1) % len(self._keys)
+        return [
+            self._keys[(start_index + offset) % len(self._keys)]
+            for offset in range(self._max_attempts)
+        ]
+
+
+class TinyFishToolExecutor:
+    def __init__(self, settings: Settings, client: TinyFishClient) -> None:
+        self.settings = settings
+        self.client = client
+        self.key_pool = (
+            TinyFishKeyPool(settings.tinyfish_keys) if settings.polling_enabled else None
+        )
+
+    async def run(self, operation: Callable[[str], Awaitable[dict[str, Any]]]) -> dict[str, Any]:
+        if not self.settings.polling_enabled:
+            return await operation(require_api_key())
+
+        require_mcp_authentication()
+        if self.key_pool is None:
+            raise AuthenticationError("TinyFish key pool is not configured")
+
+        last_error: TinyFishApiError | None = None
+        for api_key in await self.key_pool.next_attempt_keys():
+            try:
+                return await operation(api_key)
+            except TinyFishApiError as exc:
+                last_error = exc
+
+        if last_error is not None:
+            raise last_error
+        raise TinyFishApiError(502, "UPSTREAM_ERROR", "TinyFish request failed")
+
+    async def search(self, request: SearchRequest) -> dict[str, Any]:
+        return await self.run(lambda api_key: self.client.search(api_key, request))
+
+    async def fetch_content(self, request: FetchRequest) -> dict[str, Any]:
+        return await self.run(lambda api_key: self.client.fetch_content(api_key, request))
+
+    async def get_search_usage(self, request: SearchUsageRequest) -> dict[str, Any]:
+        return await self.run(lambda api_key: self.client.get_search_usage(api_key, request))
+
+    async def list_fetch_usage(self, request: FetchUsageRequest) -> dict[str, Any]:
+        return await self.run(lambda api_key: self.client.list_fetch_usage(api_key, request))
+
+
+def register_tools(mcp: FastMCP, executor: TinyFishToolExecutor) -> None:
+    assert_policy_consistent()
+
+    UsageStatus = Literal["completed", "failed"]
+
+    @mcp.tool(name="search")
+    async def search(
+        query: Annotated[
+            str,
+            Field(
+                min_length=1,
+                max_length=2000,
+                description="Search query, up to 2000 characters.",
+            ),
+        ],
+        location: Annotated[
+            str | None,
+            Field(description="Optional country code for geo-targeted results."),
+        ] = None,
+        language: Annotated[
+            str | None,
+            Field(description="Optional language code for result language."),
+        ] = None,
+        page: Annotated[
+            int,
+            Field(ge=0, le=10, description="Search result page number, starting from 0."),
+        ] = 0,
+        include_thumbnail: Annotated[
+            bool,
+            Field(description="Include thumbnail_url in results when TinyFish has one."),
+        ] = False,
+    ) -> dict[str, Any]:
+        """Search the web through the free TinyFish Search API.
+
+        Returns ranked titles, snippets, URLs, and optional thumbnail URLs.
+        This tool does not start Agent, Browser, batch, or run lifecycle APIs.
+        """
+        try:
+            request = SearchRequest(
+                query=query,
+                location=location,
+                language=language,
+                page=page,
+                include_thumbnail=include_thumbnail,
+            )
+            return await executor.search(request)
+        except Exception as exc:
+            return safe_call_error(exc)
+
+    @mcp.tool(name="fetch_content")
+    async def fetch_content(
+        urls: Annotated[
+            list[str],
+            Field(min_length=1, max_length=10, description="One to ten URLs to fetch."),
+        ],
+        format: Annotated[
+            Literal["markdown", "html", "json"],
+            Field(description="Output format for extracted content."),
+        ] = "markdown",
+        include_html_head: Annotated[
+            bool,
+            Field(description="When format is html, include a complete document head."),
+        ] = False,
+        links: Annotated[
+            bool,
+            Field(description="Extract outbound links from each page."),
+        ] = False,
+        image_links: Annotated[
+            bool,
+            Field(description="Extract image URLs from each page."),
+        ] = False,
+    ) -> dict[str, Any]:
+        """Fetch and extract clean content through the free TinyFish Fetch API.
+
+        Each URL is processed independently; per-URL failures appear in errors.
+        This tool does not create browser sessions or run web automation.
+        """
+        try:
+            request = FetchRequest(
+                urls=urls,
+                format=format,
+                include_html_head=include_html_head,
+                links=links,
+                image_links=image_links,
+            )
+            return await executor.fetch_content(request)
+        except Exception as exc:
+            return safe_call_error(exc)
+
+    @mcp.tool(name="get_search_usage")
+    async def get_search_usage(
+        start_after: Annotated[
+            str | None, Field(description="Optional ISO datetime lower bound.")
+        ] = None,
+        end_before: Annotated[
+            str | None, Field(description="Optional ISO datetime upper bound.")
+        ] = None,
+        status: Annotated[UsageStatus | None, Field(description="completed or failed.")] = None,
+        limit: Annotated[int, Field(ge=1, le=1000, description="Search usage page size.")] = 100,
+        page: Annotated[int, Field(ge=1, description="Usage page number, starting from 1.")] = 1,
+    ) -> dict[str, Any]:
+        """List Search API usage records for audit and troubleshooting."""
+        try:
+            request = SearchUsageRequest(
+                start_after=start_after,
+                end_before=end_before,
+                status=status,
+                limit=limit,
+                page=page,
+            )
+            return await executor.get_search_usage(request)
+        except Exception as exc:
+            return safe_call_error(exc)
+
+    @mcp.tool(name="list_fetch_usage")
+    async def list_fetch_usage(
+        start_after: Annotated[
+            str | None, Field(description="Optional ISO datetime lower bound.")
+        ] = None,
+        end_before: Annotated[
+            str | None, Field(description="Optional ISO datetime upper bound.")
+        ] = None,
+        status: Annotated[UsageStatus | None, Field(description="completed or failed.")] = None,
+        limit: Annotated[int, Field(ge=1, le=100, description="Fetch usage page size.")] = 20,
+        page: Annotated[int, Field(ge=1, description="Usage page number, starting from 1.")] = 1,
+    ) -> dict[str, Any]:
+        """List Fetch API usage records for audit and troubleshooting."""
+        try:
+            request = FetchUsageRequest(
+                start_after=start_after,
+                end_before=end_before,
+                status=status,
+                limit=limit,
+                page=page,
+            )
+            return await executor.list_fetch_usage(request)
+        except Exception as exc:
+            return safe_call_error(exc)

microfish-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: microfish
+Version: 0.1.0
+Summary: A restricted TinyFish MCP gateway for free search and fetch capabilities.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: mcp<2,>=1.12
+Requires-Dist: pydantic-settings<3,>=2.4
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: starlette<1,>=0.37
+Requires-Dist: uvicorn[standard]<1,>=0.30
+Description-Content-Type: text/markdown
+
+<img src=".github/assets/microfish-logo.png" width="128" vertical-align="middle">
+
+# microfish
+
+中文文档: [README_cn.md](README_cn.md)
+
+microfish is a restricted TinyFish MCP gateway. It exposes only the allowlisted TinyFish Search and Fetch related tools.
+
+## Tools
+
+Retained tools:
+- search
+- fetch_content
+- get_search_usage
+- list_fetch_usage
+
+Blocked tool groups:
+- Agent automation
+- Batch automation
+- Browser sessions
+
+## Authentication and running modes
+
+microfish only exposes TinyFish Search and Fetch related APIs. TinyFish Agent, Browser, batch, and run lifecycle APIs are intentionally not registered.
+
+### Get a TinyFish API key
+
+Generate your API key at https://agent.tinyfish.ai/api-keys.
+
+### Client-owned single key
+
+Leave `TINYFISH_KEYS` unset. Each MCP client sends `Authorization: Bearer <YOUR_TINYFISH_API_KEY>`. microfish forwards that value to TinyFish as `X-API-Key` for the current request only.
+
+### Server-managed single key
+
+Set `TINYFISH_KEYS` to one TinyFish API key. MCP clients do not receive the TinyFish key. If `MCP_AUTH_TOKEN` is set, clients send `Authorization: Bearer <YOUR_MCP_AUTH_TOKEN>`; if `MCP_AUTH_TOKEN` is unset, the MCP entrypoint is not protected by a bearer token.
+
+### Server-managed key pool
+
+Set `TINYFISH_KEYS` to multiple comma-separated TinyFish API keys. microfish assigns requests in order. When a whole upstream request fails, it tries the next key, stopping after all available keys for that call are tried or after three extra retries.
+
+## Server configuration
+
+microfish reads runtime settings from environment variables:
+
+- `MICROFISH_HOST`: bind host for the HTTP server. Defaults to `0.0.0.0`.
+- `MICROFISH_PORT`: bind port for the HTTP server. Defaults to `8000`.
+- `MICROFISH_MCP_PATH`: HTTP path that exposes the MCP entrypoint. Defaults to `/mcp`.
+- `MICROFISH_TRANSPORT`: transport for the server. Use http for the HTTP service or stdio for local coding agent subprocesses. Defaults to http.
+- `TINYFISH_KEYS`: comma-separated TinyFish API keys; presence selects server-managed mode.
+- `MCP_AUTH_TOKEN`: optional bearer token required from MCP clients in server-managed mode.
+
+## Client configuration
+
+microfish supports two transports:
+- **HTTP transport** (`MICROFISH_TRANSPORT=http`, the default): run microfish as an HTTP service and connect clients to `http://localhost:8000/mcp`.
+- **stdio transport** (`MICROFISH_TRANSPORT=stdio` or `--transport stdio`): launch `uvx microfish --transport stdio` as a local subprocess for coding agents.
+
+For the HTTP transport, the value of `Authorization: Bearer` depends on your running mode:
+- **Client-owned single key**: set it to your TinyFish API key.
+- **Server-managed single/multiple keys with `MCP_AUTH_TOKEN`**: set it to the MCP auth token.
+- **Server-managed keys without `MCP_AUTH_TOKEN`**: omit the Authorization header entirely.
+
+The stdio transport requires `TINYFISH_KEYS` because there is no separate Authorization header on local subprocess pipes.
+
+### Claude Code
+
+HTTP transport:
+
+```bash
+# Without auth header
+claude mcp add --transport http microfish http://localhost:8000/mcp
+
+# With auth header
+claude mcp add --transport http microfish http://localhost:8000/mcp \
+  --header "Authorization: Bearer <YOUR_MCP_OR_TINYFISH_TOKEN>"
+```
+
+stdio transport:
+
+```bash
+TINYFISH_KEYS=<YOUR_TINYFISH_API_KEY> \
+  claude mcp add microfish --env TINYFISH_KEYS -- uvx microfish --transport stdio
+```
+
+### Codex
+
+HTTP transport:
+
+```toml
+[mcp_servers.microfish]
+url = "http://localhost:8000/mcp"
+bearer_token_env_var = "MICROFISH_MCP_BEARER"
+```
+
+Set `MICROFISH_MCP_BEARER` in your shell environment to your TinyFish API key (client-owned mode) or MCP auth token (server-managed mode).
+
+stdio transport:
+
+```toml
+[mcp_servers.microfish]
+command = "uvx"
+args = ["microfish", "--transport", "stdio"]
+env = { TINYFISH_KEYS = "<YOUR_TINYFISH_API_KEY>" }
+```
+
+### Cursor
+
+HTTP transport:
+
+```json
+{
+  "mcpServers": {
+    "microfish": {
+      "url": "http://localhost:8000/mcp",
+      "headers": {
+        "Authorization": "Bearer ${env:MICROFISH_MCP_BEARER}"
+      }
+    }
+  }
+}
+```
+
+Set `MICROFISH_MCP_BEARER` in your environment to your TinyFish API key (client-owned mode) or MCP auth token (server-managed mode). If no auth token is required, remove the `headers` block.
+
+stdio transport:
+
+```json
+{
+  "mcpServers": {
+    "microfish": {
+      "command": "uvx",
+      "args": ["microfish", "--transport", "stdio"],
+      "env": {
+        "TINYFISH_KEYS": "<YOUR_TINYFISH_API_KEY>"
+      }
+    }
+  }
+}
+```
+
+## Run locally
+
+    uv sync
+    uv run microfish
+
+Or run directly without cloning via `uvx microfish`.
+
+## Docker
+
+Two compose files are provided:
+- `docker-compose.yml` pulls the published image `ghcr.io/vvtommy/microfish:${MICROFISH_IMAGE_TAG:-latest}` from GHCR.
+- `docker-compose_build.yml` builds the local Dockerfile.
+
+Both expose microfish on port 8000. Do not put TinyFish keys directly in compose files; pass them through your deployment environment.
+
+```bash
+docker compose up -d
+claude mcp add --transport http microfish http://localhost:8000/mcp \
+  --header "Authorization: Bearer <YOUR_MCP_OR_TINYFISH_TOKEN>"
+```
+
+## Releasing
+
+Push a SemVer tag of the form `vX.Y.Z` to trigger publish workflows:
+- `.github/workflows/pypi.yml` builds and publishes the Python package to PyPI via PyPI OIDC trusted publishing.
+- `.github/workflows/docker.yml` builds and publishes `ghcr.io/vvtommy/microfish` Docker images with version tags and `latest`.
+
+## MCP endpoint
+
+    http://localhost:8000/mcp

microfish-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+microfish/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+microfish/auth.py,sha256=Jl_mS83-qMVsaMczgucRxVE5ixSRsPukHgHfj813PRc,2901
+microfish/server.py,sha256=_8DUnPiMZnszsUv1Fqsy33woq6zgh1x200aKexW5JwU,2599
+microfish/settings.py,sha256=MrVq4Yfy__F8x3z0FB2r6axuOvTO7UhzHS0qsK7C-H8,2039
+microfish/tinyfish_client.py,sha256=XbEoHAyQxxAm_0x-dwYm86gblR7ycgpxD_RTvIQESnM,7359
+microfish/tool_policy.py,sha256=zkJzfh9UyVrJW1ozRBR41vOOhChP7RwIfhz055hKQpw,4424
+microfish/tools.py,sha256=yYAhXOhoEYQkEFD2v2f0ish86AaYmJoeWGMgi9VeiA0,9114
+microfish-0.1.0.dist-info/METADATA,sha256=maWp-ok3NvfBaY-pRQpmUODfylchDb91LWu5Ekh77bg,5965
+microfish-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+microfish-0.1.0.dist-info/entry_points.txt,sha256=2za57KKNs-41vdsWiCShQjZ0UC5b25IZetrS76pEFoA,52
+microfish-0.1.0.dist-info/licenses/LICENSE,sha256=ObPR6ejmUmc7USfN0ozY7z8luJ_KBPf_MjYpA5HllMc,1063
+microfish-0.1.0.dist-info/RECORD,,

microfish-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

microfish-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+microfish = microfish.server:main

microfish-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vvtommy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.