@sargonpiraev/hh-mcp-server 1.14.0 → 1.16.0

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@sargonpiraev/hh-mcp-server",
-  "version": "1.14.0",
-  "description": "MCP Server for HeadHunter API - job search and vacancy management",
+  "version": "1.16.0",
+  "description": "HeadHunter API MCP Server provides seamless integration between AI tools and HeadHunter's comprehensive job search platform.",
   "keywords": [
     "mcp",
     "claude",
     "ai",
-    "assistant"
+    "assistant",
+    "hh"
   ],
-  "main": "./build/index.js",
-  "types": "./build/index.d.ts",
+  "main": "./build/main.js",
+  "types": "./build/main.d.ts",
   "type": "module",
   "files": [
     "build/",
@@ -17,11 +18,11 @@
     "LICENSE"
   ],
   "bin": {
-    "hh-mcp-server": "./build/index.js"
+    "hh-mcp-server": "./build/main.js"
   },
   "scripts": {
     "test": "jest --passWithNoTests --coverage",
-    "dev": "tsx watch ./src/index.ts",
+    "dev": "tsx watch ./src/main.ts",
     "build": "tsc -p tsconfig.json",
     "lint": "eslint ./src --ext .ts",
     "format": "prettier --write .",
@@ -30,11 +31,19 @@
     "commitlint": "commitlint --edit",
     "typecheck": "tsc --noEmit",
     "audit": "npm audit --omit=dev",
-    "inspect": "npx @modelcontextprotocol/inspector node ./build/index.js"
+    "inspect": "npx @modelcontextprotocol/inspector --config mcp.json --server hh"
   },
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "dotenv": "^16.5.0",
+    "zod": "^3.24.3",
+    "axios": "^1.7.7",
+    "express": "^4.18.2",
+    "cors": "^2.8.5"
+  },
   "devDependencies": {
     "@commitlint/cli": "^19.8.0",
     "@commitlint/config-conventional": "^19.8.0",
@@ -45,6 +54,8 @@
     "@semantic-release/release-notes-generator": "^14.0.3",
     "@types/debug": "^4.1.12",
     "@types/node": "^22.15.3",
+    "@types/express": "^4.17.17",
+    "@types/cors": "^2.8.13",
     "eslint": "^9.26.0",
     "globals": "^16.0.0",
     "husky": "^9.1.7",
@@ -59,19 +70,17 @@
     "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"
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "bugs": {
+    "url": ""
   },
-  "license": "MIT"
+  "homepage": "",
+  "author": "",
+  "license": ""
 }

package/build/index.d.ts

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

package/build/index.js

@@ -1,499 +0,0 @@
-#!/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';
-dotenv.config();
-const envSchema = z.object({
-    HH_API_TOKEN: z.string(),
-});
-const env = envSchema.parse(process.env);
-const mcpServer = new McpServer({
-    name: '@sargonpiraev/hh-mcp-server',
-    version: '',
-}, {
-    instructions: `In English | [По-русски](https://api.hh.ru/openapi/redoc)
-
-Documentation [in GitHub](https://github.com/hhru/api/blob/master/docs_eng/README.md).
-
-You can use Ctrl+F to search through the documentation.
-
-# General information
-  
-* The whole API works using the HTTPS protocol.
-* Authorization is performed via the OAuth2 protocol.
-* All data is available only in the JSON format.
-* The basic URL is `https://api.hh.ru/`
-* Requests for [any site of HeadHunter Groups of Companies](#section/General-information/Host-selection)
-are available
-* <a name="date-format"></a> Dates are formatted according to
-[ISO 8601](http://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss±hhmm`.
-  
-  
-  ## Request requirements
-  
-  Your request should send the `User-Agent` header, but if your
-  HTTP client does not allow it, you can send an `HH-User-Agent` header. If no header is sent,
-  you will receive the `400 Bad Request` as a response.
-  By specifying the name of the application and the developer's contact email in the header,
-  you will help us to contact you promptly if required.
-  The `User-Agent` and `HH-User-Agent` headers are interchangeable. If you send both headers,
-  only `HH-User-Agent` is processed.
-  
-  ```
-User-Agent: MyApp/1.0 (my-app-feedback@example.com)
-  ```
-  
-  More detail on [errors in the User-Agent title](https://github.com/hhru/api/blob/master/docs_eng/errors.md#user-agent).
-  
-  
-### Request body format when sending JSON
-
-Data transferred in the request body must meet the requirements:
-  
-  * Valid JSON (it is acceptable to transfer both minified and
-  pretty-printed variants with extra whitespace and line breaks).
-  
-  * It is recommended to use the UTF-8 encoding without extra escaping
-(`{"name": "Иванов Иван"}`).
-  
-  * It is also possible to use the ascii encoding with escaping
-(`{"name": "\u0418\u0432\u0430\u043d\u043e\u0432 \u0418\u0432\u0430\u043d"}`).
-  
-  * Data types in certain fields are supplemented with additional conditions
-  described in each specific method. In JSON, data types are `string`, `number`,
-  `boolean`, `null`, `object`, `array`.
-  
-  ### Response
-  A response that exceeds a certain length will be compressed using gzip.
-  
-  ### Errors and response codes
-  
-  API extensively uses informing through response codes.
-  The application must process them correctly.
-  
-  In case of failure or breakdown, responses with the `503` and `500` code may be
-  returned.
-  
-  When an error occurs, the response body, besides the response code,
-  may have additional information allowing the developer
-  to learn the cause of a particular response.
-  
-  [More detail on possible errors](https://github.com/hhru/api/blob/master/docs_eng/errors.md).
-  
-  
-  ## Undocumented fields and request parameters
-  
-  In responses and API parameters you can find keys that are not described in the
-  documentation. It usually means that they are left for compatibility with older
-  versions. It is not recommended to use them. If your application already uses
-  such keys, switch to using desirable keys described in the documentation.
-  
-  
-  ## Pagination
-  
-  For every request that presupposes the return of object list you can indicate
-  `page=N&per_page=M` in the parameters. Numeration starts from zero; the first
-  (zero) page is returned by default with 20 objects on it. In all responses where
-pagination is available, the uniform root object:
-  
-  ```json
-  {
-    "found": 1,
-    "per_page": 1,
-    "pages": 1,
-    "page": 0,
-    "items": [{}]
-  }
-  ```
-  
-  ## Host selection
-      
-  HeadHunter API allows you to obtain data from all of the HeadHunter group of
-  companies websites.
-    
-  In particular:
-
-  * hh.ru
-  * rabota.by
-  * hh1.az
-  * hh.uz
-  * hh.kz
-  * headhunter.ge
-  * headhunter.kg
-      
-  Requests for data on all the websites should be made to `https://api.hh.ru/`.
-      
-  If you need to track the specific websites, you can add `?host=` parameter to
-      your request. Default is `hh.ru`.
-    
-  Example: to obtain [localizations](https://api.hh.ru/openapi/en/redoc#tag/Public-directories/operation/get-locales) available on hh.kz, you should
-      make a GET-request to `https://api.hh.ru/locales?host=hh.kz`.
-  
-  ## CORS (Cross-Origin Resource Sharing)
-  
-  API supports the CORS technology for requesting browser data from any domain.
-  This method is preferable to JSONP. It is not restricted to the GET method. To
-  debug CORS, a [special method](https://github.com/hhru/api/blob/master/docs_eng/cors.md) is available. To use JSONP, transfer the
-  `?callback=callback_name` parameter.
-  
-  * [CORS specification on w3.org](http://www.w3.org/TR/cors/)
-  * [HTML5Rocks CORS Tutorial](http://www.html5rocks.com/en/tutorials/cors/)
-  * [CORS on dev.opera.com](http://dev.opera.com/articles/view/dom-access-control-using-cross-origin-resource-sharing/)
-  * [CORS on caniuse.com](http://caniuse.com/#feat=cors)
-  * [CORS on en.wikipedia.org](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
-  
-  
-## External links to articles and standards
-  
-* [HTTP/1.1](http://tools.ietf.org/html/rfc2616)
-* [JSON](http://json.org/)
-* [URI Template](http://tools.ietf.org/html/rfc6570)
-* [OAuth 2.0](http://tools.ietf.org/html/rfc6749)
-* [REST](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)
-* [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601)
-
-# Authorization
-
-The API supports the following authorization levels:
-  - [application authorization](#tag/Application-authorization)
-  - [user authorization](#section/Authorization/User-authorization)
-
-* [Obtaining user authorization](#section/Authorization/User-authorization)
-  * [Rules for generating special `redirect_uri`](#section/Authorization/Rules-for-generating-special-redirect_uri)
-  * [Authorization process](#section/Authorization/Authorization-process)
-  * [Successful obtaining temporary `authorization_code`](#get-authorization_code)
-  * [Obtaining access and refresh tokens](#section/Authorization/Obtaining-access-and-refresh-tokens)
-* [Updating a pair of access and refresh tokens](#section/Authorization/Updating-a-pair-of-access-and-refresh-tokens)
-* [Authorization request under another user](#section/Authorization/Authorization-request-under-another-user)
-* [Authorization under different working account](#section/Authorization/Authorization-under-different-working-account)
-* [Obtaining application authorization](#tag/Application-authorization)
-
-
-## User authorization
-To make requests as a user you need a user token.
-
-Assign a user to the application (open the page) via the request:
-
-```
-https://hh.ru/oauth/authorize?
-response_type=code&
-client_id={client_id}&
-state={state}&
-redirect_uri={redirect_uri}
-```
-
-Required parameters:
-
-* `response_type=code` — specifies authorization method using the `authorization code`
-* `client_id` — ID obtained when creating the application
-
-
-Optional parameters:
-
-* `state` — if specified, it will be added in the redirect link of the response. 
-
-  It allows to prevent cross-site request forgery. More info see in [RFC 6749. Section 10.12](http://tools.ietf.org/html/rfc6749#section-10.12)
-* `redirect_uri` — a URI for redirecting user after authorization. 
-
-  If not specified, the value from the application settings is used. If the value is specified, its validation is carried out. Probably, you will need to make `urlencode` of the value.
-
-## Rules for generating special redirect_uri
-
-For example, if `http://example.com/oauth` is saved in the settings, it is allowed to specify:
-
-* `http://www.example.com/oauth` — a subdomain;
-* `http://www.example.com/oauth/sub/path` — a detailed path;
-* `http://example.com/oauth?lang=RU` — an additional parameter;
-* `http://www.example.com/oauth/sub/path?lang=RU` — all the mentioned.
-
-Forbidden:
-
-* `https://example.com/oauth` — another protocols;
-* `http://wwwexample.com/oauth` — another domains;
-* `http://wwwexample.com/` — another paths;
-* `http://example.com/oauths` — another paths;
-* `http://example.com:80/oauths` — originally missing port.
-
-## Authorization process
-
-If the user is not authorized, the site login form appears. When the authorization is done, the form with subject access request is shown.
-
-If the user rejects the access request, it triggers the redirection on the specified `redirect_uri` with `?error=access_denied` and
-`state={state}`, if any.
-
-<a name="get-authorization_code"></a>
-### Successful obtaining temporary `authorization_code`
-
-If the user accepts the access request, the redirect link contains a temporary `authorization_code`:
-
-```http
-HTTP/1.1 302 FOUND
-Location: {redirect_uri}?code={authorization_code}
-```
-
-If the user is already authorized, and the access to the application was granted earlier, then the login and subject access request are omitted, and the above redirect link returns as a response.
-
-## Obtaining access and refresh tokens
-
-After obtaining the `authorization_code` the application makes a server-server request `POST https://api.hh.ru/token` to exchange the `authorization_code` to an `access_token` (old `POST https://hh.ru/oauth/token` request should consider as deprecated).
-
-The request body should contain [additional parameters](#required_parameters).
-
-The request body should be sent in standard `application/x-www-form-urlencoded` format with the corresponding `Content-Type` header.
-
-The `authorization_code` has a short lifetime. When it expires, request another `authorization_code`.
-
-## Updating a pair of access and refresh tokens
-The `access_token` also has a lifetime (`expires_in` parameter, in seconds). When it expires, the application should make a request with the `refresh_token` to obtain a new one.
-
-The request should be done in `application/x-www-form-urlencoded` format.
-
-```
-POST https://api.hh.ru/token
-```
-
-(old `POST https://hh.ru/oauth/token` request should consider as deprecated)
-
-The request body should contain [additional parameters](#required_parameters).
-
-You can use the `refresh_token` only once and only after expiration of the `access_token`.
-
-A new pair of access and refresh tokens should be used for further API requests and requests for token prolongation.
-
-## Authorization request under another user
-
-The following case is possible:
-
-1. Application redirects a user to the site with the authorization request.
-2. The user is already authorized on site and application already has an access granted.
-3. The user will be proposed to continue the work under current account or login to another one.
-
-If you need to replace step 3 by instant redirection with temporary token, you should add the parameter `skip_choose_account=true` to `/oauth/authorize...` request. Then the authorized user gets access immediately.
-
-If you need to show the authorization form every time, you should add the parameter `force_login=true` to `/oauth/authorize...` request. In this case the authorization form appears even if the user is already authorized.
-
-This feature may be useful for applications that provide services for applicants only. If an employer user tries to log in, the application may propose them to get access under another user.
-
-Also, after the authorization the application can show a message:
-
-```
-You logged in as %FirstName_LastName%. Is it not you?
-```
-and propose a link with `force_login=true` for authorization under another login.
-
-## Authorization under different working account
-
-To obtain information about getting a list of manager working accounts and working under different working accounts, see the [manager working account](#tag/Employer-managers/operation/get-manager-accounts) section.
-
-
-<!-- ReDoc-Inject: <security-definitions> -->
-`,
-    capabilities: {
-        tools: {},
-        logging: {},
-    },
-});
-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(' ') }),
-};
-const apiClient = axios.create({
-    baseURL: 'https://api.hh.ru',
-    headers: {
-        Accept: 'application/json',
-    },
-    timeout: 30000,
-});
-apiClient.interceptors.request.use((config) => {
-    if (env.HH_API_TOKEN) {
-        config.headers['Authorization'] = env.HH_API_TOKEN;
-    }
-    return config;
-}, (error) => {
-    return Promise.reject(error);
-});
-function handleResult(data) {
-    return {
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify(data, null, 2),
-            },
-        ],
-    };
-}
-function handleError(error) {
-    console.error(error);
-    logger.error('Error occurred:', JSON.stringify(error));
-    if (axios.isAxiosError(error)) {
-        const message = error.response?.data?.message || error.message;
-        return {
-            isError: true,
-            content: [{ type: 'text', text: `API Error: ${message}` }],
-        };
-    }
-    return {
-        isError: true,
-        content: [{ type: 'text', text: `Error: ${error}` }],
-    };
-}
-mcpServer.tool('confirm-phone-in-resume', `Verify phone with a code`, {}, async (args) => {
-    try {
-        const response = await apiClient.post('/resume_phone_confirm', args);
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('get-manager-settings', `Manager preferences`, {
-    employer_id: z.string(),
-    manager_id: z.string(),
-}, async (args) => {
-    try {
-        const { employer_id, manager_id, ...queryParams } = args;
-        const url = `/employers/${employer_id}/managers/${manager_id}/settings`;
-        const response = await apiClient.get(url, {
-            params: queryParams,
-        });
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('get-employer-manager-limits', `Daily limit of resume views for current manager`, {
-    employer_id: z.string(),
-    manager_id: z.string(),
-}, async (args) => {
-    try {
-        const { employer_id, manager_id, ...queryParams } = args;
-        const url = `/employers/${employer_id}/managers/${manager_id}/limits/resume`;
-        const response = await apiClient.get(url, {
-            params: queryParams,
-        });
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('get-employer-addresses', `Directory of employer's addresses`, {
-    employer_id: z.string(),
-    changed_after: z.string().optional(),
-    manager_id: z.string().optional(),
-    with_manager: z.string().optional(),
-    per_page: z.string().optional(),
-    page: z.string().optional(),
-}, async (args) => {
-    try {
-        const { employer_id, ...queryParams } = args;
-        const url = `/employers/${employer_id}/addresses`;
-        const response = await apiClient.get(url, {
-            params: queryParams,
-        });
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('get-employer-managers', `Directory of employer's managers`, {
-    employer_id: z.string(),
-    page: z.string().optional(),
-    per_page: z.string().optional(),
-    search_text: z.string().optional(),
-}, async (args) => {
-    try {
-        const { employer_id, ...queryParams } = args;
-        const url = `/employers/${employer_id}/managers`;
-        const response = await apiClient.get(url, {
-            params: queryParams,
-        });
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('add-employer-manager', `Adding a manager`, {
-    employer_id: z.string(),
-}, async (args) => {
-    try {
-        const { employer_id, ...requestData } = args;
-        const url = `/employers/${employer_id}/managers`;
-        const response = await apiClient.post(url, requestData);
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('get-employer-manager-types', `Directory of manager types and privileges`, {
-    employer_id: z.string(),
-}, async (args) => {
-    try {
-        const { employer_id, ...queryParams } = args;
-        const url = `/employers/${employer_id}/manager_types`;
-        const response = await apiClient.get(url, {
-            params: queryParams,
-        });
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('get-manager-accounts', `Manager's work accounts`, {}, async (args) => {
-    try {
-        const response = await apiClient.get('/manager_accounts/mine', {
-            params: args,
-        });
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('get-applicant-phone-info', `Get information about the applicant's phone number`, {
-    phone: z.string(),
-}, async (args) => {
-    try {
-        const response = await apiClient.get('/resume_should_send_sms', {
-            params: args,
-        });
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-mcpServer.tool('get-address', `Get address by ID`, {
-    employer_id: z.string(),
-    address_id: z.string(),
-    with_manager: z.string().optional(),
-}, async (args) => {
-    try {
-        const { employer_id, address_id, ...queryParams } = args;
-        const url = `/employers/${employer_id}/addresses/${address_id}`;
-        const response = await apiClient.get(url, {
-            params: queryParams,
-        });
-        return handleResult(response.data);
-    }
-    catch (error) {
-        return handleError(error);
-    }
-});
-async function main() {
-    const transport = new StdioServerTransport();
-    await mcpServer.server.connect(transport);
-    logger.log('HeadHunter API MCP Server started');
-}
-main().catch((error) => {
-    console.error('Server error:', error);
-    process.exit(1);
-});