Content
# Tool List
[The MCP service provides job search, employer recruitment profile, talent demand analysis, job salary, and recruitment trend analysis capabilities, helping users conduct talent market research, employer analysis, and recruitment decisions.](https://www.handaas.com/)
## Main Features
- 🔍 Enterprise Recruitment Job Search
- 🏢 Employer Recruitment Profile Analysis
- 👥 Enterprise Talent Demand Analysis
- 💰 Recruitment Job Salary Query
- 📈 Enterprise Recruitment Trend Overview
## Service Design Description
- The service provides 5 tools based on actual business scenarios, not flattening tools based on the number of upstream APIs.
- Recruitment details and recruitment statistics are reused by different scenario tools with different Product IDs.
- `recruitment_demand_analysis` selects details or statistics through `view`, and only accesses one Product ID at a time.
- The business outer layer of paginated results only contains `total` and `resultList`, with a maximum `pageSize` of 50.
- Long lists in profiles and statistics are limited by `listLimit`, defaulting to 50 and maximum 200.
- `recruitment_trend` only returns recruitment quantity, recent three-month statistics, update frequency, and average salary, avoiding repeated return of profile long lists.
## Environment Requirements
- Python 3.10+
- Dependencies: python-dotenv, requests, mcp
## Local Quick Start
### 1. Enter the project directory
```bash
cd recruitment-mcp-server
```
### 2. Create a virtual environment and install dependencies
```bash
python3 -m venv mcp_env
source mcp_env/bin/activate
pip install -r requirements.txt
```
### 3. Configure environment variables
Copy the environment variable template:
```bash
cp .env.example .env
```
Edit the `.env` file:
```env
INTEGRATOR_ID=your_integrator_id
SECRET_ID=your_secret_id
SECRET_KEY=your_secret_key
HANDAAS_REQUEST_TIMEOUT=30
```
`HANDAAS_REQUEST_TIMEOUT` is an optional configuration, in seconds, with a default value of 30.
### 4. Start the Streamable HTTP service
```bash
python server/mcp_server.py streamable-http
```
The service default address is `http://localhost:8000/mcp`.
You can also use the startup script:
```bash
./start_mcp_server.sh streamable-http
```
Supports `stdio`, `sse`, and `streamable-http` three startup methods.
### 5. Cursor / Cherry Studio MCP configuration
```json
{
"mcpServers": {
"recruitment-mcp-server": {
"type": "streamableHttp",
"url": "http://127.0.0.1:8000/mcp"
}
}
}
```
## STDIO version installation and deployment
Replace `{workdir}` with the absolute path of `recruitment-mcp-server`:
```json
{
"mcpServers": {
"recruitment-mcp-server": {
"command": "{workdir}/mcp_env/bin/python",
"args": [
"{workdir}/server/mcp_server.py",
"stdio"
]
}
}
}
```
`INTEGRATOR_ID`, `SECRET_ID`, and `SECRET_KEY` need to be logged in to [HandaaS](https://www.handaas.com/) to register and open the connector to obtain. Real credentials should only be saved in the local `.env` or deployment key.
## Available tools and Product ID
| MCP Tool | Function or View | Product ID |
|---|---|---|
| `recruitment_job_search` | Enterprise Recruitment Job Details | `66b338e274bf098447db7f09` |
| `recruitment_employer_profile` | Enterprise Recruitment Profile and Statistics | `66b338e274bf098447db7f1b` |
| `recruitment_demand_analysis` | `view=details` Talent Demand Details | `66b338e274bf098447db7f09` |
| `recruitment_demand_analysis` | `view=statistics` Talent Demand Statistics | `66b338e274bf098447db7f1b` |
| `recruitment_salary` | Job Salary Range Details | `66b338e274bf098447db7f09` |
| `recruitment_trend` | Recruitment Quantity, Recent Three-Month Statistics, Update Frequency, and Average Salary | `66b338e274bf098447db7f1b` |
### 1. recruitment_job_search
**Function**: Query the recruitment job details of a specified enterprise.
**Main Parameters**:
- `matchKeyword` (required): Enterprise name, enterprise ID, registration number, or unified social credit code.
- `keywordType` (optional): Enterprise identification type, supporting `name`, `nameId`, `regNumber`, `socialCreditCode`.
- `pageIndex` (optional): Page number, starting from 1.
- `pageSize` (optional): Number of items per page, default 50, maximum 50.
**Return**: `total` and `resultList`; job details may include job name, city, education, salary, working years, and recruitment channel.
### 2. recruitment_employer_profile
**Function**: Query the recruitment profile of an enterprise, including benefits, recruitment cities, job keywords, and average salary.
**Main Parameters**:
- `matchKeyword` (required): Enterprise name, enterprise ID, registration number, or unified social credit code.
- `keywordType` (optional): Enterprise identification type.
- `listLimit` (optional): Maximum number of profile list fields returned, default 50, maximum 200.
**Return**: Enterprise recruitment statistics and profile; if the list is truncated, `truncatedFields` is returned.
### 3. recruitment_demand_analysis
**Function**: Analyze the talent demand of an enterprise, and choose the job details or enterprise statistics view.
**Main Parameters**:
- `matchKeyword` (required): Enterprise identification.
- `view` (optional): `details` job details; `statistics` enterprise statistics. Default `statistics`.
- `keywordType` (optional): Enterprise identification type.
- `pageIndex`, `pageSize` (optional): Only used in `details` view, `pageSize` maximum 50.
- `listLimit` (optional): Only used in `statistics` view, default 50, maximum 200.
**Return**: Details view returns `total` and `resultList`; statistics view returns enterprise recruitment profile and statistics.
### 4. recruitment_salary
**Function**: Query the salary range of recruitment jobs of an enterprise, used for job and talent market salary comparison.
**Main Parameters**:
- `matchKeyword` (required): Enterprise name, enterprise ID, registration number, or unified social credit code.
- `keywordType` (optional): Enterprise identification type.
- `pageIndex` (optional): Page number, starting from 1.
- `pageSize` (optional): Number of items per page, default 50, maximum 50.
**Return**: `total` and `resultList`; `workingSalary` may include currency, minimum salary, and maximum salary.
### 5. recruitment_trend
**Function**: Query the recruitment trend overview of an enterprise, not returning monthly time series.
**Main Parameters**:
- `matchKeyword` (required): Enterprise name, enterprise ID, registration number, or unified social credit code.
- `keywordType` (optional): Enterprise identification type.
**Return**:
- `recruitingCurrentCount`: Current recruitment number.
- `recruitingLastThreeMonthCount`: Recruitment number in the recent three months.
- `recruitingLastThreeMonthNo`: Number of recruitment jobs in the recent three months.
- `recruitingAvgUpdate`: Average job update frequency.
- `recruitingAvgWorkingSalary`: Average recruitment salary.
## Use Cases
1. **Talent Demand Research**: View the jobs and talent directions currently being recruited by the target enterprise.
2. **Employer Analysis**: Understand the recruitment cities, benefits, job keywords, and recruitment activity of the enterprise.
3. **Salary Comparison**: Compare the salary ranges of different enterprises or jobs.
4. **Recruitment Trend Judgment**: Analyze the current and recent three-month recruitment scale and average update frequency.
5. **Competitive Intelligence**: Judge the business expansion direction of the enterprise from the change of recruitment demand.
## Precautions for Use
1. **Enterprise Full Name**: It is recommended to provide the full name of the enterprise when querying by enterprise name.
2. **Enterprise Identification**: When the enterprise name is not unique, it is recommended to use the enterprise ID or unified social credit code.
3. **Paging Limitation**: `pageIndex` starts from 1, and `pageSize` must be between 1 and 50.
4. **List Limitation**: `listLimit` must be between 1 and 200.
5. **View Selection**: Use `view=details` when needing job records; use `view=statistics` when needing summary profiles.
6. **Trend caliber**: `recruitment_trend` is the current and recent three-month overview, not a monthly time series.
## Example of Use Questions
### recruitment_job_search (Recruitment Job Search)
1. What jobs is Xiaomi Technology Co., Ltd. currently recruiting?
2. Query the recent recruitment jobs of Beijing JD Century Trade Co., Ltd.
### recruitment_employer_profile (Employer Recruitment Profile)
1. Analyze the recruitment cities, benefits, and job profiles of Xiaomi Technology Co., Ltd.
2. What is the average recruitment salary of Zhuhai Gree Electric Co., Ltd.?
### recruitment_demand_analysis (Recruitment Demand Analysis)
1. Summarize the talent demand structure of an enterprise.
2. List the specific job demands of the target enterprise.
### recruitment_salary (Job Salary Query)
1. View the salary range of recruitment jobs of Xiaomi Technology Co., Ltd.
2. What is the salary level of Zhuhai Gree Electric Co., Ltd.?
### recruitment_trend (Recruitment Trend Overview)
1. What is the current recruitment heat and recent three-month trend of Xiaomi Technology Co., Ltd.?
2. Query the recent recruitment number, job number, and average salary of JD.
## Test Verification
```bash
python -m py_compile server/mcp_server.py
python -m unittest discover -s tests -v
```
Unit tests use mock HTTP responses and do not call the real HandaaS recruitment interface.
