xsf0221/pattern-vista-cli

Command-line access to Pattern Vista — K-line
pattern historical win-rates and MA200 deviation rankings — built to be called
by **AI agents** as easily as by humans.
Output is **JSON by default** (so an agent can parse it directly); add --table
for a human-readable view.
Install
Authenticate
Generate a key at (Account → API keys), then:
Resolution order: --api-key flag → PATTERN_VISTA_API_KEY → stored config.
Commands
Example (agent-friendly JSON)
Free vs. paid
A free account sees the **top 2** rows of each list and patterns without the
historical win-rate. A paid subscription unlocks the full lists (up to 100) and
hist_win_w20. The tier is enforced server-side from the key — see
is_billed in every response.
For agents / programmatic use
The PatternVistaClient core has no CLI dependency — it is what backs the MCP
server below, so the two can never return different things.
Use as an MCP server
The same data as tools your agent can call directly. No install needed if you
have uv:
Drop that into your MCP client's config (Claude Desktop, Claude Code, Cursor,
or anything else that speaks MCP over stdio). If you would rather install it:
Or run it in a container. -i is required — the transport is stdio, so without
an attached stdin the server has nothing to read and exits straight away:
Tools
| Tool | Answers |
|---|---|
| market_stretch | Is the market broadly extended or depressed right now, and how does that rank against its own history? |
| deviation_ranking | Which symbols are furthest below (or above) their own 200-day average? |
| recommended_patterns | What did last night's scan flag, and has that pattern bucket historically beaten SPY? |
| ticker_report | Everything held on one symbol. |
| account_status | Which account is this key, and is it on a paid tier? |
Auth resolves exactly as the CLI's does: PATTERN_VISTA_API_KEY, else the key
saved by pv config set-key. Tiering stays server-side — a free key gets 2 rows
and a null hist_win_w20, so check is_billed in the response before treating
a short list as a quiet market.
Works with both generations of the MCP Python SDK (mcp 1.x's FastMCP and
2.x's MCPServer).
Data notes
- **Deviation** = (close − MA200) / MA200, refreshed nightly over an S&P 500 +
Nasdaq 100 + major-ETF universe. Split-distorted and implausible values are