maitabi 1.0.0__py3-none-any.whl

maitabi/__init__.py

@@ -0,0 +1 @@
+"""Maitabi MCP Server package."""

maitabi/__main__.py

@@ -0,0 +1,6 @@
+"""Support `python -m maitabi` — same entrypoint as the `maitabi` script."""
+
+from maitabi.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

maitabi/cli/__init__.py

@@ -0,0 +1 @@
+"""Maitabi CLI package (thin wrapper over core services/models)."""

maitabi/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Support `python -m maitabi.cli`."""
+
+from maitabi.cli.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

maitabi/cli/commands.py

@@ -0,0 +1,75 @@
+"""CLI command dispatch — one generic handler over the action registry.
+
+Flow: argparse namespace → Pydantic Input (CSV/string flags coerced per
+`fields.plan_field`) → `asyncio.run(service())` → JSON to stdout or
+`--output` file. Exit codes: 0 OK, 1 upstream/network error, 2 input error.
+Must NOT import fastmcp/mcp/server/mcp.
+"""
+
+import argparse
+import asyncio
+import json
+import sys
+from collections.abc import Awaitable
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+
+from maitabi.cli.fields import plan_field
+from maitabi.registry import Action
+from maitabi.services.http import close_http_client
+
+EXIT_OK = 0
+EXIT_UPSTREAM_ERROR = 1
+EXIT_INPUT_ERROR = 2
+
+
+def _emit(data: dict[str, Any], args: argparse.Namespace) -> None:
+    """Serialize the service dict to the CLI's JSON wire format.
+
+    Always indent=2 / ensure_ascii=False — byte-identical to the historic
+    output (services used to pre-serialize with the same settings), so
+    `--pretty` stays a compat no-op.
+    """
+    text = json.dumps(data, ensure_ascii=False, indent=2)
+    output = getattr(args, "output", None)
+    if output:
+        with open(output, "w", encoding="utf-8") as f:
+            f.write(text + "\n")
+    else:
+        print(text)
+
+
+async def _run(service_coro: Awaitable[dict[str, Any]]) -> dict[str, Any]:
+    try:
+        return await service_coro
+    finally:
+        await close_http_client()
+
+
+def build_input(action: Action, args: argparse.Namespace) -> BaseModel:
+    """Map the parsed namespace onto the action's Input model.
+
+    Every model field exists as a flag (both are generated from the same
+    model), so this mapping is total; string flags are coerced per plan.
+    """
+    kwargs = {}
+    for name, info in action.input_model.model_fields.items():
+        raw = getattr(args, name, None)
+        plan = plan_field(name, info)
+        if plan.coerce is not None and isinstance(raw, str):
+            raw = plan.coerce(raw)
+        kwargs[name] = raw
+    return action.input_model(**kwargs)
+
+
+def run_action(action: Action, args: argparse.Namespace) -> int:
+    """Execute one action and return its process exit code."""
+    try:
+        payload = build_input(action, args)
+    except (ValidationError, ValueError) as exc:
+        print(f"maitabi: invalid arguments for {action.domain} {action.command}: {exc}", file=sys.stderr)
+        return EXIT_INPUT_ERROR
+    data = asyncio.run(_run(action.service(payload)))
+    _emit(data, args)
+    return EXIT_UPSTREAM_ERROR if "error" in data else EXIT_OK

maitabi/cli/fields.py

@@ -0,0 +1,108 @@
+"""Field-level CLI plan derived from Pydantic `FieldInfo` (presentation + coercion).
+
+Both `parser.py` (argparse flags) and `commands.py` (namespace → Input model)
+go through `plan_field`, so a field's flag type and its coercion can never
+drift apart. Must NOT import fastmcp/mcp/server/mcp.
+"""
+
+import types
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Union, get_args, get_origin
+
+from pydantic.fields import FieldInfo
+
+# Presentation-only metavars for string-ish flags (argparse's default is the
+# uppercased dest, which is noisy for CSV/range inputs).
+_METAVARS = {"day": "DAY", "course_no": "NO", "year_month": "YYYY-MM"}
+
+
+@dataclass(frozen=True)
+class FieldPlan:
+    """How one model field is exposed on the CLI."""
+
+    flag: str  # e.g. "--course-cd"
+    metavar: str | None
+    required: bool
+    default: object
+    arg_type: type | None  # None when store_true
+    store_true: bool
+    choices: list[object] | None
+    coerce: Callable[[str], object] | None  # applied to string input, if any
+
+
+def annotation_members(annotation: object) -> list[object]:
+    """Flatten a (possibly Optional/union) annotation into its members."""
+    if get_origin(annotation) in (Union, types.UnionType):
+        return list(get_args(annotation))
+    return [annotation]
+
+
+def _parse_course_nos(raw: str) -> int | list[int]:
+    """CSV → int when single (single-vs-batch changes the response shape)."""
+    nums = [int(p.strip()) for p in raw.split(",") if p.strip()]
+    return nums[0] if len(nums) == 1 else nums
+
+
+def _parse_id_list(raw: str) -> list[int] | None:
+    if not raw:
+        return None
+    return [int(p.strip()) for p in raw.split(",") if p.strip()]
+
+
+def _enum_of(members: list[object]) -> type[IntEnum] | None:
+    for member in members:
+        if get_origin(member) is None and isinstance(member, type):
+            try:
+                if issubclass(member, IntEnum):
+                    return member
+            except TypeError:  # pragma: no cover - defensive
+                continue
+    return None
+
+
+def plan_field(name: str, info: FieldInfo) -> FieldPlan:
+    """Classify a model field into an argparse flag + string coercion.
+
+    Rules (in precedence order):
+    - bool              → --flag (store_true)
+    - IntEnum (+Optional) → --flag int with enum choices (defaults kept)
+    - plain int (+Optional) → --flag int (model's ge/le validate ranges)
+    - anything else (str, CSV lists, day unions) → --flag str; unions
+      containing str pass through raw (the model parses ranges), CSV list
+      fields coerce to int/list here.
+    """
+    flag = "--" + name.replace("_", "-")
+    metavar = "IDS" if name.startswith("category_nos") else _METAVARS.get(name)
+    required = info.is_required()
+    default = None if required else info.default
+    members = [m for m in annotation_members(info.annotation) if m is not type(None)]
+
+    if info.annotation is bool:
+        return FieldPlan(flag, metavar, False, bool(default), None, True, None, None)
+
+    enum_cls = _enum_of(members)
+    if enum_cls is not None:
+        if isinstance(default, IntEnum):
+            default = int(default)
+        return FieldPlan(
+            flag,
+            metavar,
+            required,
+            default,
+            int,
+            False,
+            [member.value for member in enum_cls],
+            None,
+        )
+
+    if all(m is int for m in members):
+        return FieldPlan(flag, metavar, required, default, int, False, None, None)
+
+    coerce: Callable[[str], object] | None = None
+    if any(m == list[int] for m in members) and not any(m is str for m in members):
+        # `int | list[int]` (course_no) keeps single-as-int; bare `list[int]`
+        # (category_nos*) always yields a list.
+        coerce = _parse_course_nos if any(m is int for m in members) else _parse_id_list
+    return FieldPlan(flag, metavar, required, default, str, False, None, coerce)

maitabi/cli/main.py

@@ -0,0 +1,36 @@
+"""Entrypoint for the `maitabi` CLI.
+
+Usage: `maitabi <bus|general> <command>` or `maitabi mcp [--transport ...]`.
+
+Exit codes: 0 OK · 1 upstream/network error · 2 input error
+(argparse rejects bad flags with 2 as well).
+"""
+
+from maitabi.cli.commands import EXIT_OK, run_action
+from maitabi.cli.parser import build_parser
+from maitabi.registry import ACTION_BY_KEY
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.domain:
+        parser.print_help()
+        return EXIT_OK
+    if args.domain == "mcp":
+        # Imported lazily: the CLI must stay importable without fastmcp.
+        from maitabi.mcp.server import run
+
+        run(transport=args.transport, host=args.host, port=args.port, path=args.path)
+        return EXIT_OK
+    if not args.command:
+        args._group.print_help()
+        return EXIT_OK
+    action = ACTION_BY_KEY.get((args.domain, args.command))
+    if action is None:  # pragma: no cover - argparse restricts choices
+        parser.error(f"unknown command: {args.domain} {args.command}")
+    return run_action(action, args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

maitabi/cli/parser.py

@@ -0,0 +1,75 @@
+"""Argparse definition for the `maitabi` CLI — generated from core models.
+
+Two levels: `maitabi <domain> <command>`, where the domain is the upstream
+family (`bus` = api.bus.maitabi.jp, `general` = www.maitabi.jp) and the
+command mirrors the MCP tool name minus its domain prefix. `maitabi mcp`
+starts the MCP server, so one executable covers both interfaces.
+
+Every subcommand comes from `registry.ACTIONS` and every flag from the
+action's Pydantic `model_fields`, so CLI flags cannot drift from the MCP
+schema. No network or parsing logic lives here — see `commands.py` and
+`services/`. Must NOT import fastmcp/mcp/server/mcp so the CLI stays
+importable without MCP dependencies installed.
+"""
+
+import argparse
+from typing import Any
+
+from pydantic.fields import FieldInfo
+
+from maitabi.cli.fields import plan_field
+from maitabi.mcp_args import add_mcp_args
+from maitabi.registry import ACTIONS, DOMAINS
+
+DOMAIN_HELP = {
+    "bus": "Mountain bus tours (api.bus.maitabi.jp)",
+    "general": "General tours & calendar (www.maitabi.jp)",
+}
+
+
+def _add_field(p: argparse.ArgumentParser, name: str, info: FieldInfo) -> None:
+    plan = plan_field(name, info)
+    kwargs: dict[str, Any] = {"dest": name, "help": info.description}
+    if plan.metavar is not None:
+        kwargs["metavar"] = plan.metavar
+    if plan.store_true:
+        kwargs["action"] = "store_true"
+        kwargs["default"] = plan.default
+    else:
+        kwargs["type"] = plan.arg_type
+        kwargs["default"] = plan.default
+        if plan.choices is not None:
+            kwargs["choices"] = plan.choices
+        if plan.required:
+            kwargs["required"] = True
+    p.add_argument(plan.flag, **kwargs)
+
+
+def _add_output_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--pretty", action="store_true", help="Pretty-print JSON with indent=2")
+    p.add_argument(
+        "--output", type=str, default=None, metavar="FILE", help="Write JSON output to FILE instead of stdout"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="maitabi",
+        description="Maitabi CLI — bus tours, general tours, and the MCP server in one command",
+    )
+    domains = parser.add_subparsers(dest="domain", metavar="<group>")
+
+    for domain in DOMAINS:
+        group = domains.add_parser(domain, help=DOMAIN_HELP[domain])
+        group.set_defaults(_group=group)
+        commands = group.add_subparsers(dest="command", metavar="<command>")
+        for action in (a for a in ACTIONS if a.domain == domain):
+            p = commands.add_parser(action.command, help=action.help)
+            for name, info in action.input_model.model_fields.items():
+                _add_field(p, name, info)
+            _add_output_args(p)
+
+    mcp_parser = domains.add_parser("mcp", help="Run the MCP server (stdio, sse, streamable-http)")
+    add_mcp_args(mcp_parser)
+
+    return parser

maitabi/config.py

@@ -0,0 +1,11 @@
+"""Configuration constants for Maitabi MCP Server.
+
+Base URLs are env-overridable so tests and mirrors can repoint the clients
+without touching service code.
+"""
+
+import os
+
+API_BASE = os.getenv("MAITABI_API_BASE", "https://api.bus.maitabi.jp")
+WEB_BASE = os.getenv("MAITABI_WEB_BASE", "https://bus.maitabi.jp")
+MAIN_BASE = os.getenv("MAITABI_MAIN_BASE", "https://www.maitabi.jp")

maitabi/core/days.py

@@ -0,0 +1,42 @@
+"""Day-input parsing shared by bus and general search services."""
+
+
+def parse_days(day_input: object) -> list[int] | None:
+    """Parse day input (int, list of ints/strings, or string like '14-16, 20').
+
+    Unrecognised shapes yield None (no day filter) instead of raising: callers
+    map the result straight onto upstream query params.
+    """
+    if day_input is None:
+        return None
+    if isinstance(day_input, int):
+        return [day_input]
+    if isinstance(day_input, list):
+        days: set[int] = set()
+        for item in day_input:
+            if isinstance(item, int):
+                days.add(item)
+            elif isinstance(item, str):
+                nested = parse_days(item)
+                if nested is not None:
+                    days.update(nested)
+        return sorted(days) if days else None
+
+    if isinstance(day_input, str):
+        days = set()
+        for part in day_input.split(","):
+            part = part.strip()
+            if not part:
+                continue
+            if "-" in part:
+                try:
+                    start_str, end_str = part.split("-", 1)
+                    start, end = int(start_str), int(end_str)
+                    if start <= end:
+                        days.update(range(start, end + 1))
+                except ValueError:
+                    continue
+            elif part.isdigit():
+                days.add(int(part))
+        return sorted(days) if days else None
+    return None

maitabi/core/enums.py

@@ -0,0 +1,54 @@
+"""Enumeration IDs shared by MCP tools, CLI flags, and raw-HTTP extraction."""
+
+from enum import IntEnum
+
+
+class TravelType(IntEnum):
+    """Category ID for Maitabi general tours (www.maitabi.jp)."""
+
+    DOMESTIC_MOUNTAIN = 1  # Domestic Mountain Climbing / Trekking
+    DOMESTIC_TRAVEL = 2  # Domestic Travel / Hiking
+    MOUNTAIN_BUS = 3  # Mountain Bus
+    OVERSEAS_MOUNTAIN = 4  # Overseas Mountain Climbing / Trekking
+    OVERSEAS_TRAVEL = 5  # Overseas Travel
+
+
+class DeparturePoint(IntEnum):
+    """Point of departure for Maitabi bus tours (bus.maitabi.jp)."""
+
+    TOKYO = 1  # Departure from Tokyo (Takebashi / Shinjuku)
+    OSAKA_KYOTO = 2  # Departure from Osaka / Kyoto
+    NAGOYA = 3  # Departure from Nagoya
+
+
+class TourStyle(IntEnum):
+    """Tour style ID for mountain bus tours."""
+
+    ROUND_TRIP_BUS = 1  # Round-trip bus only (daytime departure, no mountain lodge)
+    OUTBOUND_BUS = 2  # Outbound bus only (daytime departure)
+    INBOUND_BUS = 3  # Inbound bus only (daytime departure)
+    ROUND_TRIP_LODGE = 4  # Round-trip bus with mountain lodge (daytime departure, stay overnight at lodge)
+    OUTBOUND_LODGE = 5  # Outbound bus with mountain lodge (daytime departure, stay overnight at lodge)
+    OVERNIGHT_DAY_TRIP = 6  # Night bus departure from Tokyo → arrive at mountain early morning → day hike → return same day (no lodge stay); 夜行日帰り/往復夜行
+    TAXI_PLAN = 7  # Taxi plan
+
+
+class ReturnDayOption(IntEnum):
+    """Return date option ID for mountain bus tours relative to departure."""
+
+    DAY_1 = 1  # Return 1 day after departure — used for style=6 (night bus: depart day 0 night, return day 1 evening)
+    DAY_2 = 2  # Return 2 days after departure (1 night stay at mountain lodge)
+    DAY_3 = 3  # Return 3 days after departure (2 nights stay)
+    DAY_4 = 4  # Return 4 days after departure (3 nights stay)
+    DAY_5 = 5  # Return 5 days after departure (4 nights stay)
+
+
+class BusSeatType(IntEnum):
+    """Bus seat configuration ID for mountain bus tours."""
+
+    STANDARD = 1  # Standard seat
+    PREMIUM = 2  # Premium seat
+    OUTBOUND_PREMIUM_INBOUND_STANDARD = 3  # Outbound Premium, Inbound Standard
+    OUTBOUND_STANDARD_INBOUND_PREMIUM = 4  # Outbound Standard, Inbound Premium
+    DOUBLE_SEAT = 5  # Double seat option
+    TAXI = 6  # Taxi option

maitabi/core/envelope.py

@@ -0,0 +1,65 @@
+"""The uniform result envelope shared by every search/collection endpoint.
+
+Contract (stable since 1.0.0 — additive changes only):
+
+- `count`: total matches across all pages, or null when upstream does not say.
+  Never `len(items)`, which would silently become wrong once pagination bites.
+- `page`: the requested page, or null for endpoints that do not paginate.
+- `items`: always a list, empty rather than absent.
+- `query`: the parameters actually sent, typed (ints stay ints).
+
+Single-resource endpoints (tour detail, filter options, calendar matrix) return
+their own object instead of an envelope: a list of one would only add a level
+of indexing without adding information. Errors are always
+`{"error", "detail", "retry_hint"?}`.
+"""
+
+from enum import IntEnum
+from typing import Any
+
+from pydantic import BaseModel
+
+from maitabi.core.days import parse_days
+
+
+def as_int(value: object) -> int | None:
+    """Coerce an upstream numeric string to int, or None when it is not one."""
+    if isinstance(value, bool) or not isinstance(value, (int, float, str)):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def dict_items(raw: object) -> list[dict[str, Any]]:
+    """Coerce an upstream list into a list of dict items, dropping anything else."""
+    return [item for item in raw if isinstance(item, dict)] if isinstance(raw, list) else []
+
+
+def query_of(model: BaseModel) -> dict[str, Any]:
+    """The effective parameters of a request, typed and without empty values."""
+    out: dict[str, Any] = {}
+    for name, value in model.model_dump(exclude_none=True).items():
+        if isinstance(value, IntEnum):
+            value = int(value)
+        if value is False or value in ("", [], {}):
+            continue  # not sent upstream, so not part of the query
+        out[name] = value
+    if "day" in out:
+        # Search models accept "14-16, 20"; report the days actually requested.
+        days = parse_days(out["day"])
+        if days is not None:
+            out["day"] = days
+    return out
+
+
+def envelope(
+    *,
+    items: list[Any],
+    count: int | None,
+    page: int | None,
+    query: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the uniform result envelope."""
+    return {"count": count, "page": page, "items": items, "query": query}

maitabi/core/errors.py

@@ -0,0 +1,50 @@
+"""Uniform error payloads returned inside successful HTTP responses.
+
+Upstream failures never raise: services embed these shapes in the JSON body so
+MCP clients, CLI scripts, and raw-HTTP consumers all read the same contract:
+`{"error": <human message>, "detail": <technical cause>, "retry_hint": <optional>}`.
+"""
+
+RATE_LIMIT_ERROR = "Rate limited by www.maitabi.jp (60 requests/min per IP)"
+RATE_LIMIT_RETRY_HINT = "wait ~60s and retry manually"
+THROTTLED_BODY_MESSAGE = "Too Many Attempts."
+
+
+def upstream_http_error(status_code: int, detail: str) -> dict[str, str]:
+    """Non-2xx upstream response."""
+    return {
+        "error": f"Upstream service returned error: {status_code}",
+        "detail": detail,
+    }
+
+
+def connection_error(detail: str) -> dict[str, str]:
+    """Network-level failure reaching the upstream host."""
+    return {
+        "error": "Failed to connect to Maitabi server",
+        "detail": detail,
+    }
+
+
+def rate_limit_error() -> dict[str, str]:
+    """www.maitabi.jp throttling (HTTP 200 + 'Too Many Attempts.' body)."""
+    return {
+        "error": RATE_LIMIT_ERROR,
+        "detail": THROTTLED_BODY_MESSAGE,
+        "retry_hint": RATE_LIMIT_RETRY_HINT,
+    }
+
+
+def is_rate_limited_body(data: object) -> bool:
+    """Detect www.maitabi.jp's HTTP-200 throttle body (no Retry-After header)."""
+    if not isinstance(data, dict):
+        return False
+    errors = data.get("errors")
+    if not isinstance(errors, dict):
+        return False
+    return bool(errors.get("message") == THROTTLED_BODY_MESSAGE)
+
+
+def is_error_payload(data: object) -> bool:
+    """True when a service result carries an error instead of data."""
+    return isinstance(data, dict) and "error" in data

maitabi/core/filters.py

@@ -0,0 +1,66 @@
+"""Result post-processing shared by bus and general search services.
+
+These helpers run on upstream payloads AFTER the HTTP call: price-range
+filtering, availability filtering, and `detail_url` enrichment. They keep the
+exact wire semantics that both the MCP tools and the CLI expose.
+"""
+
+from datetime import datetime
+
+from maitabi.config import MAIN_BASE, WEB_BASE
+
+# Upstream statuses that mean "not bookable" per domain.
+#
+# bus.maitabi.jp reports Japanese strings; www.maitabi.jp reports numbers where
+# 1 = maru-double, 2 = maru, 3 = batsu (closed). Only the explicit closed values
+# code must never make an existing tour disappear from results.
+BUS_CLOSED_STATUSES: tuple[object, ...] = ("満席", "受付終了", "")
+GENERAL_CLOSED_STATUSES: tuple[object, ...] = (3,)
+
+
+def parse_price_jpy(raw: object) -> int | None:
+    """Parse an upstream price string ('15,500円~') into an int, or None.
+
+    Upstream prices carry ',' thousands separators, the 円 suffix, and a
+    trailing fullwidth tilde (\uff5e) for ranges. Unparseable values yield None
+    (never 0) so callers can distinguish "no price" from a real zero.
+    """
+    cleaned = str(raw).replace(",", "").replace("円", "").replace("\uff5e", "").strip()
+    return int(cleaned) if cleaned.isdigit() else None
+
+
+def within_price_range(price_jpy: int | None, min_price: int | None, max_price: int | None) -> bool:
+    """True when price fits [min_price, max_price]. Unknown price (None) always fits."""
+    if price_jpy is None:
+        return True
+    if min_price is not None and price_jpy < min_price:
+        return False
+    return not (max_price is not None and price_jpy > max_price)
+
+
+def is_open_status(status: object, closed_statuses: tuple[object, ...]) -> bool:
+    """True when an upstream status (string or numeric code) is still bookable."""
+    return status not in closed_statuses
+
+
+def derive_bus_detail_url(course_no: int | str, date_str: str, fallback_month: int | None = None) -> str:
+    """Build the bus.maitabi.jp detail link, deriving year/month from the date field.
+
+    Upstream `date` looks like '2026年09月12日(土)'. When it can't be parsed,
+    fall back to the current year and the search month (or current month).
+    """
+    now = datetime.now()
+    year, month = now.year, fallback_month or now.month
+    if "年" in date_str and "月" in date_str:
+        parts = date_str.split("年")
+        if len(parts) == 2:
+            y_str = parts[0]
+            m_str = parts[1].split("月")[0]
+            if y_str.isdigit() and m_str.isdigit():
+                year, month = int(y_str), int(m_str)
+    return f"{WEB_BASE}/detail.html?course_no={course_no}&year={year}&month={month}"
+
+
+def derive_general_detail_url(course_no: int | str) -> str:
+    """Build the www.maitabi.jp detail link (no date derivation needed)."""
+    return f"{MAIN_BASE}/detail.php?courseNo={course_no}"