feat: add MCP server, machine-readable output and English UI

[Ramos-dev]

Builds on #8 — that PR restores basic functionality by migrating off the discontinued Xueqiu API; this one makes the tool usable by AI agents and scripts. Please merge #8 first, otherwise this diff will also show its commit.

MCP server

wstock mcp speaks the Model Context Protocol over stdio, so Claude Desktop, Claude Code and Cursor can query quotes directly:

{ "mcpServers": { "wstock": { "command": "wstock", "args": ["mcp"] } } }

Five tools: get_stock_quote, search_stock, list_watchlist, add_to_watchlist, remove_from_watchlist.

I implemented the protocol directly instead of using @modelcontextprotocol/sdk, because the SDK pulls in ~90 transitive packages (express, cors, zod, jose) for what is a line-delimited JSON-RPC loop over stdio. The runtime tree stays at two packages — happy to switch if you would prefer the SDK.

Machine-readable output

--json and --csv on list, show and query. Both imply --single, so they print once and exit rather than hanging in the polling loop:

$ wstock show 600519 --json
{"name":"贵州茅台","code":"sh600519","current":1346.48,"percentage":-0.18,...}

$ wstock show 600519 --json | jq -r .current
1346.48

Numeric fields are numbers, not strings; unparseable values become null so the JSON stays valid. Field names and market labels are always English here regardless of --lang, so parsers do not break when someone switches language.

English by default

Headers and messages were hard-coded Chinese, which made the table unreadable in non-CJK terminals and awkward to parse. They now default to English:

$ wstock list
NAME         CODE         OPEN         PREV CLOSE   PRICE        HIGH         LOW          CHANGE
上证指数     sh000001     3950.71      3966.59      3964.79      3966.39      3942.75      -0.05%

--lang zh or WSTOCK_LANG=zh restores the Chinese output. Strings live in lib/i18n.js.

This replaces config.stockTermMap with config.stockFields (the column list), since labels now come from the catalogue. Worth flagging as the one behavioural change for existing users — anyone reading stockTermMap from the config module would need updating, though it was not part of the documented API.

Issues addressed

#4 — press q to quit. Matches top/htop. Only enabled on an interactive TTY, and raw mode is always restored so the terminal is not left without echo. Verified in a real PTY.

#6 — wrong prefix corrupts the whole table. Already fixed by #8: the parser matches on v_<code>= rather than splitting positionally, so a bad code can no longer shift other rows. But the invalid code still vanished silently, which is confusing — now it is reported:

$ wstock list
...
Unresolved code(s): sz515050 — check the market prefix (sh/sz/bj/hk/us)

#3 and #5 need no change after #8 — I verified both. wstock add 600127 infers the market (sh600127), and list preserves stock.json order.

#7 is promotional and unrelated; I have left it alone.

Documentation

• AGENTS.md — layout, conventions, output contract, and the gotchas that have each caused a real bug here: GBK responses vs UTF-8 query keys, the ambiguous 000xxx range, and why ESC[2J must not be used for refresh. CLAUDE.md points to it.
• SECURITY.md — private reporting process plus the actual posture: outbound HTTPS only, no inbound listener, no credentials, no telemetry, two dependencies.
• CONTRIBUTING.md — setup, conventions, test layout.
• .mcp.json — ready-to-use client config.
• README rewritten around the new flags, MCP setup and scripting.

Other

• files added to package.json, so the tarball no longer ships tests and dev files.
• Version bumped to 0.1.0 — new features, plus the stockTermMap rename.
• Non-zero exit codes on failed lookups, so set -e scripts behave.

Verification

• Suite extended from 22 to 39 assertions, covering i18n key parity across both languages, the JSON/CSV contract, and the MCP handlers (handshake, tool schemas, notifications, unknown methods, missing arguments).
• Clean-clone install checked: 2 packages, 39/39 pass, MCP and CLI both work.
• q-to-quit and in-place refresh verified in a real PTY (4 frames, no ESC[2J).
• No deprecation warnings on any command.
• config/stock.json is byte-identical to master.