jobdatapool-mcp 0.1.0__tar.gz

jobdatapool_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JobDataPool
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jobdatapool_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+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
+```

jobdatapool_mcp-0.1.0/README.md

@@ -0,0 +1,179 @@
+# 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
+```

jobdatapool_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "jobdatapool-mcp"
+version = "0.1.0"
+description = "MCP server for JobDataPool job search, source provenance, and analyst workflows"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "JobDataPool" }]
+keywords = ["mcp", "model-context-protocol", "jobs", "jobdatapool", "job-search"]
+dependencies = [
+    "mcp>=1.0,<2",
+    "requests>=2.32"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://jobdatapool.com/mcp/"
+Documentation = "https://jobdatapool.com/mcp/"
+API = "https://jobdatapool.com/docs/api/"
+
+[project.scripts]
+jobdatapool-mcp = "jobdatapool_mcp.server:main"
+
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

jobdatapool_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jobdatapool_mcp-0.1.0/src/jobdatapool_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""JobDataPool MCP server."""
+
+__version__ = "0.1.0"

jobdatapool_mcp-0.1.0/src/jobdatapool_mcp/cache.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from .config import cache_ttl_seconds
+from .http import get_json
+from .sources import candidate_dataset_urls, get_source_catalog
+
+
+@dataclass
+class DatasetCache:
+    rows: list[dict[str, Any]] = field(default_factory=list)
+    source_catalog: Any | None = None
+    dataset_url: str | None = None
+    loaded_at: float = 0.0
+    error: str | None = None
+
+    def fresh(self) -> bool:
+        ttl = cache_ttl_seconds()
+        return bool(self.rows) and ttl > 0 and (time.time() - self.loaded_at) < ttl
+
+    def status(self) -> dict[str, Any]:
+        return {
+            "loaded_rows": len(self.rows),
+            "dataset_url": self.dataset_url,
+            "loaded_at": self.loaded_at or None,
+            "ttl_seconds": cache_ttl_seconds(),
+            "fresh": self.fresh(),
+            "last_error": self.error,
+        }
+
+
+_CACHE = DatasetCache()
+
+
+def _extract_rows(payload: Any) -> list[dict[str, Any]]:
+    if isinstance(payload, list):
+        rows = payload
+    elif isinstance(payload, dict):
+        rows = payload.get("jobs") or payload.get("results") or payload.get("data") or payload.get("rows") or payload.get("listings") or []
+    else:
+        rows = []
+    return [row for row in rows if isinstance(row, dict)]
+
+
+def load_dataset(force: bool = False) -> DatasetCache:
+    if _CACHE.fresh() and not force:
+        return _CACHE
+    try:
+        _CACHE.source_catalog = get_source_catalog()
+    except Exception as exc:  # noqa: BLE001
+        _CACHE.error = f"source catalog unavailable: {exc}"
+    last_error = None
+    for url in candidate_dataset_urls(_CACHE.source_catalog):
+        try:
+            payload = get_json(url, timeout=30)
+            rows = _extract_rows(payload)
+            if rows:
+                _CACHE.rows = rows
+                _CACHE.dataset_url = url
+                _CACHE.loaded_at = time.time()
+                _CACHE.error = None
+                return _CACHE
+        except Exception as exc:  # noqa: BLE001
+            last_error = f"{url}: {exc}"
+    _CACHE.error = last_error or _CACHE.error or "No dataset rows loaded."
+    return _CACHE

jobdatapool_mcp-0.1.0/src/jobdatapool_mcp/company.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+from .models import as_list, get_first, text_value
+from .masking import public_job
+
+
+def company_brief(rows: list[dict[str, Any]], company: str, limit_examples: int = 5) -> dict[str, Any]:
+    needle = company.lower()
+    matches = [row for row in rows if needle in text_value(row.get("company")).lower()]
+    locations: Counter[str] = Counter()
+    seniority: Counter[str] = Counter()
+    industries: Counter[str] = Counter()
+    skills: Counter[str] = Counter()
+    for row in matches:
+        for value, counter in (
+            (row.get("location"), locations),
+            (row.get("seniority"), seniority),
+            (row.get("industry") or row.get("industries"), industries),
+            (row.get("skills"), skills),
+        ):
+            for item in as_list(value):
+                text = text_value(item)
+                if text:
+                    counter[text] += 1
+    examples = []
+    for row in matches[: max(1, min(limit_examples, 20))]:
+        examples.append(public_job({
+            "id": get_first(row, "id", "job_id", "listing_id", "jobdatapool_id"),
+            "title": row.get("title"),
+            "company": row.get("company"),
+            "location": row.get("location"),
+        }))
+    return {
+        "company_query": company,
+        "matching_listings": len(matches),
+        "locations": dict(locations.most_common(15)),
+        "seniority": dict(seniority.most_common(15)),
+        "industries": dict(industries.most_common(15)),
+        "skills": dict(skills.most_common(20)),
+        "examples": examples,
+        "caveat": "This brief is derived from the current JobDataPool snapshot loaded by the MCP cache.",
+    }

jobdatapool_mcp-0.1.0/src/jobdatapool_mcp/config.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import os
+
+DEFAULT_BASE_URL = "https://jobdatapool.com"
+DEFAULT_CACHE_TTL_SECONDS = 600
+USER_AGENT = "jobdatapool-mcp/0.1.0 (+https://jobdatapool.com/mcp/)"
+
+
+def base_url() -> str:
+    return os.getenv("JOBDATAPOOL_BASE_URL", DEFAULT_BASE_URL).rstrip("/")
+
+
+def cache_ttl_seconds() -> int:
+    raw = os.getenv("JOBDATAPOOL_CACHE_TTL_SECONDS", str(DEFAULT_CACHE_TTL_SECONDS))
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return DEFAULT_CACHE_TTL_SECONDS

jobdatapool_mcp-0.1.0/src/jobdatapool_mcp/http.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+from .config import USER_AGENT
+
+
+def get_json(url: str, *, params: dict[str, Any] | None = None, timeout: int = 20) -> Any:
+    response = requests.get(
+        url,
+        params=params,
+        timeout=timeout,
+        headers={"Accept": "application/json", "User-Agent": USER_AGENT},
+    )
+    response.raise_for_status()
+    return response.json()

jobdatapool_mcp-0.1.0/src/jobdatapool_mcp/masking.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .config import base_url
+
+_URL_RE = re.compile(r"https?://[^\s)\]}>\"']+", re.IGNORECASE)
+
+RAW_URL_KEYS = {
+    "url",
+    "source_url",
+    "application_url",
+    "apply_url",
+    "job_url",
+    "external_url",
+    "original_url",
+    "canonical_url",
+}
+
+
+def job_id(job: dict[str, Any]) -> str | None:
+    for key in ("id", "job_id", "listing_id", "jobdatapool_id", "uuid"):
+        value = job.get(key)
+        if value is not None and str(value).strip():
+            return str(value).strip()
+    return None
+
+
+def redirect_url(job_or_id: dict[str, Any] | str | int | None) -> str | None:
+    if isinstance(job_or_id, dict):
+        jid = job_id(job_or_id)
+    elif job_or_id is None:
+        jid = None
+    else:
+        jid = str(job_or_id).strip()
+    return f"{base_url()}/jobrd?id={jid}" if jid else None
+
+
+def sanitize_text(value: Any) -> Any:
+    if not isinstance(value, str):
+        return value
+    return _URL_RE.sub("[masked external URL]", value)
+
+
+def public_job(job: dict[str, Any]) -> dict[str, Any]:
+    """Return a listing payload with raw origin/application URLs removed."""
+    output: dict[str, Any] = {}
+    for key, value in job.items():
+        lower = key.lower()
+        if lower in RAW_URL_KEYS or lower.endswith("_url") or lower.endswith("Url"):
+            continue
+        if isinstance(value, str):
+            output[key] = sanitize_text(value)
+        elif isinstance(value, list):
+            output[key] = [sanitize_text(item) for item in value]
+        elif isinstance(value, dict):
+            output[key] = {k: sanitize_text(v) for k, v in value.items() if not str(k).lower().endswith("url")}
+        else:
+            output[key] = value
+    jid = job_id(job)
+    if jid:
+        output.setdefault("id", jid)
+        output["jobdatapool_url"] = redirect_url(jid)
+    return output