iflow-mcp_gmen1057-headhunter-mcp-server 0.1.0__py3-none-any.whl

README.md

@@ -0,0 +1,314 @@
+# HeadHunter MCP Server
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP](https://img.shields.io/badge/MCP-1.0+-green.svg)](https://modelcontextprotocol.io/)
+[![HeadHunter API](https://img.shields.io/badge/HeadHunter-API%20v3-orange.svg)](https://dev.hh.ru/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[English](#english) | [Русский](#russian)
+
+---
+
+## English
+
+**MCP (Model Context Protocol) server for integrating HeadHunter API with Claude Code and other MCP clients.**
+
+HeadHunter (hh.ru) is the largest job search platform in Russia and CIS countries. This MCP server provides seamless integration with HeadHunter API, enabling AI assistants to search vacancies, manage resumes, and apply to jobs on your behalf.
+
+### Features
+
+- 🔍 **Advanced Vacancy Search** - Filter by location, salary, experience, employment type
+- 📄 **Resume Management** - View and manage your HeadHunter resumes
+- ✉️ **Job Applications** - Apply to vacancies with custom cover letters
+- 🏢 **Company Information** - Get detailed employer data
+- 📊 **Application Tracking** - Monitor your job application history
+- 🤖 **AI-Powered Agent** - Automated vacancy hunter with intelligent matching
+- 🔐 **OAuth 2.0** - Secure authorization with HeadHunter
+
+### Available Tools (10)
+
+1. **hh_search_vacancies** - Search for job vacancies
+2. **hh_get_vacancy** - Get detailed vacancy information
+3. **hh_get_employer** - Get company/employer details
+4. **hh_get_similar** - Find similar vacancies
+5. **hh_get_areas** - Get list of regions/cities
+6. **hh_get_dictionaries** - Get reference data (experience, employment types, etc.)
+7. **hh_get_resumes** - Get your resumes list
+8. **hh_get_resume** - Get detailed resume information
+9. **hh_apply_to_vacancy** - Apply to a vacancy (requires OAuth)
+10. **hh_get_negotiations** - Get application history (requires OAuth)
+
+### Quick Start
+
+#### 1. Installation
+
+```bash
+git clone https://github.com/yourusername/headhunter-mcp-server.git
+cd headhunter-mcp-server
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+#### 2. Get HeadHunter API Credentials
+
+1. Register your application at [https://dev.hh.ru/admin](https://dev.hh.ru/admin)
+2. Get Client ID, Client Secret, and App Token
+3. Copy `.env.example` to `.env` and fill in your credentials
+
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+#### 3. Configure Claude Code
+
+Add to your `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "headhunter": {
+      "type": "stdio",
+      "command": "/path/to/venv/bin/python",
+      "args": ["/path/to/headhunter-mcp-server/server.py"],
+      "env": {
+        "HH_CLIENT_ID": "your_client_id",
+        "HH_CLIENT_SECRET": "your_client_secret",
+        "HH_APP_TOKEN": "your_app_token",
+        "HH_REDIRECT_URI": "https://your-domain.com/oauth/callback"
+      }
+    }
+  }
+}
+```
+
+#### 4. OAuth Authorization (Optional)
+
+For job applications and resume management:
+
+```bash
+python examples/oauth_flow.py
+```
+
+Follow the instructions to authorize and get access tokens.
+
+### Usage Examples
+
+```bash
+# Search for Python jobs in Moscow
+Find 10 Python developer vacancies in Moscow with salary from 200000
+
+# View your resumes
+Show my resumes
+
+# Get vacancy details
+Show details for vacancy 126209046
+
+# Apply to a job (after OAuth)
+Apply to vacancy 126209046 with resume [resume_id] and cover letter: "Hello..."
+```
+
+### Vacancy Hunter Agent
+
+Automated agent for intelligent vacancy search and analysis. See [docs/vacancy-hunter-agent.md](docs/vacancy-hunter-agent.md) for details.
+
+**Features:**
+- Analyzes multiple resumes simultaneously
+- Scores vacancies by relevance (0-30 points)
+- Generates CSV reports with AI-powered recommendations
+- Focuses on Moscow region only
+
+**Usage:**
+```bash
+Run vacancy-hunter agent
+```
+
+### Project Structure
+
+```
+headhunter-mcp-server/
+├── server.py              # MCP server (10 tools)
+├── hh_client.py           # HeadHunter API client
+├── requirements.txt       # Python dependencies
+├── .env.example           # Environment variables template
+├── examples/
+│   └── oauth_flow.py      # OAuth authorization script
+└── docs/
+    └── vacancy-hunter-agent.md  # Agent documentation
+```
+
+### Requirements
+
+- Python 3.10+
+- Claude Code or any MCP-compatible client
+- HeadHunter API credentials
+
+### Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+### License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+### Links
+
+- [HeadHunter API Documentation](https://dev.hh.ru/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Code Documentation](https://docs.claude.com/en/docs/claude-code)
+
+---
+
+## Russian
+
+**MCP сервер для интеграции HeadHunter API с Claude Code и другими MCP клиентами.**
+
+HeadHunter (hh.ru) — крупнейшая платформа по поиску работы в России и странах СНГ. Этот MCP сервер обеспечивает бесшовную интеграцию с API HeadHunter, позволяя AI ассистентам искать вакансии, управлять резюме и откликаться на вакансии от вашего имени.
+
+### Возможности
+
+- 🔍 **Расширенный поиск вакансий** - Фильтрация по местоположению, зарплате, опыту, типу занятости
+- 📄 **Управление резюме** - Просмотр и управление вашими резюме на HeadHunter
+- ✉️ **Отклики на вакансии** - Подача заявок с персонализированными сопроводительными письмами
+- 🏢 **Информация о компаниях** - Получение детальных данных о работодателях
+- 📊 **Отслеживание откликов** - Мониторинг истории ваших откликов
+- 🤖 **AI-агент** - Автоматизированный поиск вакансий с умным сопоставлением
+- 🔐 **OAuth 2.0** - Безопасная авторизация через HeadHunter
+
+### Доступные инструменты (10)
+
+1. **hh_search_vacancies** - Поиск вакансий
+2. **hh_get_vacancy** - Детальная информация о вакансии
+3. **hh_get_employer** - Информация о компании/работодателе
+4. **hh_get_similar** - Поиск похожих вакансий
+5. **hh_get_areas** - Список регионов/городов
+6. **hh_get_dictionaries** - Справочные данные (опыт, типы занятости и т.д.)
+7. **hh_get_resumes** - Список ваших резюме
+8. **hh_get_resume** - Детальная информация о резюме
+9. **hh_apply_to_vacancy** - Откликнуться на вакансию (требует OAuth)
+10. **hh_get_negotiations** - История откликов (требует OAuth)
+
+### Быстрый старт
+
+#### 1. Установка
+
+```bash
+git clone https://github.com/yourusername/headhunter-mcp-server.git
+cd headhunter-mcp-server
+python -m venv venv
+source venv/bin/activate  # В Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+#### 2. Получение credentials HeadHunter API
+
+1. Зарегистрируйте приложение на [https://dev.hh.ru/admin](https://dev.hh.ru/admin)
+2. Получите Client ID, Client Secret и App Token
+3. Скопируйте `.env.example` в `.env` и заполните свои credentials
+
+```bash
+cp .env.example .env
+# Отредактируйте .env своими credentials
+```
+
+#### 3. Настройка Claude Code
+
+Добавьте в `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "headhunter": {
+      "type": "stdio",
+      "command": "/путь/к/venv/bin/python",
+      "args": ["/путь/к/headhunter-mcp-server/server.py"],
+      "env": {
+        "HH_CLIENT_ID": "ваш_client_id",
+        "HH_CLIENT_SECRET": "ваш_client_secret",
+        "HH_APP_TOKEN": "ваш_app_token",
+        "HH_REDIRECT_URI": "https://ваш-домен.com/oauth/callback"
+      }
+    }
+  }
+}
+```
+
+#### 4. OAuth авторизация (опционально)
+
+Для откликов на вакансии и управления резюме:
+
+```bash
+python examples/oauth_flow.py
+```
+
+Следуйте инструкциям для авторизации и получения токенов доступа.
+
+### Примеры использования
+
+```bash
+# Поиск Python вакансий в Москве
+Найди 10 вакансий Python разработчика в Москве с зарплатой от 200000
+
+# Просмотр резюме
+Покажи мои резюме
+
+# Детали вакансии
+Покажи детали вакансии 126209046
+
+# Отклик на вакансию (после OAuth)
+Откликнись на вакансию 126209046 резюме [resume_id] с письмом: "Здравствуйте..."
+```
+
+### Vacancy Hunter Agent
+
+Автоматизированный агент для умного поиска и анализа вакансий. Подробности в [docs/vacancy-hunter-agent.md](docs/vacancy-hunter-agent.md).
+
+**Возможности:**
+- Анализирует несколько резюме одновременно
+- Оценивает релевантность вакансий (0-30 баллов)
+- Генерирует CSV отчёты с AI рекомендациями
+- Фокусируется только на регионе Москва
+
+**Использование:**
+```bash
+Запусти агента vacancy-hunter
+```
+
+### Структура проекта
+
+```
+headhunter-mcp-server/
+├── server.py              # MCP сервер (10 инструментов)
+├── hh_client.py           # HeadHunter API клиент
+├── requirements.txt       # Python зависимости
+├── .env.example           # Шаблон переменных окружения
+├── examples/
+│   └── oauth_flow.py      # Скрипт OAuth авторизации
+└── docs/
+    └── vacancy-hunter-agent.md  # Документация агента
+```
+
+### Требования
+
+- Python 3.10+
+- Claude Code или любой MCP-совместимый клиент
+- HeadHunter API credentials
+
+### Участие в разработке
+
+Приветствуются любые вклады! Не стесняйтесь отправлять Pull Request.
+
+### Лицензия
+
+MIT License - подробности в файле [LICENSE](LICENSE).
+
+### Ссылки
+
+- [Документация HeadHunter API](https://dev.hh.ru/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Документация Claude Code](https://docs.claude.com/en/docs/claude-code)
+
+---
+
+**Made with ❤️ for the HeadHunter and MCP community**

docs/vacancy-hunter.md

@@ -0,0 +1,150 @@
+---
+name: vacancy-hunter
+description: Analyzes user's resumes and finds relevant vacancies on HeadHunter, creates CSV reports with AI-powered matching scores
+tools: mcp__headhunter__hh_get_resume, mcp__headhunter__hh_search_vacancies, mcp__headhunter__hh_get_vacancy, Write, Bash
+model: inherit
+---
+
+# Vacancy Hunter Agent
+
+You are an autonomous agent that searches and analyzes job vacancies on HeadHunter for the user.
+
+## Your Mission
+
+Analyze user's resumes, search for relevant vacancies in Moscow, evaluate matches, and create detailed CSV reports with recommendations.
+
+## Target Resumes
+
+Always analyze these 3 resumes:
+1. **Head of Product** - ID: `7b7f2ea6ff0838f1ea0039ed1f704b31506463`
+2. **Директор по электронной коммерции** - ID: `3d8654a4ff0f05c0590039ed1f4c5957513858`
+3. **Операционный директор** - ID: `42b7d11eff0e77905f0039ed1f744a72386174`
+
+## Search Criteria
+
+**Location:** Only Moscow (area=1)
+**Ignore:** Salary, experience requirements
+**Focus:** Job title, description, company, key skills match
+
+## Workflow
+
+### 1. Load Resumes
+```
+For each resume_id:
+  - Call mcp__headhunter__hh_get_resume(resume_id)
+  - Extract: title, skills, experience, key competencies
+  - Create skill keywords list
+```
+
+### 2. Search Vacancies
+```
+For each resume:
+  - Search by job title keywords
+  - Filter: area=1 (Moscow), per_page=50
+  - Get 50-100 relevant vacancies
+```
+
+### 3. Analyze Each Vacancy
+```
+For each vacancy:
+  - Get full details with mcp__headhunter__hh_get_vacancy
+  - Match against resume:
+    * Title similarity (0-10)
+    * Skills overlap (0-10)
+    * Description relevance (0-10)
+  - Calculate total_score (0-30)
+  - Write brief AI comment (1-2 sentences)
+```
+
+### 4. Generate CSV Report
+```
+Filename: vacancies_report_YYYY-MM-DD_HH-MM.csv
+Location: /root/vacancy-reports/
+
+Columns:
+- vacancy_id: HH vacancy ID
+- title: Job title
+- company: Company name
+- salary: Salary range or "Not specified"
+- url: Direct link to vacancy
+- resume_matched: Which resume (Head of Product / Ecommerce Director / COO)
+- match_score: Total score (0-30)
+- title_score: Title match (0-10)
+- skills_score: Skills match (0-10)
+- relevance_score: Description relevance (0-10)
+- ai_comment: Your brief analysis
+- found_at: Timestamp
+
+Sort by: match_score DESC
+Filter: Only include score >= 15 (50%+ match)
+```
+
+## Analysis Guidelines
+
+**High Match (25-30):**
+- Perfect title match
+- 80%+ key skills overlap
+- Job description perfectly aligns with resume experience
+
+**Medium Match (20-24):**
+- Similar title or role
+- 50-80% skills overlap
+- Good experience alignment
+
+**Low Match (15-19):**
+- Related field
+- 30-50% skills overlap
+- Partial experience match
+
+**AI Comment Examples:**
+- "Perfect match: Product leadership role with marketplace experience"
+- "Good fit: E-commerce director with P&L responsibility"
+- "Relevant: Operations role in tech company, lacks product focus"
+
+## Important Rules
+
+1. **DO NOT apply** to any vacancies
+2. **DO NOT write** cover letters
+3. **DO create** detailed CSV reports only
+4. Search 50-100 vacancies per resume (150-300 total)
+5. Report only matches with score >= 15
+6. Always include timestamp in filename
+7. Save reports to `/root/vacancy-reports/`
+
+## Success Metrics
+
+- CSV file created successfully
+- At least 20-50 quality matches found
+- Scores are realistic and well-justified
+- Comments are concise and actionable
+- User can easily review and select vacancies
+
+## Example Output
+
+After completion, report:
+```
+✅ Vacancy search completed!
+
+Analyzed:
+- Head of Product: 87 vacancies → 23 matches (score ≥15)
+- Ecommerce Director: 64 vacancies → 18 matches
+- COO: 73 vacancies → 15 matches
+
+Total: 224 vacancies analyzed, 56 quality matches found
+
+Report saved: /root/vacancy-reports/vacancies_report_2025-10-08_14-30.csv
+
+Top matches:
+1. [126xxx] Product Director @ Tech Company (score: 28/30)
+2. [125xxx] Head of E-commerce @ Marketplace (score: 27/30)
+3. [124xxx] COO @ FinTech Startup (score: 26/30)
+```
+
+## Error Handling
+
+- If resume not found: Skip and continue with others
+- If search returns 0 results: Try broader keywords
+- If API rate limit hit: Wait 60 seconds and retry
+- Always complete report even if some resumes fail
+
+Now go find the best job opportunities! 🎯

examples/README.md

@@ -0,0 +1,90 @@
+# Examples
+
+## OAuth Authorization
+
+To use features that require authentication (applying to vacancies, viewing resumes), you need to complete OAuth authorization.
+
+### oauth_flow.py
+
+Interactive script for obtaining OAuth tokens.
+
+**Usage:**
+
+```bash
+python examples/oauth_flow.py
+```
+
+**Steps:**
+
+1. Script generates authorization URL
+2. Open URL in browser and authorize the application
+3. Copy the authorization code from redirect URL
+4. Paste code into terminal
+5. Tokens are automatically saved to `.env`
+
+**What you'll get:**
+
+- `HH_ACCESS_TOKEN` - for making authenticated requests
+- `HH_REFRESH_TOKEN` - for refreshing access token when it expires
+
+**Token lifetime:** Access tokens expire after ~14 days. Use refresh token to get new access token.
+
+## Example Queries
+
+Once the MCP server is configured in Claude Code, you can use natural language queries:
+
+### Search Vacancies
+
+```
+Find 10 Python developer jobs in Moscow with salary above 200000
+```
+
+```
+Search for remote Product Manager positions
+```
+
+### View Resumes
+
+```
+Show my resumes
+```
+
+```
+Show details of resume with ID abc123
+```
+
+### Apply to Jobs
+
+```
+Apply to vacancy 126209046 with my Python Developer resume
+```
+
+```
+Apply to vacancy 123456 with resume xyz789 and cover letter: "Dear Hiring Manager, I am excited to apply..."
+```
+
+### Track Applications
+
+```
+Show my last 20 job applications
+```
+
+```
+Show status of my applications from this month
+```
+
+## Advanced: Using Vacancy Hunter Agent
+
+The automated agent can search and analyze vacancies across multiple resumes:
+
+```
+Run vacancy-hunter agent
+```
+
+The agent will:
+1. Load your specified resumes
+2. Search for relevant vacancies
+3. Score each vacancy by match quality (0-30 points)
+4. Generate CSV report with recommendations
+
+Results are saved to `/root/vacancy-reports/` (or your configured path).