@gera-services/mcp-gera-jobs 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# @gera-services/mcp-gera-jobs
+
+**GeraJobs MCP server** — give any AI agent (Claude, ChatGPT with tools, Cursor,
+or any [Model Context Protocol](https://modelcontextprotocol.io) client) direct
+access to the GeraJobs global jobs dataset: 30 job categories, 20 country job
+markets, and salary benchmarks aggregated from **1,002 real crawled job
+listings**.
+
+Everything is answered locally from on-disk data — **no backend, no network, no
+auth, no API key**. It is the same data the [GeraJobs](https://gerajobs.com)
+product renders. A Gera Systems product.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_job_categories` | Free-text search over the 30 categories (name, description, skills, keywords). Returns avg USD salary range, top skills, remote %, trending flag. |
+| `get_salary_benchmark` | Real salary benchmarks for a role per country/currency — sample size + median / p25 / p75 / low / high annual pay, plus sample listings. Aggregated from crawled listings. |
+| `list_job_categories` | Compact index of all 30 categories (id, name, salary range, trending) — the canonical ids for the other tools. |
+| `get_job_market` | Country hiring profile: avg monthly wage, top industries/employers, job + AI growth, remote adoption, summary. Lookup by ISO code, country name, or city. |
+| `get_category_details` | Full profile + curated FAQ for one category (salaries, skills, how to find roles). |
+
+All numbers trace to the underlying GeraJobs datasets; salary figures derive from
+real crawled listings (snapshot date and total listing count are returned in
+every salary response). Orientation only — not a contractual salary guarantee.
+
+## Install & run
+
+```bash
+# From the npm registry (once published):
+npx -y @gera-services/mcp-gera-jobs
+
+# Or from this repo:
+cd packages/mcp-gera-jobs
+node scripts/build-dataset.mjs   # snapshot the real datasets (already committed)
+npm run build                    # tsc --noCheck -> dist/
+npm run smoke                    # prove tools/list + tools/call over stdio
+```
+
+## Claude Desktop
+
+Add this to your `claude_desktop_config.json`
+(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "gera-jobs": {
+      "command": "npx",
+      "args": ["-y", "@gera-services/mcp-gera-jobs"]
+    }
+  }
+}
+```
+
+Then restart Claude Desktop. Ask things like:
+
+- *"What's the median salary for a data scientist in the US?"*
+- *"Show me trending remote job categories and their top skills."*
+- *"What's the hiring market like in Armenia right now?"*
+
+## Cursor / other stdio MCP clients
+
+Point the client at the `mcp-gera-jobs` stdio command (`npx -y
+@gera-services/mcp-gera-jobs`), or to `node bin/cli.js` when running from a local
+checkout.
+
+## Data sources (real, in-repo)
+
+- **Categories:** `apps/gerajobs-web/src/data/job-categories.ts` (30 categories)
+- **Markets:** `apps/gerajobs-web/src/data/job-markets.ts` (20 countries)
+- **Salary benchmarks:** `apps/gerajobs-web/src/data/salary-cluster.generated.ts`
+  — aggregated from 1,002 real crawled GeraJobs listings.
+
+Regenerate the bundled snapshot with `node scripts/build-dataset.mjs`.
+
+---
+
+A [GeraJobs](https://gerajobs.com) product, by Gera Systems Ltd. MIT licensed.

package/bin/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the GeraJobs MCP server.
+ * Starts the server on stdio. Intended to be launched by an MCP client
+ * (Claude Desktop, ChatGPT-with-tools, Cursor, etc.) — not run interactively.
+ */
+import { main } from '../dist/server.js';
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/dist/dataset.generated.d.ts

@@ -0,0 +1,65 @@
+export interface JobCategory {
+    id: string;
+    name: string;
+    icon: string;
+    description: string;
+    avgSalaryUSD: {
+        min: number;
+        max: number;
+    };
+    topSkills: string[];
+    trending: boolean;
+    remotePercentage: number;
+    keywords: string[];
+    faqs: {
+        q: string;
+        a: string;
+    }[];
+}
+export interface JobMarket {
+    countryCode: string;
+    country: string;
+    city: string;
+    currency: string;
+    avgMonthlyWage: number;
+    topIndustries: string[];
+    topEmployers: string[];
+    jobGrowthRate: string;
+    remoteWorkAdoption: string;
+    aiJobsGrowth: string;
+    description: string;
+    hiring: string;
+    keywords: string[];
+    slug: string;
+}
+export interface SalaryMarketStat {
+    currency: string;
+    country: string;
+    countryCode: string;
+    sampleSize: number;
+    medianAnnual: number;
+    p25Annual: number;
+    p75Annual: number;
+    lowAnnual: number;
+    highAnnual: number;
+}
+export interface SalarySampleListing {
+    id: string;
+    title: string;
+    company: string | null;
+    currency: string;
+    salary: string;
+    url: string | null;
+}
+export interface SalaryRole {
+    slug: string;
+    name: string;
+    totalSampleSize: number;
+    markets: SalaryMarketStat[];
+    sampleListings: SalarySampleListing[];
+}
+export declare const SALARY_TOTAL_LISTINGS: 1002;
+export declare const SALARY_GENERATED_AT: "2026-06-12";
+export declare const JOB_CATEGORIES: JobCategory[];
+export declare const JOB_MARKETS: JobMarket[];
+export declare const SALARY_ROLES: SalaryRole[];