@gera-services/mcp-gera-jobs 1.0.0

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GeraJobs MCP Server (stdio)
+ *
+ * Exposes the Gera global jobs dataset to AI agents over the Model Context
+ * Protocol. Everything is answered locally from the same on-disk data the
+ * GeraJobs product renders — 30 job categories, 20 country job markets, and
+ * salary benchmarks aggregated from 1,002 real crawled listings — so an agent
+ * (Claude, ChatGPT with tools, any MCP client) can search categories, read
+ * salary benchmarks, and look up country markets entirely offline, no auth.
+ *
+ * Product: GeraJobs — https://gerajobs.com (a Gera Systems product)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const server: McpServer;
+export declare function main(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,248 @@
+/**
+ * GeraJobs MCP Server (stdio)
+ *
+ * Exposes the Gera global jobs dataset to AI agents over the Model Context
+ * Protocol. Everything is answered locally from the same on-disk data the
+ * GeraJobs product renders — 30 job categories, 20 country job markets, and
+ * salary benchmarks aggregated from 1,002 real crawled listings — so an agent
+ * (Claude, ChatGPT with tools, any MCP client) can search categories, read
+ * salary benchmarks, and look up country markets entirely offline, no auth.
+ *
+ * Product: GeraJobs — https://gerajobs.com (a Gera Systems product)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { JOB_CATEGORIES, JOB_MARKETS, SALARY_ROLES, SALARY_TOTAL_LISTINGS, SALARY_GENERATED_AT, } from './dataset.generated.js';
+export const server = new McpServer({
+    name: 'gera-jobs',
+    version: '1.0.0',
+});
+function asText(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+}
+const SOURCE_NOTE = 'Data from GeraJobs (gerajobs.com), a Gera Systems product. Salary figures are aggregated ' +
+    `from ${SALARY_TOTAL_LISTINGS} real crawled job listings (snapshot ${SALARY_GENERATED_AT}); ` +
+    'category and market figures are GeraJobs editorial benchmarks. Orientation only.';
+function matchesQuery(cat, q) {
+    const hay = (cat.name +
+        ' ' +
+        cat.description +
+        ' ' +
+        cat.topSkills.join(' ') +
+        ' ' +
+        cat.keywords.join(' ')).toLowerCase();
+    return hay.includes(q);
+}
+function categorySummary(cat) {
+    return {
+        id: cat.id,
+        name: cat.name,
+        description: cat.description,
+        avg_salary_usd: cat.avgSalaryUSD,
+        top_skills: cat.topSkills,
+        trending: cat.trending,
+        remote_percentage: cat.remotePercentage,
+    };
+}
+// ── Tool 1: search_job_categories ────────────────────────────────────────────
+// Free-text search over the 30 real GeraJobs categories (name, description,
+// skills, keywords). The agent's main entry point from a plain-language query.
+server.registerTool('search_job_categories', {
+    title: 'Search GeraJobs job categories',
+    description: 'Search the 30 GeraJobs job categories by free-text query (matches name, description, required skills and SEO keywords). Use this first when a user describes a kind of work in plain language (e.g. "machine learning", "nursing", "remote design", "plumber"). Returns matching categories with average USD salary range, top skills, remote percentage and whether the field is trending. Pass no query to list every category.',
+    inputSchema: {
+        query: z
+            .string()
+            .optional()
+            .describe('Free-text query, e.g. "machine learning" or "remote sales". Omit to list all.'),
+        trending_only: z
+            .boolean()
+            .optional()
+            .describe('If true, only return categories flagged as trending in 2026.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(30)
+            .optional()
+            .describe('Max categories to return (default 10).'),
+    },
+}, async ({ query, trending_only, limit }) => {
+    const q = (query ?? '').trim().toLowerCase();
+    let matches = q ? JOB_CATEGORIES.filter((c) => matchesQuery(c, q)) : [...JOB_CATEGORIES];
+    if (trending_only)
+        matches = matches.filter((c) => c.trending);
+    const max = limit ?? 10;
+    return asText({
+        query: query ?? null,
+        trending_only: trending_only ?? false,
+        total_matches: matches.length,
+        categories: matches.slice(0, max).map(categorySummary),
+        source: SOURCE_NOTE,
+    });
+});
+// ── Tool 2: get_salary_benchmark ─────────────────────────────────────────────
+// Real salary benchmarks per role per market, from 1,002 crawled listings.
+const SALARY_ROLE_SLUGS = SALARY_ROLES.map((r) => r.slug);
+server.registerTool('get_salary_benchmark', {
+    title: 'Get a GeraJobs salary benchmark',
+    description: 'Return real salary benchmarks for a role, aggregated from crawled GeraJobs listings. For each market (country/currency) you get the sample size and median / 25th / 75th percentile / low / high annual pay — every number traces to real listings. Available roles: ' +
+        SALARY_ROLE_SLUGS.join(', ') +
+        '. Optionally filter to one country by ISO code (e.g. "US", "GB"). Omit currency to get all markets for the role.',
+    inputSchema: {
+        role: z
+            .string()
+            .describe('Role slug or name, e.g. "software-engineer", "Data Scientist", "product-manager".'),
+        country_code: z
+            .string()
+            .length(2)
+            .optional()
+            .describe('Optional ISO-3166 country code to filter to one market, e.g. "US", "GB", "CA".'),
+    },
+}, async ({ role, country_code }) => {
+    const needle = role.trim().toLowerCase().replace(/\s+/g, '-');
+    const found = SALARY_ROLES.find((r) => r.slug === needle) ??
+        SALARY_ROLES.find((r) => r.slug.includes(needle) || r.name.toLowerCase().includes(role.trim().toLowerCase()));
+    if (!found) {
+        return asText({
+            error: `No salary benchmark for role "${role}".`,
+            available_roles: SALARY_ROLES.map((r) => ({ slug: r.slug, name: r.name })),
+            source: SOURCE_NOTE,
+        });
+    }
+    let markets = found.markets;
+    if (country_code) {
+        const cc = country_code.toUpperCase();
+        markets = markets.filter((m) => m.countryCode === cc);
+    }
+    return asText({
+        role: { slug: found.slug, name: found.name },
+        total_sample_size: found.totalSampleSize,
+        markets,
+        sample_listings: found.sampleListings.slice(0, 5),
+        methodology: 'Annual figures only; hourly rows excluded. Median/percentiles computed per role × currency from crawled listings.',
+        source: SOURCE_NOTE,
+    });
+});
+// ── Tool 3: list_job_categories ──────────────────────────────────────────────
+// Compact index of every category + slug, so an agent can map descriptions to ids.
+server.registerTool('list_job_categories', {
+    title: 'List all GeraJobs categories',
+    description: 'List all 30 GeraJobs job categories with their id, name, average USD salary range and trending flag. Use this to get the canonical category ids to pass to other tools, or to give a user a full menu of fields GeraJobs covers.',
+    inputSchema: {},
+}, async () => asText({
+    count: JOB_CATEGORIES.length,
+    categories: JOB_CATEGORIES.map((c) => ({
+        id: c.id,
+        name: c.name,
+        avg_salary_usd: c.avgSalaryUSD,
+        trending: c.trending,
+        remote_percentage: c.remotePercentage,
+    })),
+    source: SOURCE_NOTE,
+}));
+// ── Tool 4: get_job_market ───────────────────────────────────────────────────
+// Country-level hiring intelligence for the 20 real GeraJobs markets.
+server.registerTool('get_job_market', {
+    title: 'Get a GeraJobs country job market',
+    description: 'Return the hiring profile for a country GeraJobs covers: average monthly wage + currency, top industries, top employers, job/AI growth rates, remote-work adoption and a market summary. Look up by ISO country code (e.g. "AM", "GB", "US"), country name, or city. Omit all arguments to list every covered market.',
+    inputSchema: {
+        country_code: z.string().optional().describe('ISO-3166 country code, e.g. "AM", "GE", "GB".'),
+        query: z
+            .string()
+            .optional()
+            .describe('Country name or city, e.g. "Armenia", "Yerevan", "United Kingdom".'),
+    },
+}, async ({ country_code, query }) => {
+    if (!country_code && !query) {
+        return asText({
+            count: JOB_MARKETS.length,
+            markets: JOB_MARKETS.map((m) => ({
+                country_code: m.countryCode,
+                country: m.country,
+                city: m.city,
+                currency: m.currency,
+            })),
+            source: SOURCE_NOTE,
+        });
+    }
+    let match = null;
+    if (country_code) {
+        const cc = country_code.toUpperCase();
+        match = JOB_MARKETS.find((m) => m.countryCode === cc) ?? null;
+    }
+    if (!match && query) {
+        const q = query.trim().toLowerCase();
+        match =
+            JOB_MARKETS.find((m) => m.country.toLowerCase() === q || m.city.toLowerCase() === q || m.slug === q) ??
+                JOB_MARKETS.find((m) => m.country.toLowerCase().includes(q) || m.city.toLowerCase().includes(q)) ??
+                null;
+    }
+    if (!match) {
+        return asText({
+            error: `No GeraJobs market for "${country_code ?? query}".`,
+            available_markets: JOB_MARKETS.map((m) => ({
+                country_code: m.countryCode,
+                country: m.country,
+            })),
+            source: SOURCE_NOTE,
+        });
+    }
+    return asText({ market: match, source: SOURCE_NOTE });
+});
+// ── Tool 5: get_category_details ─────────────────────────────────────────────
+// Full detail + FAQ for one category — the GEO/answer-engine payload.
+server.registerTool('get_category_details', {
+    title: 'Get full GeraJobs category details',
+    description: 'Return the full GeraJobs profile for one job category: description, average USD salary range, the complete top-skills list, remote percentage, and the curated FAQ (common questions and GeraJobs answers about salaries, skills, and how to find roles). Look up by category id (from list_job_categories) or name.',
+    inputSchema: {
+        category: z
+            .string()
+            .describe('Category id or name, e.g. "software-engineering" or "Data Science & AI".'),
+    },
+}, async ({ category }) => {
+    const q = category.trim().toLowerCase();
+    const found = JOB_CATEGORIES.find((c) => c.id === q) ??
+        JOB_CATEGORIES.find((c) => c.name.toLowerCase() === q) ??
+        JOB_CATEGORIES.find((c) => c.id.includes(q) || c.name.toLowerCase().includes(q));
+    if (!found) {
+        return asText({
+            error: `No GeraJobs category for "${category}".`,
+            available_categories: JOB_CATEGORIES.map((c) => ({ id: c.id, name: c.name })),
+            source: SOURCE_NOTE,
+        });
+    }
+    return asText({
+        id: found.id,
+        name: found.name,
+        description: found.description,
+        avg_salary_usd: found.avgSalaryUSD,
+        top_skills: found.topSkills,
+        trending: found.trending,
+        remote_percentage: found.remotePercentage,
+        faqs: found.faqs,
+        source: SOURCE_NOTE,
+    });
+});
+// ── Start ────────────────────────────────────────────────────────────────────
+export async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only — stdout is the MCP transport.
+    console.error('GeraJobs MCP server running on stdio (gera-jobs v1.0.0)');
+}
+// Run when invoked directly as the built server (node dist/server.js). The
+// bin/cli.js entry imports and calls main() itself, so we only auto-run for
+// direct server.js invocation to avoid a double start.
+const isMain = typeof process !== 'undefined' &&
+    process.argv[1] &&
+    /server\.js$/.test(process.argv[1]);
+if (isMain) {
+    main().catch((err) => {
+        console.error('Fatal:', err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@gera-services/mcp-gera-jobs",
+  "version": "1.0.0",
+  "description": "GeraJobs MCP server — search global job categories, read real salary benchmarks, and look up country job markets. Offline, no auth. A Gera Systems product.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "mcpName": "io.github.geraservicesuk/mcp-gera-jobs",
+  "bin": {
+    "mcp-gera-jobs": "bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build:dataset": "node scripts/build-dataset.mjs",
+    "build": "tsc --noCheck",
+    "type-check": "tsc --noEmit",
+    "start": "node bin/cli.js",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "jobs",
+    "job-search",
+    "salary-benchmark",
+    "gera",
+    "gera-jobs",
+    "recruitment"
+  ],
+  "author": "Gera Systems Ltd",
+  "homepage": "https://gerajobs.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geraservicesuk/globetura.git",
+    "directory": "packages/mcp-gera-jobs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.geraservicesuk/mcp-gera-jobs",
+  "description": "Search global job categories, real crawled salary benchmarks and country job markets. No auth.",
+  "version": "1.0.0",
+  "repository": {
+    "url": "https://github.com/geraservicesuk/globetura",
+    "source": "github",
+    "subfolder": "packages/mcp-gera-jobs"
+  },
+  "websiteUrl": "https://gerajobs.com",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@gera-services/mcp-gera-jobs",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}