@sargonpiraev/hh-mcp-server 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sargon Piraev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,133 @@
+# HeadHunter MCP Server
+
+![npm version](https://img.shields.io/npm/v/@sargonpiraev/hh-mcp-server)
+![smithery badge](https://smithery.ai/badge/@sargonpiraev/hh-mcp-server)
+
+MCP Server for HeadHunter API - job search and vacancy management
+
+## Features
+
+- 🔍 User Profile Management - View and manage your HeadHunter profile
+- 📄 Resume Management - View detailed resume information
+- 💼 Job Application Management - Manage negotiations and communications with employers
+- ⭐ Vacancy Search & Favorites - Search for jobs and manage your favorites
+
+## Get Your Credentials
+
+Before installation, you'll need to obtain your API credentials:
+
+1. **HH_USER_AGENT**: User-Agent header for HeadHunter API requests (required by HH API)
+
+Save these credentials for the installation steps below.
+
+## Installation
+
+<details>
+<summary><b>Installing via Smithery</b></summary>
+
+To install HeadHunter MCP Server for any client automatically via [Smithery](https://smithery.ai):
+
+```bash
+npx -y @smithery/cli@latest install @sargonpiraev/hh-mcp-server --client <CLIENT_NAME>
+```
+
+</details>
+
+<details>
+<summary><b>Install in Cursor</b></summary>
+
+#### Cursor One-Click Installation
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=@sargonpiraev/hh-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzYXJnb25waXJhZXYvaGFiaXRpZnktbWNwLXNlcnZlciJdLCJlbnYiOnsiSEFCSVRJRllfQVBJX0tFWSI6InlvdXItaGFiaXRpZnktYXBpLWtleSJ9fQo=)
+
+#### Manual Configuration
+
+Add to your Cursor `~/.cursor/mcp.json` file:
+
+```json
+{
+  "mcpServers": {
+    "hh-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@sargonpiraev/hh-mcp-server"],
+      "env": {
+        "HH_USER_AGENT": "your-HH_USER_AGENT-here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in VS Code</b></summary>
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF)](vscode:mcp/install?%7B%22name%22%3A%22hh-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22@sargonpiraev/hh-mcp-server%22%5D%7D)
+
+Or add manually to your VS Code settings:
+
+```json
+"mcp": {
+  "servers": {
+    "hh-mcp-server": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@sargonpiraev/hh-mcp-server"],
+      "env": {
+        "HH_USER_AGENT": "your-HH_USER_AGENT-here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Install in Claude Desktop</b></summary>
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "hh-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@sargonpiraev/hh-mcp-server"],
+      "env": {
+        "HH_USER_AGENT": "your-HH_USER_AGENT-here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## Available Tools
+
+- **`get-vacancies`**: Execute get-vacancies operation
+- **`get-dictionaries`**: Execute get-dictionaries operation
+- **`get-areas`**: Execute get-areas operation
+- **`get-languages`**: Execute get-languages operation
+- **`get-industries`**: Execute get-industries operation
+- **`get-metro`**: Execute get-metro operation
+- **`get-professional-roles`**: Execute get-professional-roles operation
+- **`get-employers`**: Execute get-employers operation
+
+**Total: 8 tools available** 🎯
+
+## Support This Project
+
+Hi! I'm Sargon, a software engineer passionate about AI tools and automation. I create open-source MCP servers to help developers integrate AI assistants with their favorite services.
+
+Your support helps me continue developing and maintaining these tools, and motivates me to create new integrations that make AI assistants even more powerful! 🚀
+
+[![Support on Boosty](https://img.shields.io/badge/Support-Boosty-orange?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTEyIDJMMTMuMDkgOC4yNkwyMCA5TDEzLjA5IDE1Ljc0TDEyIDIyTDEwLjkxIDE1Ljc0TDQgOUwxMC45MSA4LjI2TDEyIDJaIiBmaWxsPSJ3aGl0ZSIvPgo8L3N2Zz4K)](https://boosty.to/sargonpiraev)
+
+## Connect with Author
+
+- 🌐 Visit [sargonpiraev.com](https://sargonpiraev.com)
+- 📧 Email: [sargonpiraev@gmail.com](mailto:sargonpiraev@gmail.com)
+- 💬 Join [Discord](https://discord.gg/ZsWGxRGj)

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import axios from 'axios';
+import dotenv from 'dotenv';
+// Load environment variables
+dotenv.config();
+// Environment configuration schema
+const envSchema = z.object({
+    HH_USER_AGENT: z.string().min(1),
+    //  TOOL_GLOB_PATTERNS: z.string().optional(),
+    //  LOG_LEVEL: z.enum(['debug', 'info', 'notice', 'warning', 'error']).default('info').optional(),
+});
+// Parse and validate environment variables
+const env = envSchema.parse(process.env);
+const mcpServer = new McpServer({
+    name: '@sargonpiraev/hh-mcp-server',
+    version: '',
+}, {
+    capabilities: {
+        tools: {},
+        logging: {},
+    },
+    instructions: `MCP Server for HeadHunter API - job search and vacancy management`,
+});
+const logger = {
+    log: (...message) => mcpServer.server.sendLoggingMessage({
+        level: 'info',
+        data: message.join(' '),
+    }),
+    error: (...message) => mcpServer.server.sendLoggingMessage({
+        level: 'error',
+        data: message.join(' '),
+    }),
+    debug: (...message) => mcpServer.server.sendLoggingMessage({
+        level: 'debug',
+        data: message.join(' '),
+    }),
+};
+// Axios client setup
+const apiClient = axios.create({
+    baseURL: 'https://api.hh.ru',
+    headers: {
+        Accept: 'application/json',
+    },
+    timeout: 30000,
+});
+// Add request interceptor for environment variables
+apiClient.interceptors.request.use((config) => {
+    if (env.HH_USER_AGENT) {
+        config.headers['User-Agent'] = env.HH_USER_AGENT;
+    }
+    return config;
+}, (error) => {
+    return Promise.reject(error);
+});
+function handleError(error) {
+    console.error(error);
+    logger.error('Error occurred:', JSON.stringify(error));
+    if (axios.isAxiosError(error)) {
+        const message = error.response?.data?.description || error.message;
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `API Error: ${message}` }],
+        };
+    }
+    return {
+        isError: true,
+        content: [{ type: 'text', text: `Error: ${error}` }],
+    };
+}
+// Tools
+mcpServer.tool('get-vacancies', `Search for vacancies`, {}, async (args) => {
+    try {
+        const response = await apiClient.get('/vacancies', {
+            params: args,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleError(error);
+    }
+});
+mcpServer.tool('get-dictionaries', `Directories of fields`, {}, async (args) => {
+    try {
+        const response = await apiClient.get('/dictionaries', {
+            params: args,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleError(error);
+    }
+});
+mcpServer.tool('get-areas', `Tree view of all regions`, {}, async (args) => {
+    try {
+        const response = await apiClient.get('/areas', {
+            params: args,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleError(error);
+    }
+});
+mcpServer.tool('get-languages', `The list of all languages`, {}, async (args) => {
+    try {
+        const response = await apiClient.get('/languages', {
+            params: args,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleError(error);
+    }
+});
+mcpServer.tool('get-industries', `Industries`, {}, async (args) => {
+    try {
+        const response = await apiClient.get('/industries', {
+            params: args,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleError(error);
+    }
+});
+mcpServer.tool('get-metro', `The list of metro stations in all cities`, {}, async (args) => {
+    try {
+        const response = await apiClient.get('/metro', {
+            params: args,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleError(error);
+    }
+});
+mcpServer.tool('get-professional-roles', `Professional role directory`, {}, async (args) => {
+    try {
+        const response = await apiClient.get('/professional_roles', {
+            params: args,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleError(error);
+    }
+});
+mcpServer.tool('get-employers', `Employer search`, {}, async (args) => {
+    try {
+        const response = await apiClient.get('/employers', {
+            params: args,
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleError(error);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await mcpServer.server.connect(transport);
+    logger.log('HeadHunter MCP Server started');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@sargonpiraev/hh-mcp-server",
+  "version": "1.1.0",
+  "description": "MCP Server for HeadHunter API - job search and vacancy management",
+  "keywords": [
+    "mcp",
+    "claude",
+    "ai",
+    "assistant"
+  ],
+  "main": "./build/main.js",
+  "types": "./build/main.d.ts",
+  "type": "module",
+  "files": [
+    "build/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest --passWithNoTests --coverage",
+    "dev": "tsx watch ./src/main.ts",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint ./src --ext .ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "commitlint": "commitlint --edit",
+    "typecheck": "tsc --noEmit",
+    "audit": "npm audit --omit=dev",
+    "inspect": "npx @modelcontextprotocol/inspector node ./build/main.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.0",
+    "@eslint/js": "^9.26.0",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^11.0.0",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.0.3",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^22.15.3",
+    "eslint": "^9.26.0",
+    "globals": "^16.0.0",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "jest-junit": "^16.0.0",
+    "prettier": "^3.5.3",
+    "semantic-release": "^24.2.3",
+    "ts-jest": "^29.3.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.31.1",
+    "@types/minimatch": "^5.1.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "dotenv": "^16.5.0",
+    "zod": "^3.24.3",
+    "axios": "^1.7.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": {
+    "name": "Sargon Piraev",
+    "email": "sargonpiraev@gmail.com",
+    "url": "https://sargonpiraev.com"
+  },
+  "license": "MIT"
+}