Metadata-Version: 2.4
Name: jobdatapool-mcp
Version: 0.1.0
Summary: MCP server for JobDataPool job search, source provenance, and analyst workflows
Author: JobDataPool
License: MIT
Project-URL: Homepage, https://jobdatapool.com/mcp/
Project-URL: Documentation, https://jobdatapool.com/mcp/
Project-URL: API, https://jobdatapool.com/docs/api/
Keywords: mcp,model-context-protocol,jobs,jobdatapool,job-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.0
Requires-Dist: requests>=2.32
Dynamic: license-file

# jobdatapool-mcp

A local Model Context Protocol server for JobDataPool job listings, source provenance, dataset QA, company briefs, and market scans.

This Python package is a parity-oriented port of the Node JobDataPool MCP surface. It exposes the same six core tools, three resources, and three guided prompts described on the JobDataPool MCP page.

## Requirements

- Python 3.10+
- An MCP-compatible client that can launch a local stdio server, such as Claude Desktop, Claude Code, Cursor, or Windsurf

## Install

```bash
pip install jobdatapool-mcp
```

## Run locally

```bash
jobdatapool-mcp
```

The server uses `https://jobdatapool.com` by default.

For local site testing, point it at your local JobDataPool build:

```bash
JOBDATAPOOL_BASE_URL=http://localhost:8888 jobdatapool-mcp
```

The dataset snapshot is cached for 10 minutes by default. Override that with:

```bash
JOBDATAPOOL_CACHE_TTL_SECONDS=60 jobdatapool-mcp
```

## MCP client config

### Claude Desktop / Claude Code / Cursor / Windsurf

After installing from PyPI, use the package command directly:

```json
{
  "mcpServers": {
    "jobdatapool": {
      "command": "jobdatapool-mcp",
      "env": {
        "JOBDATAPOOL_BASE_URL": "https://jobdatapool.com"
      }
    }
  }
}
```

For a local checkout before publishing, run through Python instead:

```json
{
  "mcpServers": {
    "jobdatapool": {
      "command": "python",
      "args": ["-m", "jobdatapool_mcp.server"],
      "cwd": "/absolute/path/to/jobdatapool-mcp",
      "env": {
        "JOBDATAPOOL_BASE_URL": "https://jobdatapool.com"
      }
    }
  }
}
```

## Tools

### `search_jobs`

Search the current JobDataPool snapshot by keyword and filters.

Useful arguments include:

- `query`
- `limit`
- `location`
- `country`
- `company`
- `industry`
- `skill`
- `seniority`
- `employment_type`
- `remote`
- `posted_within_days`
- `salary`
- `sort`

Example prompts:

```text
Find remote senior Python security jobs in the US.
```

```text
Search JobDataPool for data engineering roles in healthcare, limit to 15, and include listing ids.
```

```text
Find remote product manager jobs with salary signals and summarize the strongest matches.
```

### `get_job`

Return one listing by JobDataPool id. Raw source and application URLs are masked; results include the JobDataPool redirect handoff URL when an id is available.

```text
Tell me more about listing id 12345.
```

### `get_company`

Summarize a company footprint from matching listings in the current snapshot.

```text
Brief me on Huntress in the current JobDataPool snapshot.
```

The response includes matching listing count, locations, seniority, industries, skills, examples, and snapshot caveats.

### `get_filter_options`

Show high-count facet values for common filters.

```text
What skills, countries, locations, industries, and companies are common in this dataset?
```

### `find_similar_jobs`

Find listings similar to a known JobDataPool listing id using title, skill, company, industry, and summary overlap.

```text
Find jobs similar to listing id 12345.
```

### `get_sources`

Return the JobDataPool source catalog, contract pointers, and local MCP cache status.

```text
What snapshot is this MCP reading, and how many rows are cached?
```

## Resources

- `jobdatapool://source-catalog` — live `/v1/sources` catalog plus cache status
- `jobdatapool://analyst-context` — dataset scope, cache behavior, provenance guidance, caveats, and URL masking policy
- `jobdatapool://contracts` — OpenAPI, schema, dataset, v1 endpoint, tool, resource, and prompt pointers

## Prompts

- `jobdatapool_market_scan(topic, location, remote)` — role, skill, industry, or hiring-theme scan
- `jobdatapool_company_brief(company)` — company footprint summary workflow
- `jobdatapool_dataset_qa()` — source/catalog health and facet coverage workflow

## URL masking behavior

The server does not return raw source or application URLs. It removes common origin URL fields and replaces embedded external URLs in scraped text with `[masked external URL]`. When a JobDataPool id is present, outputs include:

```text
https://jobdatapool.com/jobrd?id=<id>
```

## Publishing

This repository is wired for PyPI Trusted Publishing through GitHub Actions. Configure a PyPI Trusted Publisher for the repository and the `release` environment, then push a tag:

```bash
git tag v0.1.0
git push origin v0.1.0
```
