avios-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{avios_cli-0.5.0 → avios_cli-0.6.0}/CHANGELOG.md

@@ -6,6 +6,32 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-11
+
+### Added
+- **MCP server (`avios-mcp`).** Exposes your Avios accounts and British Airways
+  reward availability to Claude and any other MCP client over stdio. Install with
+  `uv tool install 'avios-cli[mcp]'`; sessions come from `avios login`, so the
+  server never performs a login itself. Closes #45.
+
+  Tools: `list_accounts`, `get_balance`, `get_transactions`,
+  `get_pending_transactions`, `whoami`, `search_reward_flights`.
+
+  Design constraints worth stating, because they are what make it safe to point an
+  agent at:
+
+  - **Read-only.** Nothing books, spends, or mutates a session.
+  - **No credentials in output.** Every tool returns an explicit response model
+    rather than a raw API payload, so cookies, API keys and the `whoami` id token
+    never leave the process.
+  - **Reward search is batched and rate-limited.** BA blocks by IP address, so an
+    agent fanning out over routes could lock you out of the site. A whole return
+    trip goes through one batched, single-browser-session search; the server
+    enforces a cooldown between searches; and a block is reported as terminal and
+    explicitly not retryable.
+  - **MCP is an optional extra**, so a plain CLI install does not pull in the SDK's
+    web stack.
+
 ## [0.5.0] - 2026-08-11
 
 ### Fixed

{avios_cli-0.5.0 → avios_cli-0.6.0}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.5
 Name: avios-cli
-Version: 0.5.0
-Summary: A CLI and TUI for Avios balances, transactions, and BA reward-flight availability.
+Version: 0.6.0
+Summary: A CLI, TUI and MCP server for Avios balances, transactions, and BA reward-flight availability.
 Project-URL: Homepage, https://github.com/alexechoi/avios-cli
 Project-URL: Repository, https://github.com/alexechoi/avios-cli
 Project-URL: Issues, https://github.com/alexechoi/avios-cli/issues
 Author: Alex Choi
 License-Expression: MIT
 License-File: LICENSE
-Keywords: avios,british-airways,cli,loyalty,terminal,tui
+Keywords: avios,british-airways,cli,loyalty,mcp,terminal,tui
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: End Users/Desktop
@@ -31,6 +31,8 @@ Requires-Dist: rich>=13.7
 Requires-Dist: textual>=0.80
 Requires-Dist: typer>=0.12
 Provides-Extra: login
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # avios-cli
@@ -39,10 +41,10 @@ Description-Content-Type: text/markdown
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 
-A **CLI and TUI for your Avios programmes** — check balances, browse transactions,
-and search British Airways reward-flight availability without leaving the terminal.
-British Airways, Iberia, and Aer Lingus use avios.com; Finnair Plus uses Finnair's
-own OAuth and loyalty API.
+A **CLI, TUI and MCP server for your Avios programmes** — check balances, browse
+transactions, and search British Airways reward-flight availability without leaving
+the terminal, or hand the same data to an AI agent. British Airways, Iberia, and
+Aer Lingus use avios.com; Finnair Plus uses Finnair's own OAuth and loyalty API.
 
 > ⚠️ **Unofficial.** This project is not affiliated with, authorised by, or endorsed by
 > Avios, British Airways, Finnair or IAG Loyalty. It drives the same private endpoints
@@ -178,6 +180,41 @@ A tabbed full-screen application:
 Press `r` to refresh the dashboard and `q` to quit. Reward searches run only when
 you press Search or Enter.
 
+## MCP server
+
+Expose your accounts to Claude and other MCP clients, read-only:
+
+```bash
+uv tool install 'avios-cli[mcp]'
+avios login ba          # sessions come from the CLI; the server never logs in
+```
+
+```jsonc
+// Claude Desktop: claude_desktop_config.json
+{
+  "mcpServers": {
+    "avios": { "command": "avios-mcp" }
+  }
+}
+```
+
+Or, for Claude Code:
+
+```bash
+claude mcp add avios -- uvx --from 'avios-cli[mcp]' avios-mcp
+```
+
+Tools: `list_accounts`, `get_balance`, `get_transactions`,
+`get_pending_transactions`, `whoami`, `search_reward_flights`.
+
+Every tool is read-only — nothing books, spends, or changes a session — and no
+cookie or token is ever returned. `search_reward_flights` searches a whole return
+trip in one call and is rate-limited server-side, because it drives a real browser
+and British Airways blocks by IP address; an agent looping over routes could get
+you locked out of the site.
+
+## Notes on reward search
+
 Reward search is an unofficial view of BA's own flight finder. It supports direct
 BA flights, three-letter airport/city codes, and seat counts by cabin. Searching
 an exact `--date` also fetches the Avios price per cabin for your party; calendar
@@ -197,6 +234,7 @@ one-way searches sharing one browser session.
 - [x] Multiple accounts (BA, Iberia, Aer Lingus, Finnair) with combined views
 - [x] British Airways reward-flight **availability** search (CLI + TUI)
 - [x] Avios pricing per cabin for an exact date
+- [x] MCP server (`avios-mcp`) for AI agents
 
 ## Development
 

{avios_cli-0.5.0 → avios_cli-0.6.0}/README.md

@@ -4,10 +4,10 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 
-A **CLI and TUI for your Avios programmes** — check balances, browse transactions,
-and search British Airways reward-flight availability without leaving the terminal.
-British Airways, Iberia, and Aer Lingus use avios.com; Finnair Plus uses Finnair's
-own OAuth and loyalty API.
+A **CLI, TUI and MCP server for your Avios programmes** — check balances, browse
+transactions, and search British Airways reward-flight availability without leaving
+the terminal, or hand the same data to an AI agent. British Airways, Iberia, and
+Aer Lingus use avios.com; Finnair Plus uses Finnair's own OAuth and loyalty API.
 
 > ⚠️ **Unofficial.** This project is not affiliated with, authorised by, or endorsed by
 > Avios, British Airways, Finnair or IAG Loyalty. It drives the same private endpoints
@@ -143,6 +143,41 @@ A tabbed full-screen application:
 Press `r` to refresh the dashboard and `q` to quit. Reward searches run only when
 you press Search or Enter.
 
+## MCP server
+
+Expose your accounts to Claude and other MCP clients, read-only:
+
+```bash
+uv tool install 'avios-cli[mcp]'
+avios login ba          # sessions come from the CLI; the server never logs in
+```
+
+```jsonc
+// Claude Desktop: claude_desktop_config.json
+{
+  "mcpServers": {
+    "avios": { "command": "avios-mcp" }
+  }
+}
+```
+
+Or, for Claude Code:
+
+```bash
+claude mcp add avios -- uvx --from 'avios-cli[mcp]' avios-mcp
+```
+
+Tools: `list_accounts`, `get_balance`, `get_transactions`,
+`get_pending_transactions`, `whoami`, `search_reward_flights`.
+
+Every tool is read-only — nothing books, spends, or changes a session — and no
+cookie or token is ever returned. `search_reward_flights` searches a whole return
+trip in one call and is rate-limited server-side, because it drives a real browser
+and British Airways blocks by IP address; an agent looping over routes could get
+you locked out of the site.
+
+## Notes on reward search
+
 Reward search is an unofficial view of BA's own flight finder. It supports direct
 BA flights, three-letter airport/city codes, and seat counts by cabin. Searching
 an exact `--date` also fetches the Avios price per cabin for your party; calendar
@@ -162,6 +197,7 @@ one-way searches sharing one browser session.
 - [x] Multiple accounts (BA, Iberia, Aer Lingus, Finnair) with combined views
 - [x] British Airways reward-flight **availability** search (CLI + TUI)
 - [x] Avios pricing per cabin for an exact date
+- [x] MCP server (`avios-mcp`) for AI agents
 
 ## Development
 

{avios_cli-0.5.0 → avios_cli-0.6.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "avios-cli"
-description = "A CLI and TUI for Avios balances, transactions, and BA reward-flight availability."
+description = "A CLI, TUI and MCP server for Avios balances, transactions, and BA reward-flight availability."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.10"
 authors = [{ name = "Alex Choi" }]
-keywords = ["avios", "british-airways", "cli", "tui", "loyalty", "terminal"]
+keywords = ["avios", "british-airways", "cli", "tui", "loyalty", "terminal", "mcp"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",
@@ -45,6 +45,10 @@ dependencies = [
 # base package, so `avios-cli[login]` resolves to the same thing as `avios-cli`.
 login = []
 
+# MCP server (`avios-mcp`). Optional so a plain CLI install stays small; the SDK
+# pulls in a web stack the terminal app has no use for.
+mcp = ["mcp>=2.0,<3"]
+
 # Dev tooling lives in a PEP 735 dependency-group (not an extra) so that `uv sync`
 # and `uv run` install it by default — an extra would be pruned by `uv run`.
 [dependency-groups]
@@ -56,12 +60,18 @@ dev = [
     "ruff>=0.6",
     "mypy>=1.10",
     "types-PyYAML",
+    # In the dev group, not just the `mcp` extra, so CI type-checks and tests the
+    # MCP server rather than skipping it.
+    "mcp>=2.0,<3",
 ]
 
 [project.scripts]
 avios = "avios.cli:app"
 # Alias so `uvx avios-cli` (matching the package name) works too.
 avios-cli = "avios.cli:app"
+# MCP server over stdio; needs the `mcp` extra. The wrapper module reports a
+# missing extra as one readable line rather than an import traceback.
+avios-mcp = "avios.mcp_entry:main"
 
 [project.urls]
 Homepage = "https://github.com/alexechoi/avios-cli"
@@ -99,5 +109,5 @@ mypy_path = "src"
 plugins = ["pydantic.mypy"]
 
 [[tool.mypy.overrides]]
-module = ["browser_cookie3.*", "playwright.*"]
+module = ["browser_cookie3.*", "playwright.*", "mcp.*"]
 ignore_missing_imports = true

avios_cli-0.6.0/src/avios/__init__.py

@@ -0,0 +1,7 @@
+"""avios — a CLI, TUI and MCP server for avios.com.
+
+View your Avios balance, transactions and reward-flight availability from the
+terminal, or serve them to an AI agent with ``avios-mcp``.
+"""
+
+__version__ = "0.6.0"

avios_cli-0.6.0/src/avios/mcp_entry.py

@@ -0,0 +1,36 @@
+"""Console-script wrapper for ``avios-mcp``.
+
+Kept separate from :mod:`avios.mcp_server` so that a missing ``mcp`` extra produces
+one actionable line on stderr instead of an ``ImportError`` traceback — the server
+is normally launched by an MCP client, which shows the user very little.
+"""
+
+from __future__ import annotations
+
+import sys
+from importlib.util import find_spec
+
+INSTALL_HINT = (
+    "avios-mcp needs the `mcp` extra, which is not installed.\n"
+    "\n"
+    "  uv tool install 'avios-cli[mcp]'\n"
+    "\n"
+    "or run it without installing:\n"
+    "\n"
+    "  uvx --from 'avios-cli[mcp]' avios-mcp"
+)
+
+
+def main() -> None:
+    """Serve the Avios MCP server over stdio."""
+    if find_spec("mcp") is None:
+        print(INSTALL_HINT, file=sys.stderr)
+        raise SystemExit(1)
+
+    from avios.mcp_server import mcp
+
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()