Stepstone Job Search MCP Server

# Stepstone Job Search MCP Server [](https://smithery.ai/server/@kdkiss/mcp-stepstone) An [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/specification) server that lets MCP-compatible clients search the German job portal [Stepstone.de](https://www.stepstone.de). The service exposes a pair of tools for running multi-term job searches and fetching rich job details so assistants such as Claude Desktop or Smithery can surface up-to-date vacancies. --- ## Table of Contents 1. [Key Features](#key-features) 2. [Quick Start](#quick-start) 3. [Configuration](#configuration) 4. [Usage](#usage) 5. [Architecture Overview](#architecture-overview) 6. [Local Development](#local-development) 7. [Testing](#testing) 8. [Troubleshooting](#troubleshooting) 9. [Contributing](#contributing) 10. [Support](#support) 11. [Version History](#version-history) 12. [License](#license) --- ## Key Features - 🔍 **Multi-term Search** – Concurrently queries Stepstone for every search phrase you supply and deduplicates duplicate postings. - 📍 **Location Targeting** – Supports German postal codes with a configurable radius (1–100 km) for regional searches. - 🧠 **Session-aware Follow-ups** – Saves results for one hour so you can request full job details later via `get_job_details`. - 🛡️ **Robust Validation** – Defensive parameter validation, logging, and graceful error messages for malformed requests. - 🐳 **Container & CLI Friendly** – Works as a plain Python process or inside Docker; integrates cleanly with Smithery and Claude Desktop. > ℹ️ **Note:** A Redis cache and other scaling features are mentioned as future enhancements. They are not enabled in the current release. --- ## Quick Start ### Prerequisites - Python 3.8+ - `pip` - Internet access to reach Stepstone.de when running real searches ### Installation Options <details> <summary><strong>Option 1 · Install with Smithery (Recommended)</strong></summary> ```bash npx -y @smithery/cli install @kdkiss/mcp-stepstone --client claude ``` </details> <details> <summary><strong>Option 2 · Manual Setup</strong></summary> ```bash # Clone the repository git clone https://github.com/kdkiss/mcp-stepstone.git cd mcp-stepstone # Install runtime dependencies pip install -r requirements.txt # (Optional) make the server script executable on Unix-like systems chmod +x stepstone_server.py ``` </details> <details> <summary><strong>Option 3 · Docker</strong></summary> ```bash # Build the image docker build -t mcp-stepstone . # Run the container docker run -it --rm mcp-stepstone ``` </details> --- ## Configuration ### MCP Client Configuration #### Smithery `mcp.json` ```json { "mcpServers": { "stepstone-job-search": { "command": "python", "args": ["/path/to/stepstone_server.py"], "description": "Search for job listings on Stepstone.de", "env": { "LOG_LEVEL": "INFO", "REQUEST_TIMEOUT": "10" } } } } ``` #### Claude Desktop - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%/Claude/claude_desktop_config.json` ```json { "mcpServers": { "stepstone-job-search": { "command": "python", "args": ["/absolute/path/to/stepstone_server.py"], "env": { "LOG_LEVEL": "DEBUG", "USER_AGENT": "MCP-Stepstone-Bot/1.0" } } } } ``` ### Environment Variables | Variable | Default | Description | | --- | --- | --- | | `LOG_LEVEL` | `INFO` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`). | | `REQUEST_TIMEOUT` | `10` | Timeout (seconds) for outbound Stepstone HTTP requests and the upper bound for long-running tool calls (the server stops waiting shortly before this limit to avoid client timeouts). | | `USER_AGENT` | Browser-like UA string | Custom User-Agent presented to Stepstone.de. | | `MAX_RETRIES` | `3` | Retry attempts for failed HTTP calls. | | `CACHE_TTL` | `300` | Placeholder for future in-memory caching feature. | --- ## Usage ### Available Tools #### `search_jobs` Runs one or more keyword searches against Stepstone. **Parameters** - `search_terms` *(array of strings, optional)* – Search phrases to query. Defaults to `["fraud", "betrug", "compliance"]`. - `zip_code` *(string, optional)* – German 5-digit postal code. Defaults to `"40210"` (Düsseldorf). - `radius` *(integer, optional)* – Radius in kilometres around the postal code. Defaults to `5`; must be between 1 and 100. #### `get_job_details` Fetches one stored job and enriches it with full description and metadata. **Parameters** - `job_index` *(integer, optional)* – 1-based index into the most recent session’s results. - `job_query` *(string, optional)* – Fuzzy match against stored jobs. Alias `query` is also accepted. - `session_id` *(string, optional)* – Explicit session identifier (auto-selects the most recent active session when omitted). > ⚠️ Provide either `job_index` or `job_query`. Supplying both prioritises `job_index`. ### Example Invocations ```jsonc // Basic search { "tool": "search_jobs", "parameters": { "search_terms": ["software engineer", "developer"] } } // Location constrained search { "tool": "search_jobs", "parameters": { "search_terms": ["marketing manager", "digital marketing"], "zip_code": "10115", "radius": 15 } } // Fetch job details by index { "tool": "get_job_details", "parameters": { "job_index": 1 } } // Fetch job details by query string { "tool": "get_job_details", "parameters": { "job_query": "AML Specialist", "session_id": "550e8400-e29b-41d4-a716-446655440000" } } ``` ### Sample Output ``` Job Search Summary: Search Terms: fraud analyst, compliance officer Location: 60329 (±25km) Total Jobs Found: 23 Session ID: 550e8400-e29b-41d4-a716-446655440000 --- Results for 'fraud analyst' --- 1. Senior Fraud Analyst - Digital Banking Company: Deutsche Bank AG Description: Join our fraud prevention team to analyze transaction patterns... Link: https://www.stepstone.de/stellenangebote--Senior-Fraud-Analyst-Frankfurt-Deutsche-Bank-AG--1234567 ``` ``` 📋 Job Details: Senior Fraud Analyst - Digital Banking 🏢 Company: Deutsche Bank AG 📍 Location: Frankfurt am Main 💰 Salary: €65,000 - €85,000 per year ⏰ Employment Type: Full-time, Permanent 📝 Description: Join our fraud prevention team to analyze transaction patterns and develop detection algorithms... ✅ Requirements: • Bachelor's degree in Computer Science, Finance, or related field • 3+ years experience in fraud detection or financial crime prevention • Strong analytical skills with SQL, Python, or R • Knowledge of AML regulations and compliance frameworks ``` --- ## Architecture Overview ``` ┌────────────────────┐ ┌─────────────────────┐ ┌───────────────────┐ │ MCP Client │ ──▶ │ MCP Stepstone │ ──▶ │ Stepstone.de │ │ (Claude/Smithery) │ │ Server │ │ Job Portal │ └────────────────────┘ └─────────────────────┘ └───────────────────┘ │ ┌─────────────────────┐ │ Job Scraper │ │ - URL Builder │ │ - HTML Parser │ │ - Data Cleaner │ └─────────────────────┘ ``` 1. **Request** – MCP client sends tool invocation. 2. **Validation** – Inputs validated (terms, postal code, radius). 3. **Search** – URLs constructed and fetched concurrently. 4. **Processing** – HTML parsed and normalised job entries produced. 5. **Sessioning** – Results stored in memory for one hour for follow-up queries. 6. **Response** – Textual summary returned to the MCP client. 7. **Details** – `get_job_details` fetches the original job page and extracts specifics. Key modules: - `StepstoneJobScraper` – Builds search URLs, fetches and parses job listings. - `JobDetailParser` – Scrapes detailed job pages for salary, requirements, etc. - `SessionManager` – Stores search sessions, supports lookup by index or fuzzy match. - `stepstone_server.py` – Registers MCP tools/resources and handles tool invocations. --- ## Local Development ```bash # Clone repository git clone https://github.com/kdkiss/mcp-stepstone.git cd mcp-stepstone # Create & activate a virtual environment python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # Install dependencies pip install -r requirements.txt # Install dev tooling pip install pytest pytest-asyncio black flake8 # Run formatter and linter black stepstone_server.py flake8 stepstone_server.py ``` ### Debug Fixtures A lightweight HTTP server is included to serve bundled HTML fixtures. Start it when adjusting selectors or parsers: ```bash python debug_server.py ``` Visit `http://127.0.0.1:5000` to inspect the mocked Stepstone pages used in tests. ### HTTP Transport Adapter Some hosted MCP environments (such as Smithery) require an HTTP endpoint with liberal CORS headers instead of the default STDIO transport. The project ships a small Starlette-based adapter that exposes the existing server over the streamable HTTP protocol: ```bash python stepstone_http_server.py ``` The server listens on `0.0.0.0:8000` by default and responds to preflight requests with `Access-Control-Allow-Origin: *`. Adjust the `HOST` and `PORT` environment variables when deploying to platforms that mandate specific interfaces or ports. --- ## Testing The test suite uses mocked network responses to avoid contacting Stepstone.de. ```bash pip install -r requirements.txt pytest pytest ``` To validate specific tool flows interactively, you can run `stepstone_server.py` directly or call `handle_call_tool` from a Python shell. --- ## Troubleshooting ### Server Won’t Start ```bash python --version # Expect 3.8+ pip list | grep -E "(requests|beautifulsoup4|mcp)" ls -la stepstone_server.py # Confirm execute permissions when running directly ``` ### No Jobs Returned - Verify the postal code is a valid five-digit German PLZ. - Increase `radius` or broaden `search_terms`. - Confirm internet connectivity. - Stepstone layout changes may require updating selectors—use the debug server to compare fixtures. ### Import Errors ```bash pip install -r requirements.txt pip install --upgrade pip ``` ### Enable Verbose Logging ```bash export LOG_LEVEL=DEBUG python stepstone_server.py ``` Logs are emitted to stdout; integrate with your own logging infrastructure if desired. ### Smithery Scanner Cannot Initialize Connection If the Smithery CLI reports repeated `HTTP error: This operation was aborted` or `McpError: MCP error -32001: Request timed out` messages while scanning the server, the MCP process started successfully but the JSON-RPC handshake failed. Typical causes and remedies: 1. **CORS headers missing** – Ensure your HTTP transport returns permissive CORS headers: ```javascript res.setHeader("Access-Control-Allow-Origin", "*"); res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS"); res.setHeader("Access-Control-Allow-Headers", "Content-Type"); ``` 2. **Slow initialization** – Increase client timeouts (example Smithery `mcp.json` snippet): ```json { "mcpServers": { "stepstone-job-search": { "type": "streamable-http", "url": "http://localhost:3000/mcp", "initTimeout": 30000, "timeout": 60000 } } } ``` 3. **Endpoint mismatch** – Confirm the server is reachable where the client expects it (for example, `curl -v http://localhost:3000/mcp`). If Smithery logs show `HTTP POST → undefined`, double-check the configured URL or transport binding. When debugging, start the server manually via `npx -y @smithery/cli serve` to observe whether it exits early or logs binding issues. --- ## Contributing 1. Fork the repository and create a feature branch: `git checkout -b feature/my-change`. 2. Implement your changes and add tests. 3. Run `pytest` and lint/format the code (`black`, `flake8`). 4. Open a pull request describing the change. Coding guidelines: - Follow PEP 8 and include type hints where practical. - Document public functions with docstrings. - Handle network and parsing errors defensively. --- ## Support - 📖 Consult this README for configuration and usage tips. - 🧪 Use the debug server to inspect fixture HTML when selectors break. - 🐛 File bugs or feature requests via GitHub Issues. - 💬 Join the project’s Discord community (link forthcoming). --- ## Version History ### v1.2.0 (Current) - Added `get_job_details` tool for follow-up queries. - Introduced session management with one-hour TTL. - Enhanced detail parsing for salary, requirements, and benefits. - Summaries now include session IDs for easy follow-up. ### v1.1.0 - Expanded documentation and usage examples. - Added Docker support and environment variable configuration. - Improved error handling and validation. ### v1.0.0 - Initial release with multi-term job search and MCP compliance. --- ## License Distributed under the [MIT License](LICENSE). --- **Made with ❤️ for the German job market.**