# Stepstone Job Search MCP Server

[![smithery badge](https://smithery.ai/badge/@kdkiss/mcp-stepstone)](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.**