Metadata-Version: 2.4
Name: cleanjobdata-mcp
Version: 0.1.0
Summary: CleanJobData MCP Server
Project-URL: Homepage, https://github.com/jhgaylor/cleanjobdata-mcp
Project-URL: Repository, https://github.com/jhgaylor/cleanjobdata-mcp
Project-URL: Bug Tracker, https://github.com/jhgaylor/cleanjobdata-mcp/issues
Author-email: Jake Gaylor <jhgaylor@gmail.com>
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=2.0
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: pyinstaller; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Description-Content-Type: text/markdown

# CleanJobData MCP Server

A Model Context Protocol (MCP) server providing tools to interact with the [CleanJobData](https://cleanjobdata.com) Job API.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Available MCP Interactions

This server exposes the following MCP interactions:

### Tools

*   `search_jobs`: Search for jobs using the CleanJobData API based on various criteria.
    *   *Parameters*: `title`, `sort_by`, `city_id`, `state_id`, `country_id`, `location`, `remote`, `remote_type`, `company_name`, `employer_id`, `salary_min`, `salary_max`, `require_salary`, `experience_level`, `employment_type`, `published_after`, `max_age`, `include_expired`, `include_description`, `limit`, `cursor`, `count`.
*   `get_job`: Retrieve detailed information about a specific job (including its full description) by ID.
    *   *Parameters*: `job_id`.
*   `search_companies`: Search for companies by name (fuzzy), website domain, or company IDs.
    *   *Parameters*: `query`, `website_url`, `employer_id`, `active`, `limit`, `offset`.
*   `get_company`: Retrieve detailed information about a specific company, including enrichment data.
    *   *Parameters*: `company_id`.
*   `suggest_locations`: Autocomplete city/state/country names into the IDs used by `search_jobs` geo filters.
    *   *Parameters*: `query`, `kinds`, `limit`.

### Prompts

*   `create_candidate_profile`: Generates a structured prompt based on candidate details (name, LinkedIn, website, resume text) to help guide job searching.
    *   *Parameters*: `name`, `linkedin_url`, `personal_website`, `resume_text`.

## Client Setup (Examples: Claude Desktop, Cursor)

To use this server with an MCP client like Claude Desktop or Cursor, you need to configure the client to run the server process and provide the CleanJobData API key.

1.  **Ensure `uv` is installed:** `curl -LsSf https://astral.sh/uv/install.sh | sh`
2.  **Obtain a CleanJobData API Key:** Request a key from [CleanJobData](https://cleanjobdata.com). Set it as the `CLEANJOBDATA_API_KEY` environment variable.
3.  **Configure your client:**

    *   **Using `uvx`:**
        *   **Claude Desktop:** Edit your `claude_desktop_config.json`:
            ```json
            {
              "mcpServers": {
                "cleanjobdata": {
                  "command": "uvx",
                  "args": [
                    "cleanjobdata-mcp"
                  ],
                  "env": {
                    "CLEANJOBDATA_API_KEY": ""
                  }
                }
              }
            }
            ```
        *   **Cursor:** Go to Settings > MCP > Add Server:
            *   **Mac/Linux Command:** `uvx cleanjobdata-mcp`
            *   **Windows Command:** `cmd`
            *   **Windows Args:** `/c`, `uvx`, `cleanjobdata-mcp`
            *   Set the `CLEANJOBDATA_API_KEY` environment variable in the appropriate section.

    *   **Running from source (Alternative):**
        1. Clone the repo and note where you clone it to
        2. **Claude Desktop:** Edit your `claude_desktop_config.json`:
        ```json
        {
            "mcpServers": {
                "cleanjobdata": {
                    "command": "uv",
                    "args": [
                        "run",
                        "--directory",
                        "PATH_TO_REPO",
                        "cleanjobdata-mcp"
                    ],
                    "env": {
                        "CLEANJOBDATA_API_KEY": ""
                    }
                }
            }
        }
        ```

## Development

This project uses:
- `uv` for dependency management and virtual environments
- `ruff` for linting and formatting
- `hatch` as the build backend

### Common Tasks

```bash
# Setup virtual env
uv venv

# Install dependencies
uv pip install -e .

# install cli tools
uv tool install ruff

# Run linting
ruff check .

# Format code
ruff format .
```

## Environment Variables

-   `CLEANJOBDATA_API_KEY` (**required**): Your API key for accessing the CleanJobData API, sent as a Bearer token. The server needs this to make authenticated requests for job data.

## Testing

This project uses `pytest` for testing the core tool logic. Tests mock external API calls using `unittest.mock`.

1. Install test dependencies:
```bash
# Ensure you are in your activated virtual environment (.venv)
uv pip install -e '.[test]'
```

2. Run tests:
```bash
pytest
```

## Contributing

Contributions are welcome.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
