Skip to main content
Glama
ati-hh-mcp

ati-hh-mcp

by timur-ai
README.md
# ati-hh-mcp

[![CI](https://github.com/timur-ai/ati-hh-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/timur-ai/ati-hh-mcp/actions/workflows/ci.yml)
[![Docs](https://github.com/timur-ai/ati-hh-mcp/actions/workflows/docs.yml/badge.svg)](https://timur-ai.github.io/ati-hh-mcp/)
[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](#requirements)
[![Coverage](https://img.shields.io/badge/coverage-%E2%89%A595%25%20src-green.svg)](#development)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Public MCP (Model Context Protocol) server for the [hh.ru](https://hh.ru) API:
every operation of the public hh.ru OpenAPI specification – all 135 of them –
exposed as grouped, switchable toolsets for LLM agents. stdio for personal
use, streamable HTTP with API keys and OAuth for teams.

- **Complete and verified**: 135/135 public OpenAPI operations are implemented
  and locked by a contract metatest (operations *and* required parameters);
  responses are checked against the vendored specification with live-recorded
  fixtures.
- **Safe by design**: mutations require an explicit `confirm=true` argument;
  GET requests are throttled and retried on 429, mutations never repeat
  automatically; tokens never appear in logs.
- **Built for LLMs**: domain-prefixed snake_case tool names, concise English
  descriptions, structured errors with hh.ru codes and Russian descriptions.

[Русская версия документации](README_RU.md)

## Contents

- [Requirements](#requirements)
- [Quick start](#quick-start)
  - [uvx from git (stdio)](#uvx-from-git-stdio)
  - [Docker Compose (HTTP)](#docker-compose-http)
- [Client configuration](#client-configuration)
  - [ZCode (stdio)](#zcode-stdio)
  - [Claude Desktop (stdio)](#claude-desktop-stdio)
  - [Cursor (stdio and HTTP)](#cursor-stdio-and-http)
- [Toolsets](#toolsets)
- [Authorization](#authorization)
  - [1. Static token](#1-static-token)
  - [2. Per-request token header](#2-per-request-token-header)
  - [3. OAuth login](#3-oauth-login)
  - [Registering an hh.ru application](#registering-an-hhru-application)
- [Two-level search schema](#two-level-search-schema)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [Limitations](#limitations)
- [Documented deviations](#documented-deviations)
- [Development](#development)
- [License](#license)

## Requirements

- Python 3.10 – 3.14 (CI matrix covers every minor version), or Docker.
- [uv](https://docs.astral.sh/uv/) for the uvx/stdio path.
- An hh.ru API token or a registered OAuth application for authorized calls;
  public dictionaries, suggestions and vacancy search work without a token.

## Quick start

### uvx from git (stdio)

No clone, no install – the server runs straight from the repository:

```bash
uvx --from git+https://github.com/timur-ai/ati-hh-mcp ati-hh-mcp serve --transport stdio
```

The command starts the server on stdio with the default toolsets. Point an
MCP client at it (see [client configuration](#client-configuration)) and set
`HH_TOKEN` in the server environment for authorized tools.

### Docker Compose (HTTP)

```bash
git clone https://github.com/timur-ai/ati-hh-mcp
cd ati-hh-mcp
MCP_API_KEYS="$(openssl rand -hex 32)" docker compose up --build
```

Clients connect to `http://localhost:8080/mcp` with
`Authorization: Bearer <your-api-key>`. The container is non-root, has a
`/health` endpoint for the Compose healthcheck, and keeps OAuth tokens in a
SQLite volume. See the [deployment guide](https://timur-ai.github.io/ati-hh-mcp/deployment/)
for multi-user setup.

**TLS is mandatory for network exposure**: the server speaks plain HTTP, so
put a TLS-terminating reverse proxy (Caddy/nginx) in front of it, bind the
container to `127.0.0.1` and run a single worker process – see the
[deployment guide](https://timur-ai.github.io/ati-hh-mcp/deployment/) for
ready-made proxy snippets.

## Client configuration

### ZCode (stdio)

`.zcode/settings.json` in the project (or the user config):

```json
{
  "mcpServers": {
    "hh": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/timur-ai/ati-hh-mcp",
        "ati-hh-mcp", "serve", "--transport", "stdio"
      ],
      "env": {
        "HH_TOKEN": "YOUR_HH_TOKEN",
        "HH_UA_EMAIL": "you@example.com"
      }
    }
  }
}
```

### Claude Desktop (stdio)

`claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows: `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "hh": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/timur-ai/ati-hh-mcp",
        "ati-hh-mcp", "serve", "--transport", "stdio"
      ],
      "env": {
        "HH_TOKEN": "YOUR_HH_TOKEN",
        "HH_UA_EMAIL": "you@example.com"
      }
    }
  }
}
```

### Cursor (stdio and HTTP)

`.cursor/mcp.json`. stdio launch:

```json
{
  "mcpServers": {
    "hh": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/timur-ai/ati-hh-mcp",
        "ati-hh-mcp", "serve", "--transport", "stdio"
      ],
      "env": {
        "HH_TOKEN": "YOUR_HH_TOKEN",
        "HH_UA_EMAIL": "you@example.com"
      }
    }
  }
}
```

Connection to the Docker/HTTP deployment:

```json
{
  "mcpServers": {
    "hh": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}
```

## Toolsets

62 tools are enabled by default; six employer toolsets and the undocumented
extended set are opt-in via `HH_TOOLSETS`. `HH_TOOLSETS` fully replaces the
default list; the `auth` toolset is always included regardless.
A generated catalog with every tool, its OpenAPI operation and description
lives in the [tool reference](https://timur-ai.github.io/ati-hh-mcp/tools/).

| Toolset | Tools | Default | Domain |
| --- | :---: | :---: | --- |
| `auth` | 5 | always on | `/me` profile, OAuth login/exchange/status/logout |
| `dictionaries` | 16 | on | areas, industries, professional roles, languages, locales, metro, skills, universities, vacancy conditions |
| `suggests` | 11 | on | search suggestions: areas, companies, positions, skills, keywords |
| `vacancies` | 4 | on | vacancy search, similar and related vacancies |
| `negotiations` | 10 | on | responses/invitations: lists, states, messages, tests, invitations |
| `chats` | 14 | on | chats: messages, participants, files, read counters |
| `resumes` | 2 | on | resume viewing, call-tracking phone numbers |
| `employer_vacancies` | 23 | off | employer vacancy CRUD, drafts, publication, statistics |
| `employer_negotiations` | 5 | off | employer responses/invitations, mail templates, statistics |
| `employer_resumes` | 11 | off | resume search (52 parameters), saved searches, applicant comments |
| `employer_managers` | 11 | off | managers, settings, access and limits |
| `employer_misc` | 25 | off | employers info, addresses, departments, calls, webhooks, salary statistics |
| `extended` | 4 | off | **undocumented**: apply to a vacancy, own resumes, artifacts |

Enable extra toolsets with a comma-separated list, for example
`HH_TOOLSETS=employer_vacancies,employer_resumes`.

## Authorization

The server separates *access to the MCP server* from *access to hh.ru*:

- `Authorization: Bearer <key>` (HTTP mode) – the MCP API key from
  `MCP_API_KEYS`; protects the server itself in multi-user deployments.
- `X-HH-Token: <hh-token>` – the hh.ru token for a single request (HTTP mode).
- OAuth profile – token pairs stored in SQLite per MCP API key.

An hh.ru token can be provided in three ways.

### 1. Static token

Set `HH_TOKEN` in the server environment (the usual stdio path). Applies to
every call of the deployment; in HTTP mode with `MCP_API_KEYS` set, `HH_TOKEN`
is deliberately ignored to avoid mixing user profiles.

### 2. Per-request token header

Send `X-HH-Token: <token>` with an MCP call (HTTP mode). The token is used
statelessly for that request only and is never stored.

### 3. OAuth login

With `HH_CLIENT_ID`, `HH_CLIENT_SECRET` and `HH_REDIRECT_URI` configured:

- **stdio**: call `auth_get_login_url`, open the URL in a browser, log in on
  hh.ru, copy the `code` parameter from the redirect address, then call
  `auth_exchange_code(code)`. Token pairs land in the local SQLite store and
  refresh automatically.
- **HTTP**: same flow, but the redirect goes to `GET /oauth/callback` on the
  server and the exchange completes automatically. The OAuth `state` parameter
  is bound to the caller's profile, so tokens land in the right SQLite profile.

`auth_status` shows the current profile state, `auth_logout` calls
`DELETE /token` on hh.ru and drops the stored pair.

### Registering an hh.ru application

1. Sign in at [dev.hh.ru](https://dev.hh.ru) and open the application admin.
2. Create an application; you will get `HH_CLIENT_ID` and `HH_CLIENT_SECRET`.
3. Register the redirect URI:
   - HTTP deployment: `http://<your-host>:8080/oauth/callback`
     (for local testing `http://localhost:8080/oauth/callback`);
   - stdio: any previously registered URI works – you copy the code manually.
4. Set `HH_CLIENT_ID`, `HH_CLIENT_SECRET`, `HH_REDIRECT_URI` in the server
   environment and restart.

## Two-level search schema

Heavy search operations (`search_vacancies` with 45 parameters,
`employer_search_resumes` with 52) would bury an LLM in flat arguments. Such tools use
a two-level schema: frequent filters are top-level tool parameters, the long
tail lives in a nested `advanced` object:

```json
{
  "text": "python developer",
  "area": "1",
  "salary": 200000,
  "advanced": { "work_format": "remote", "date_from": "2026-01-01" }
}
```

Unset fields – top-level or nested – are simply not sent to hh.ru. The
allowed subset is locked in the tool registry and verified by the contract
metatest, so no parameter outside the OpenAPI operation can sneak in.

## Architecture

```mermaid
flowchart LR
    A["MCP client<br/>(ZCode, Claude, Cursor)"] -- "stdio" --> S
    A -- "HTTP + Bearer MCP API key" --> S
    S["FastMCP server<br/>transports - auth middleware - /health - /oauth/callback"]
    S --> R["Registry<br/>tool = operation (135/135)"]
    S --> T["13 toolsets / 141 tools<br/>mutating tools require confirm"]
    T --> K["toolkit make_tool<br/>path/query/body packing"]
    K --> C["HHClient<br/>User-Agent - token bucket - 429 retries (GET only)"]
    C -- "HTTPS + Bearer hh.ru token" --> HH["api.hh.ru"]
    S -.-> DB[("TokenStore SQLite<br/>OAuth profiles per API key")]
    B["browser OAuth"] -.-> S
```

- **Transports**: stdio for personal launch (`uvx git+...`), streamable HTTP
  with `MCP_API_KEYS` for teams; `/health` for Docker healthchecks.
- **Registry**: the single source of truth mapping every tool to its OpenAPI
  operation; a contract metatest enforces `required params of the operation
  subset of tool params subset of operation params`.
- **HHClient**: token-bucket throttling (default 25 req/min), the User-Agent
  contact policy of hh.ru, automatic 429 retries for GET only – mutations
  fail loudly instead of repeating.
- **TokenStore**: SQLite, one OAuth profile per MCP API key (keyed by the
  sha256 hash – raw keys are never stored); automatic refresh on expiry.

## Configuration

| Environment variable | Default | Purpose |
| --- | --- | --- |
| `HH_TOKEN` | – | hh.ru token for all calls (stdio path; ignored in HTTP mode with `MCP_API_KEYS`) |
| `HH_CLIENT_ID` | – | OAuth application client id (dev.hh.ru) |
| `HH_CLIENT_SECRET` | – | OAuth application client secret |
| `HH_REDIRECT_URI` | – | OAuth redirect URI registered at dev.hh.ru |
| `HH_TOOLSETS` | default set | Comma-separated toolsets to enable; fully replaces the default list (`auth` is always included) |
| `HH_API_BASE` | `https://api.hh.ru` | API base URL (tests and experiments) |
| `HH_UA_EMAIL` | placeholder | Contact email in the User-Agent (hh.ru requirement) |
| `HH_RATE_LIMIT` | `25` | Requests per minute (token bucket) |
| `HH_TOKEN_STORE` | platform dir | SQLite path for OAuth token pairs (Docker: `/data/tokens.sqlite3`) |
| `MCP_API_KEYS` | – | Comma-separated API keys guarding the HTTP endpoint (case-sensitive) |

## Limitations

Stated honestly:

- **No resume CRUD.** The public hh.ru OpenAPI has no operations to create or
  edit resumes; the `resumes` toolset is read-only by design.
- **The extended toolset is undocumented API.** `apply_to_vacancy`,
  `my_resumes`, `artifacts_list`, `artifact_delete` rely on endpoints outside
  the public specification; they are disabled by default, marked
  `[UNDOCUMENTED hh.ru API]` and may break without notice.
- **Authorization header semantics.** `Authorization` carries the *MCP server*
  API key, not the hh.ru token; the hh.ru token travels in `X-HH-Token` or
  `HH_TOKEN`. This mirrors the two-tenant reality (server access vs hh.ru
  access) and is an intentional deviation from the hh.ru API convention.
- **Retries are GET-only.** A timed-out mutation is reported as an error with
  a "may have been applied" hint; it is never retried automatically.
- **The live API drifts from the specification.** Responses are validated
  against the vendored OpenAPI with live-recorded fixtures; the single
  confirmed deviation (`GET /suggests/companies` returns `null` in
  non-nullable `url`, `area.name`, `logo_urls`) is pinned in
  `KNOWN_DEVIATIONS` of `tests/contract/test_schemas.py`.
- **Search endpoints are geo-blocked** for datacenter IPs by hh.ru; the
  fixture recorder skips them (403 `forbidden`) when run from such networks.
  The server itself is unaffected when run from an allowed network.

## Documented deviations

From the original design decisions, recorded with reasons:

- **FastMCP 4.1** instead of "FastMCP 2": the plan fixed the family, the
  concrete major was chosen in the M1 spike by stability and Python 3.10–3.14
  support criteria; pinned in `uv.lock`. Details:
  [ADR Z1](docs/adr/Z1-fastmcp-major.md).
- **`__main__` coverage floor is 90 %**, below the project-wide 95 % – the
  CLI entrypoint is a thin argument parser around tested components.
- **Distribution is sources-only** (git + Docker): no PyPI, no GHCR, per the
  project decision.

## Development

```bash
uv sync --dev                # environment
uv run pytest -q             # 547 tests (+8 live, opt-in): unit + contract + MCP e2e
uv run ruff check src tests  # lint
uv run mypy src              # strict type check
```

Useful maintenance scripts:

```bash
uv run python scripts/record_fixtures.py    # re-record live response fixtures (read-only, sanitized)
uv run python scripts/gen_tool_docs.py      # regenerate docs/tools/ from the registry
bash scripts/fetch_openapi.sh               # refresh the vendored OpenAPI spec
uv run mkdocs serve                         # documentation site locally
```

Live integration tests (`tests/integration_live/`, marker `live`) are opt-in
and safe: read-only calls, token from the `HH_LIVE_TOKEN` secret, masked in
logs. The documentation site builds strictly (`mkdocs build --strict`) and
deploys to GitHub Pages from `main` on every push.

## License

[MIT](LICENSE)

TDQS

B3.1/5.0

Scored across 62 tools

Disambiguation3/5

Most tools target a distinct resource+action, but with 62 tools there are several near-pairs that require careful reading: dict_areas vs suggest_areas vs suggest_area_leaves, dict_metro vs dict_metro_city, suggest_positions vs suggest_vacancy_positions vs suggest_professional_roles, and list_negotiations vs list_collection_negotiations. Descriptions do clarify the boundaries (resume-side vs vacancy-side, legacy negotiations vs chats), but an agent can still misselect without close attention.

Naming Consistency4/5

Names follow a predictable, readable pattern of domain prefix + verb/noun (dict_*, suggest_*, auth_*, chat_*, negotiation_*), with clear verb_noun forms like get_resume, list_chats, send_chat_message, delete_chat_message. Minor deviations exist (e.g. get_me, similar_vacancies, related_vacancies lack a domain prefix, and auth_get_login_url mixes prefix and verb), but the overall scheme is coherent.

Tool Count2/5

62 tools far exceeds the 3-15 sweet spot and makes the surface hard for an agent to navigate; many niche dictionary/suggest endpoints could be consolidated or lazily exposed. Each tool does map to a real hh.ru endpoint, so it is not arbitrary bloat, but the count is still excessive for practical selection.

Completeness3/5

Coverage is broad across dictionaries, OAuth, negotiations, and chats (including message CRUD, file uploads, and participant management), so core workflows are reachable. However, key lifecycle operations are missing: resumes and vacancies are read-only (no create/update/publish), and applicant-side/employer-side applicant search tools are absent, leaving notable gaps.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues