Metadata-Version: 2.4
Name: acsearch-mcp
Version: 0.1.0
Summary: MCP server for acsearch.info — ancient coin auction archive with 16M+ lots
Project-URL: Homepage, https://github.com/wushanyun64/acsearch-mcp
Project-URL: Repository, https://github.com/wushanyun64/acsearch-mcp
Project-URL: Issues, https://github.com/wushanyun64/acsearch-mcp/issues
Author: Jason Sun
License: MIT
License-File: LICENSE
Keywords: acsearch,ancient-coins,auction-archive,coin-auction,market-research,mcp,numismatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: lxml>=5.0.0
Description-Content-Type: text/markdown

# acsearch-mcp

MCP server for [acsearch.info](https://www.acsearch.info) — the ancient coin auction archive with 16M+ lots from 475 auction houses. Framework-agnostic: works with any MCP-compatible client (Hermes, Claude Desktop, Claude Code, Cursor, Continue.dev, etc.).

## Setup

```bash
git clone git@github.com:wushanyun64/acsearch-mcp.git
cd acsearch-mcp
uv sync
```

Requires an acsearch.info **Premium account** (€85/year) for price data.

Credentials are passed via environment variables:

```bash
export ACSEARCH_USERNAME="your_username"
export ACSEARCH_PASSWORD="your_password"
```

Session cookies are cached to `~/.acsearch_cookies.json` after first login to avoid re-authenticating on every tool call.

## MCP Tools

| Tool | Description |
|---|---|
| `search` | Full-text Boolean search with wildcards, phrases, exclusions |
| `get_lot` | Full lot details: description, specs, references, provenance |
| `price_history` | Year-by-year price analysis for market research |
| `find_comparables` | Recent comparable auction results for valuation |

### Search Syntax

- `*` — wildcard (auto-appended to 3+ char words)
- `"..."` — exact phrase
- `-word` — exclude results containing word
- `(...)` — group sub-queries

Examples: `"Philip II tetradrachm"`, `Alexander* stater -bronze`, `cistophorus Ephes*`

## Client Configuration

### Hermes Agent

Add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  acsearch:
    command: uv
    args:
      - --directory
      - /path/to/acsearch-mcp
      - run
      - acsearch-mcp
      - --transport
      - stdio
    env:
      ACSEARCH_USERNAME: your_username
      ACSEARCH_PASSWORD: your_password
```

Then restart: `hermes gateway restart` (or `/reset` in CLI).

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "acsearch": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/acsearch-mcp",
        "run", "acsearch-mcp", "--transport", "stdio"
      ],
      "env": {
        "ACSEARCH_USERNAME": "your_username",
        "ACSEARCH_PASSWORD": "your_password"
      }
    }
  }
}
```

### Claude Code / Cursor / Continue.dev

Any MCP client that accepts stdio command config. Point `command` to `uv`, pass `--directory /path/to/acsearch-mcp run acsearch-mcp --transport stdio` as args, and include the two `ACSEARCH_*` env vars.

### Generic MCP Client (stdio)

```bash
ACSEARCH_USERNAME="your_username" \
ACSEARCH_PASSWORD="your_password" \
uv --directory /path/to/acsearch-mcp run acsearch-mcp --transport stdio
```

### HTTP Mode (remote / networked clients)

```bash
uv run acsearch-mcp --transport http --host 0.0.0.0 --port 8001
```

Then connect your client to `http://host:8001/mcp`.

## Architecture

```
acsearch_mcp/
├── server.py    # FastMCP server with 4 tools (stdio + HTTP)
├── client.py    # HTTP client: login, cookies, rate limiting
├── parser.py    # JSON extraction from script tags, HTML fallback
└── models.py    # Dataclasses: SearchResult, LotDetail, etc.
```

Key insight: acsearch.info embeds search results as `acsearch.initSearchResults = [{...}]` JSON in a `<script>` tag. No fragile HTML parsing needed for search results.

## Limitations

- Descriptions are capped at 350 characters by acsearch.info. The full catalog text lives on the original auction house page (accessible via the `link` field in lot details).
- Prices are only visible with a Premium account.
