# screener-ai-tool — Agent Install & Usage Guide

This file is written for AI coding agents (Claude Code, Cursor, Codex, Copilot,
etc.) so they can install and operate this tool **autonomously** — install the
package, register the MCP server, install the skill, and start using it.
Follow the steps below in order.

## What this is

Async Python toolkit for NSE/BSE Indian stock data from screener.in. Ships as:

- a CLI (`screener`)
- a library (`screener_ai`)
- an MCP server exposing `screener_*` tools
- an agent skill at `skills/screener-ai-tool/SKILL.md`

## 1. Install the package

Preferred — from PyPI:

```bash
pip install screener-ai-tool
# or
uv pip install screener-ai-tool
```

From source (latest, if PyPI release lags):

```bash
git clone https://github.com/singhvedant/screener-ai-tool.git
cd screener-ai-tool
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
```

Verify: `screener --help` should print the command list.

## 2. Register the MCP server

If your platform is an MCP client (Claude Code, Claude Desktop, Cursor,
Windsurf, etc.), register the `screener` MCP server over stdio:

```bash
# if installed via pip/uv (entry point on PATH)
claude mcp add screener -- screener serve

# if running from a cloned repo
claude mcp add screener -- uv run --directory <path-to-repo> screener serve
```

This exposes `screener_search`, `screener_price`, `screener_overview`,
`screener_fundamentals`, `screener_technical`, `screener_peers`,
`screener_shareholding`, `screener_events`, `screener_news`,
`screener_snapshot`, `screener_bulk`, `screener_export`, `screener_login`,
`screener_auth_status`. All return JSON-serializable dicts.

## 3. Install the skill (so you can toggle it on/off and reuse it anytime)

Copy `skills/screener-ai-tool/SKILL.md` into your own skills directory. This
makes the skill discoverable/triggerable (`/screener` or auto-trigger on
Indian-stock questions) independent of this repo.

```bash
# Claude Code — user-level (available in every project)
mkdir -p ~/.claude/skills/screener-ai-tool
curl -fsSL -o ~/.claude/skills/screener-ai-tool/SKILL.md \
  https://raw.githubusercontent.com/singhvedant/screener-ai-tool/main/skills/screener-ai-tool/SKILL.md

# or project-level
mkdir -p .claude/skills/screener-ai-tool
cp skills/screener-ai-tool/SKILL.md .claude/skills/screener-ai-tool/SKILL.md
```

To turn it off later: delete or rename that copied `SKILL.md`
(`~/.claude/skills/screener-ai-tool/`) — no other state to clean up. To turn
it back on, re-run the copy step above.

## 4. Authenticate (optional, recommended for heavy use)

Anonymous screener.in access is rate-limited (~50 page views/day):

```bash
screener login --email you@example.com   # hidden password prompt
# or via env vars
export SCREENER_EMAIL=you@example.com SCREENER_PASSWORD=your-password
screener login
```

Session persists to `~/.screener-ai/session.json` (mode 0600) and is reused
automatically. Or call `screener_login(email, password)` via MCP.

## 5. Use it

```bash
screener search reliance --json
screener overview RELIANCE --json
screener technical RELIANCE --days 365 --json
screener snapshot RELIANCE --json
screener bulk RELIANCE TCS INFY --dataset overview --json
```

Or via MCP tools (`screener_search`, `screener_overview`, ...) or the library:
`from screener_ai.service import ScreenerService`.

## 6. Rules of engagement

- Symbols are NSE/BSE tickers (RELIANCE, TCS, INFY, HDFCBANK). Always call
  `screener_search` / `screener search` to resolve a company name to a symbol
  first — never guess.
- `bulk`/`screener_bulk`/`export` isolate per-symbol failures as
  `{"error": "..."}` — check each entry, don't assume the whole batch
  succeeded.
- Treat `None` as "data not available", never as `0`.
- Respect screener.in's Terms of Service: don't scrape at scale or evade rate
  limits. Defaults are conservative (2 req/s, burst 5) — don't raise
  `--concurrency` aggressively. If you hit rate limits, log in (step 4)
  instead of retrying harder.

## Reference

- `README.md` — full docs, architecture, CLI/MCP reference, data models
- `SPEC.md` — design/architecture details
- `skills/screener-ai-tool/SKILL.md` — the skill definition copied in step 3

## License

MIT — see `LICENSE`.
