Metadata-Version: 2.4
Name: styx-search
Version: 0.1.0.post3
Summary: Fast CLI & Model Context Protocol (MCP) search tool for 450,000+ open-access papers, technical standards, and books.
Author: Lucida Team
License: MIT
Project-URL: Homepage, https://styx-iota.vercel.app
Project-URL: Repository, https://github.com/0x923041-dotcom/styx-cli
Keywords: search,academic,papers,mcp,ai-agents,arxiv,nist,research
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: rich>=13.0.0
Dynamic: license-file

# styx-search

**Search 450,000+ open-access papers, standards, textbooks, and legal documents — right from your terminal or your AI agent.**

`styx-search` is a zero-configuration CLI and [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Styx Open Knowledge Archive](https://styx-iota.vercel.app). Every source in the archive is open access or public domain — no paywalls, no accounts required to search.

- **For humans** — search, export BibTeX/APA/MLA/Chicago citations, and download PDFs to disk with one command.
- **For AI agents** — a stdio MCP server with four tools, so Claude, Cursor, Windsurf, OpenCode, or any MCP client can search papers and save PDFs into your workspace.
- **100% self-contained** — talks only to the public HTTPS API. No API keys, no sign-up, no internal infrastructure.

---

## Install

```bash
pip install styx-search
```

Or from source:

```bash
git clone https://github.com/0x923041-dotcom/styx-cli.git
cd styx-cli
pip install .
```

Requires Python 3.8+.

---

## Quick start

```bash
# Search — supports source:/lang:/category: directives
styx search "attention is all you need" --limit 5
styx search "source:nist zero trust" --category "Computer Science & Tech"
styx search "source:eurlex AI act" --json
styx search "meditations marcus aurelius" --markdown   # for Obsidian/Notion

# Download the original PDF
styx download 297465 -o paper.pdf          # by document ID
styx download "https://arxiv.org/pdf/2604.21816v1.pdf"   # by URL

# Citations
styx cite 7288 --format bibtex
styx cite 7288 --format apa

# Document metadata
styx info 2844

# License key (Pro) + quota
styx auth STYX-XXXX-XXXX-XXXX
styx quota

# AI agent server
styx mcp
```

### Example

```text
$ styx search "source:nist zero trust" --limit 3

Styx - 3 results for "source:nist zero trust"
    #   Year  Title                                 Author                 Source
    1   n.d.  NIST SP 1800-35: Implementing a Zero  Scott Rose (NIST); ..  NIST
              Trust Architecture: High...
    2   n.d.  NIST SP 800-207: Zero Trust           Scott Rose (NIST); ..  NIST
              Architecture
    3   n.d.  NIST SP 800-207A: A Zero Trust        Ramaswamy Chandramo..  NIST
              Architecture Model for Access ...

  Tip: styx download 2844 saves the PDF, styx cite 2844 exports a citation.
```

### Search directives

The CLI understands the same directives as the Styx web app — they are stripped
from the query and applied as real filters:

| Directive | Example | Effect |
|-----------|---------|--------|
| `source:` / `src:` | `source:nist` | Restrict to one or more sources (`source:nist source:owasp`) |
| `lang:` / `language:` | `lang:it` | Restrict to a language (ISO code) |
| `category:` / `cat:` | `cat:"Law & Regulation"` | Restrict to a category tab |

Directives can be combined freely: `styx search "cat:\"Computer Science & Tech\" source:nist lattice cryptography"`.

---

## Model Context Protocol (MCP)

The `styx mcp` command starts a stdio JSON-RPC MCP server. It is dependency-free
(no MCP SDK required) and works with any MCP client.

### Tools

| Tool | Description |
|------|-------------|
| `styx_search` | Search the archive (query, limit, category). Returns structured results with titles, authors, years, source, snippet, and `direct_pdf_url`. |
| `styx_download_pdf` | Download the original PDF for a document ID or URL to a local path. |
| `styx_get_citation` | BibTeX / APA / MLA / Chicago citation for a document ID. |
| `styx_get_document` | Full metadata (description, license, source, direct PDF URL) for a document ID. |

### Claude Desktop

Add to `claude_desktop_config.json`:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "styx": {
      "command": "styx",
      "args": ["mcp"]
    }
  }
}
```

### Cursor

`Settings → Cursor Settings → MCP → Add new MCP server`:

```json
{
  "mcpServers": {
    "styx": {
      "command": "styx",
      "args": ["mcp"]
    }
  }
}
```

After adding, restart the client and you can ask, for example:

> *"Find the NIST post-quantum encryption standard and download the PDF into my workspace."*

### Manual smoke test

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | styx mcp
```

---

## Fair use

Every source in Styx is open access or public domain, and searching is free.
To keep the archive open for everyone, a trial allowance applies per client
(and then a rate limit). When a limit is reached, the CLI returns a clear,
non-blocking message:

```text
Free trial allowance exhausted. Add a license key to continue at higher
limits: docs at https://styx-iota.vercel.app or `styx auth <key>`.
```

Add a license key once with `styx auth <key>` — it is stored in
`~/.styx/config.json` and sent with every request. No account or sign-up is
required to search.

---

## Development

```bash
pip install -e . pytest
pytest tests/            # 36 offline tests (mocked HTTP, no network)
```

## License

MIT — see [LICENSE](LICENSE).

Built on the [Styx Open Knowledge Archive](https://styx-iota.vercel.app) — 500+
living sources: arXiv, NIST, OWASP, CISA, PubMed/PMC, MIT OpenCourseWare,
EUR-Lex, Project Gutenberg, and more.
