impresso-mcp: Instructions file for Claude Code

impresso MCP Server

A CLI and an MCP server for impresso, the research corpus of the digitised press of Switzerland and Luxembourg. It needs a free account, it resolves to an article, and the search response holds the keyword in context.

Stack

• Python ≥3.12, uv, fastMCP ≥2.0.0, httpx ≥0.27.0, python-dotenv ≥1.0.0

Functions

• A full-text search at article level, with the extracts in the search response
• A structured boolean query, through --or, --and and --not
• A control of the precision: exact, fuzzy, soft, partial
• Filters for the year range, the publication, the language, the country, the item type, the front page, the headline, the named-entity mentions, the entities, the topics and the partners
• A regular expression filter against the terms in the index
• A facet listing over 16 fields, so that you can give a full-string filter value exactly
• A source listing with the dates that impresso holds for each publication
• A transcript download for each article
• Pagination at up to 1000 results for each request, with no limit on the depth

Structure

impresso-mcp/
├── .claude/skills/impresso-search/   # Skill documenting the CLI
├── src/impresso_mcp/
│   ├── __init__.py
│   ├── auth.py             # Token minting, caching and renewal
│   ├── client.py           # API client + caching
│   ├── cli.py              # `impresso` command-line interface
│   ├── paths.py            # Cache and credential locations
│   ├── ratelimit.py        # Cross-process request pacing
│   ├── server.py           # FastMCP tools
│   └── install.py          # MCP server installer
├── pyproject.toml
└── CLAUDE.md               # This file

client.py holds all the behaviour. server.py and cli.py are thin presentation layers over it, so the search semantics and the cache stay identical for each method of access. The CLI shows each filter without a condition. The MCP server hides them behind --enable-advanced-search.