ZeroChan MCP

Instructions

Queries the Zerochan global feed without any tag filter. Supports sorting by
recency or popularity, filtering by dimensions or color, and pagination.

Args:
    params (BrowseAllInput): Input parameters including:
        - username (str): Your Zerochan username for the User-Agent header (required)
        - page (int): Page number (default: 1)
        - limit (int): Results per page, 1–250 (default: 20)
        - sort (SortOrder): 'id' for recent, 'fav' for popular (default: 'id')
        - time_range (Optional[TimeRange]): '0' all-time, '1' last 7000, '2' last 15000
        - dimensions (Optional[Dimensions]): Filter by image shape
        - color (Optional[str]): Filter by dominant color name
        - response_format (ResponseFormat): 'markdown' or 'json' (default: 'markdown')

Returns:
    str: Paginated list of entries in the requested format.
         Markdown: formatted table with ID, tags, dimensions, favorites, links.
         JSON: raw API response with all fields.

Implementation Reference

• server.py:252-296 (handler)

  Main handler function for zerochan_browse tool. Executes the API call to browse all Zerochan entries with optional filtering by time range, dimensions, color, and supports pagination and sorting. Returns results in either Markdown or JSON format.

  async def zerochan_browse(params: BrowseAllInput) -> str:
      """Browse all Zerochan entries with optional filtering and pagination.
  
      Queries the Zerochan global feed without any tag filter. Supports sorting by
      recency or popularity, filtering by dimensions or color, and pagination.
  
      Args:
          params (BrowseAllInput): Input parameters including:
              - username (str): Your Zerochan username for the User-Agent header (required)
              - page (int): Page number (default: 1)
              - limit (int): Results per page, 1–250 (default: 20)
              - sort (SortOrder): 'id' for recent, 'fav' for popular (default: 'id')
              - time_range (Optional[TimeRange]): '0' all-time, '1' last 7000, '2' last 15000
              - dimensions (Optional[Dimensions]): Filter by image shape
              - color (Optional[str]): Filter by dominant color name
              - response_format (ResponseFormat): 'markdown' or 'json' (default: 'markdown')
  
      Returns:
          str: Paginated list of entries in the requested format.
               Markdown: formatted table with ID, tags, dimensions, favorites, links.
               JSON: raw API response with all fields.
      """
      query: dict = {
          "p": params.page,
          "l": params.limit,
          "s": params.sort.value,
      }
      if params.time_range is not None:
          query["t"] = params.time_range.value
      if params.dimensions is not None:
          query["d"] = params.dimensions.value
      if params.color:
          query["c"] = params.color
  
      try:
          data = await zerochan_get("/", query)
      except Exception as e:
          return handle_api_error(e)
  
      items = data.get("items", data) if isinstance(data, dict) else data
  
      if params.response_format == ResponseFormat.JSON:
          return json.dumps(data, indent=2, ensure_ascii=False)
  
      return format_post_list_markdown(items if isinstance(items, list) else [], "Global Feed")

• server.py:184-194 (schema)

  Input schema (BrowseAllInput) defining the parameters for the zerochan_browse tool. Includes fields for page, limit, sort order, time range, dimensions filter, color filter, and response format with validation constraints.

  class BrowseAllInput(BaseModel):
      """Input for browsing all Zerochan entries."""
      model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
  
      page: int = Field(default=1, description="Page number for pagination (starts at 1)", ge=1)
      limit: int = Field(default=DEFAULT_LIMIT, description="Number of results per page (1–250)", ge=1, le=MAX_LIMIT)
      sort: SortOrder = Field(default=SortOrder.RECENT, description="Sort order: 'id' = most recent, 'fav' = most popular")
      time_range: Optional[TimeRange] = Field(default=None, description="Time range for popularity sort: '0' = all time, '1' = last 7000 entries, '2' = last 15000 entries")
      dimensions: Optional[Dimensions] = Field(default=None, description="Filter by image dimensions: large, huge, landscape, portrait, square")
      color: Optional[str] = Field(default=None, description="Filter by dominant color, e.g. 'red', 'blue', 'green'", max_length=32)
      response_format: ResponseFormat = Field(default=ResponseFormat.MARKDOWN, description="Output format: 'markdown' or 'json'")

• server.py:242-251 (registration)

  Tool registration using @mcp.tool decorator with name 'zerochan_browse' and annotations including title, readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.

  @mcp.tool(
      name="zerochan_browse",
      annotations={
          "title": "Browse All Zerochan Entries",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      }
  )

• server.py:58-86 (helper)

  HTTP client helper function zerochan_get that performs GET requests to the Zerochan API with proper headers, error handling, and JSON response parsing. Used by zerochan_browse to fetch data.

  async def zerochan_get(path: str, params: dict) -> dict:
      """
      Perform a GET request to the Zerochan API.
  
      Args:
          path: URL path (e.g. '/Hatsune+Miku')
          params: Query string parameters (json=True always included)
  
      Returns:
          Parsed JSON response dict
  
      Raises:
          ValueError: If ZEROCHAN_USERNAME env var is not set
          httpx.HTTPStatusError: On non-2xx responses
          httpx.TimeoutException: On request timeout
      """
      if not ZEROCHAN_USERNAME:
          raise ValueError(
              "ZEROCHAN_USERNAME is not set. Add it to your MCP config: "
              '"env": {"ZEROCHAN_USERNAME": "YourUsername"}'
          )
      params["json"] = True
      url = f"{ZEROCHAN_BASE_URL}{path}"
      user_agent = f"zerochan-mcp - {ZEROCHAN_USERNAME}"
  
      async with httpx.AsyncClient(timeout=15.0) as client:
          response = await client.get(url, params=params, headers={"User-Agent": user_agent})
          response.raise_for_status()
          return response.json()

• server.py:111-131 (helper)

  Formatting helper function format_post_list_markdown that transforms API response data into a formatted Markdown table with columns for ID, tags, dimensions, favorites, and links. Used by zerochan_browse for markdown output.

  def format_post_list_markdown(items: list, source: str) -> str:
      """Format a list of post summaries as a Markdown table."""
      if not items:
          return "No results found."
  
      lines = [f"### Zerochan Results from `{source}`\n"]
      lines.append(f"| ID | Tags | Dimensions | Favorites | Full Image |")
      lines.append(f"|---|---|---|---|---|")
  
      for item in items:
          entry_id = item.get("id", "N/A")
          tags = ", ".join(item.get("tags", [])[:5])
          if len(item.get("tags", [])) > 5:
              tags += f" (+{len(item['tags']) - 5} more)"
          width = item.get("width", "?")
          height = item.get("height", "?")
          fav = item.get("fav", "?")
          full_url = item.get("full", f"https://www.zerochan.net/{entry_id}")
          lines.append(f"| [{entry_id}]({full_url}) | {tags} | {width}×{height} | {fav} | [View]({full_url}) |")
  
      return "\n".join(lines)