# theyahia/hh-mcp architecture

> Architecture diagram of the GitHub repository theyahia/hh-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theyahia/hh-mcp
- Repository: https://github.com/theyahia/hh-mcp

## Overview

This is an MCP server exposing hh.ru recruiting data to AI-agent clients. The main workflow is a tool request over stdio or Streamable HTTP, dispatch through registered handlers, query the hh.ru API, and return either compact summaries or raw JSON. Its tool families cover vacancies, resumes, employers, reference data and suggestions, salary estimates, and token validation. The sampled source shows the client and several handler-to-client/formatter calls; unsampled handler details are represented from the README, so their internal call paths are not inferred.

Main entry points: [`src/index.ts`](https://github.com/theyahia/hh-mcp/blob/main/src/index.ts) (MCP server), [`src/client.ts`](https://github.com/theyahia/hh-mcp/blob/main/src/client.ts) (API client), [`src/format.ts`](https://github.com/theyahia/hh-mcp/blob/main/src/format.ts) (Response formatting), [`src/tools/vacancies.ts`](https://github.com/theyahia/hh-mcp/blob/main/src/tools/vacancies.ts) (Vacancy tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_server["MCP server<br/>[index.ts]"]
end

subgraph group_domains["Recruiting tools"]
  node_vacancies["Vacancy tools<br/>[vacancies.ts]"]
  node_resumes["Resume tools<br/>[resumes.ts]"]
  node_employers["Employer tools<br/>[employers.ts]"]
  node_references["Reference tools<br/>[references.ts]"]
  node_salary["Salary estimates<br/>[salary.ts]"]
end

subgraph group_shared["Shared services"]
  node_client["API client<br/>[client.ts]"]
  node_format["Response formatting<br/>[format.ts]"]
end

subgraph group_external["External systems"]
  node_hhapi["hh.ru API"]
end

node_agent(("AI agent"))

node_agent -->|"requests tools"| node_server
node_server -->|"returns results"| node_agent
node_server -->|"dispatches"| node_vacancies
node_server -->|"dispatches"| node_resumes
node_server -->|"dispatches"| node_employers
node_server -->|"dispatches"| node_references
node_server -->|"dispatches"| node_salary
node_vacancies -->|"requests data"| node_client
node_vacancies -->|"formats results"| node_format
node_resumes -->|"requests data"| node_client
node_resumes -->|"formats results"| node_format
node_employers -->|"requests data"| node_client
node_employers -->|"formats results"| node_format
node_references -->|"requests data"| node_client
node_references -->|"flattens areas"| node_format
node_salary -->|"samples vacancies"| node_client
node_salary -->|"formats salary"| node_format
node_client -->|"fetches API"| node_hhapi

click node_server "https://github.com/theyahia/hh-mcp/blob/main/src/index.ts"
click node_vacancies "https://github.com/theyahia/hh-mcp/blob/main/src/tools/vacancies.ts"
click node_resumes "https://github.com/theyahia/hh-mcp/blob/main/src/tools/resumes.ts"
click node_employers "https://github.com/theyahia/hh-mcp/blob/main/src/tools/employers.ts"
click node_references "https://github.com/theyahia/hh-mcp/blob/main/src/tools/references.ts"
click node_salary "https://github.com/theyahia/hh-mcp/blob/main/src/tools/salary.ts"
click node_client "https://github.com/theyahia/hh-mcp/blob/main/src/client.ts"
click node_format "https://github.com/theyahia/hh-mcp/blob/main/src/format.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server toneBlue
class node_vacancies,node_resumes,node_employers,node_references,node_salary toneAmber
class node_client,node_format toneMint
class node_hhapi toneRose
class node_agent toneIndigo
```

## Components

### MCP entry

- [MCP server](https://github.com/theyahia/hh-mcp/blob/main/src/index.ts): `src/index.ts`

### Recruiting tools

- [Vacancy tools](https://github.com/theyahia/hh-mcp/blob/main/src/tools/vacancies.ts): `src/tools/vacancies.ts`
- [Resume tools](https://github.com/theyahia/hh-mcp/blob/main/src/tools/resumes.ts): `src/tools/resumes.ts`
- [Employer tools](https://github.com/theyahia/hh-mcp/blob/main/src/tools/employers.ts): `src/tools/employers.ts`
- [Reference tools](https://github.com/theyahia/hh-mcp/blob/main/src/tools/references.ts): `src/tools/references.ts`
- [Salary estimates](https://github.com/theyahia/hh-mcp/blob/main/src/tools/salary.ts): `src/tools/salary.ts`

### Shared services

- [API client](https://github.com/theyahia/hh-mcp/blob/main/src/client.ts): `src/client.ts`
- [Response formatting](https://github.com/theyahia/hh-mcp/blob/main/src/format.ts): `src/format.ts`

### External systems

- **hh.ru API**

### Other components

- **AI agent**

## Connections

- AI agent → MCP server: requests tools (evidence: `README.md`)
- MCP server → AI agent: returns results (evidence: `README.md`)
- MCP server → Vacancy tools: dispatches (evidence: `src/index.ts`)
- MCP server → Resume tools: dispatches (evidence: `src/index.ts`)
- MCP server → Employer tools: dispatches (evidence: `src/index.ts`)
- MCP server → Reference tools: dispatches (evidence: `src/index.ts`)
- MCP server → Salary estimates: dispatches (evidence: `src/index.ts`)
- Vacancy tools → API client: requests data (evidence: `src/tools/vacancies.ts`)
- Vacancy tools → Response formatting: formats results (evidence: `src/tools/vacancies.ts`)
- Resume tools → API client: requests data (evidence: `src/tools/resumes.ts`)
- Resume tools → Response formatting: formats results (evidence: `src/tools/resumes.ts`)
- Employer tools → API client: requests data (evidence: `src/tools/employers.ts`)
- Employer tools → Response formatting: formats results (evidence: `src/tools/employers.ts`)
- Reference tools → API client: requests data (evidence: `src/tools/references.ts`)
- Reference tools → Response formatting: flattens areas (evidence: `src/tools/references.ts`)
- Salary estimates → API client: samples vacancies (evidence: `src/tools/salary.ts`)
- Salary estimates → Response formatting: formats salary (evidence: `src/tools/salary.ts`)
- API client → hh.ru API: fetches API (evidence: `src/client.ts`)
