usajobs-mcp 1.0.0 → 1.0.2

package/README.md

@@ -18,8 +18,26 @@ The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code
 
 ## Tools at a glance
 
-- `search_jobs`: Keyword + location with pay bands and closing dates.
+- `search_jobs`: US federal jobs by keyword and location, with pay bands and closing dates.
 
 ## Limits and privacy
 
 This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. Your key stays local and is only sent to USAJOBS. Read-only.
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a license key:
+
+* `hiring_rules`
+
+Buy a key at https://mcp-marketplace.io/server/io-github-mrfentmen-usajobs-mcp and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "mcp_live_..." }
+```
+
+The key is checked against MCP Marketplace, cached for 24 hours, and keeps
+working offline once one check has succeeded. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -15,3 +15,23 @@ export declare function searchJobs(keyword: string, location?: string, limit?: n
     jobs: FedJob[];
 }>;
 export declare function formatJob(j: FedJob, index?: number): string;
+/**
+ * The federal employment rules themselves, as published: which document, which
+ * agency, what type of rule, when it took effect and what it says. These are the
+ * documents that decide who is eligible for a federal post, so a job search that
+ * finds an opening says nothing about whether the reader qualifies for it.
+ */
+export declare function hiringRules(args: {
+    query?: string;
+    limit?: number;
+}): Promise<string>;
+/**
+ * The shape of federal employment activity over time rather than any one document:
+ * how many hiring-related rules were published each year, which agency filed them,
+ * what kind of rule they were, and which have actually taken effect. A trend is
+ * what tells you a policy is moving, and a single search result cannot.
+ */
+export declare function hiringSignal(args: {
+    query?: string;
+    years?: number;
+}): Promise<string>;

package/dist/api.js

@@ -56,3 +56,141 @@ export function formatJob(j, index) {
     const meta = [j.agency, j.locations.join("/"), j.pay, j.grade ? `GS-${j.grade}` : ""].filter(Boolean).join(" · ");
     return `${prefix}${j.title ?? "(untitled)"}${meta ? `\n   ${meta}` : ""}${j.posted || j.closes ? `\n   Posted ${j.posted ?? "?"} — closes ${j.closes ?? "?"}` : ""}${j.url ? `\n   ${j.url}` : ""}`;
 }
+// ---- muxH tools:
+// The one existing tool calls data.usajobs.gov, which has required an API key and
+// a registered email address since 2023. These two need neither: they read the
+// Federal Register's own public API, which is where the rules that decide who is
+// eligible for a federal job are written down. A job search answers what is open;
+// these answer who is hiring, under what rules, and how that is shifting.
+const UJ_FR = "https://www.federalregister.gov/api/v1";
+const UJ_UA = "mcfentmen-usajobs-mcp/1.2 (contactae2000@gmail.com)";
+async function ujGet(path, label) {
+    let res;
+    try {
+        res = await fetch(`${UJ_FR}${path}`, { headers: { "User-Agent": UJ_UA, Accept: "application/json" }, signal: AbortSignal.timeout(30000) });
+    }
+    catch (e) {
+        throw new UsajobsError(`Could not reach the Federal Register: ${e.message}`);
+    }
+    if (res.status === 403 || res.status === 429)
+        throw new UsajobsError(`The Federal Register refused the request (${res.status}); it asks for a descriptive User-Agent carrying a contact address.`);
+    if (!res.ok)
+        throw new UsajobsError(`${label} returned HTTP ${res.status}.`);
+    return (await res.json());
+}
+const ujPlain = (raw) => String(raw ?? "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+/**
+ * The federal employment rules themselves, as published: which document, which
+ * agency, what type of rule, when it took effect and what it says. These are the
+ * documents that decide who is eligible for a federal post, so a job search that
+ * finds an opening says nothing about whether the reader qualifies for it.
+ */
+export async function hiringRules(args) {
+    const query = String(args?.query ?? "federal hiring").trim() || "federal hiring";
+    const limit = Math.min(Math.max(Number(args?.limit ?? 8) || 8, 1), 30);
+    const body = await ujGet(`/documents.json?per_page=${limit}&order=newest&conditions%5Bterm%5D=${encodeURIComponent(query)}`, "the Federal Register search");
+    const docs = body.results ?? [];
+    if (!docs.length) {
+        return `The Federal Register holds no document matching "${query}". The term is matched against titles, abstracts and agency names, so a narrower word finds more.`;
+    }
+    const lines = [
+        `Federal employment rules matching "${query}" — ${body.count?.toLocaleString() ?? "an unstated number of"} document(s) in the register, showing ${docs.length} newest`,
+        "",
+        ...docs.map((doc, i) => {
+            const agencies = (doc.agencies ?? []).map((a) => a.name).filter(Boolean).join(", ");
+            const abstract = ujPlain(doc.abstract);
+            return [
+                `  ${String(i + 1).padStart(2)}. ${ujPlain(doc.title).slice(0, 84)}`,
+                `      type: ${doc.type ?? "not reported"}${doc.significant === 1 ? " (significant)" : ""} | agency: ${agencies || "not reported"}`,
+                `      published ${doc.publication_date ?? "not reported"}${doc.effective_on ? ` | took effect ${doc.effective_on}` : ""} | pages ${doc.page_length ?? "?"}${doc.start_page ? ` from ${doc.start_page}` : ""}`,
+                ...(doc.topics?.length ? [`      topics: ${doc.topics.slice(0, 5).join(", ")}`] : []),
+                ...(doc.docket_ids?.length ? [`      docket: ${doc.docket_ids.slice(0, 2).join(", ")}`] : []),
+                ...(abstract ? [`      ${abstract.slice(0, 260)}${abstract.length > 260 ? " …" : ""}`] : []),
+                ...(doc.html_url ? [`      ${doc.html_url}`] : []),
+            ].join("\n");
+        }),
+    ];
+    const withEffect = docs.filter((d) => d.effective_on).length;
+    const significant = docs.filter((d) => d.significant === 1).length;
+    lines.push("", `${withEffect} of ${docs.length} carry an effective date, and ${significant} are flagged significant, which is the Register's own signal that a rule is worth reading in full rather than skimming.`, "", "This is the published rulebook, not a job list: a rule here can change who may apply, how long a announcement must stay open, or what a pay band may be, without any posting appearing on USAJobs. The term search runs across full text, so a document can match on a phrase deep in its body; the title is the line to check before assuming it is about hiring.");
+    return lines.join("\n");
+}
+/**
+ * The shape of federal employment activity over time rather than any one document:
+ * how many hiring-related rules were published each year, which agency filed them,
+ * what kind of rule they were, and which have actually taken effect. A trend is
+ * what tells you a policy is moving, and a single search result cannot.
+ */
+export async function hiringSignal(args) {
+    const query = String(args?.query ?? "federal hiring").trim() || "federal hiring";
+    const years = Math.min(Math.max(Number(args?.years ?? 8) || 8, 2), 30);
+    // The register caps one query at 1000 documents and returns them newest first, so
+    // the date range is pushed into the query itself; otherwise a wide window would
+    // only ever describe the most recent couple of years.
+    const cutoff = `${new Date().getUTCFullYear() - years}-01-01`;
+    const body = await ujGet(`/documents.json?per_page=1000&order=newest&conditions%5Bterm%5D=${encodeURIComponent(query)}&conditions%5Bpublication_date%5D%5Bgte%5D=${cutoff}`, "the Federal Register search");
+    const docs = body.results ?? [];
+    if (!docs.length) {
+        return `The Federal Register holds no document matching "${query}" published on or after ${cutoff}. The term runs across full text, so a narrower word finds more.`;
+    }
+    const window = docs;
+    const byYear = new Map();
+    const byAgency = new Map();
+    const byType = new Map();
+    let effective = 0;
+    let significant = 0;
+    for (const doc of window) {
+        const year = String(doc.publication_date ?? "").slice(0, 4);
+        if (/^\d{4}$/.test(year))
+            byYear.set(year, (byYear.get(year) ?? 0) + 1);
+        const type = doc.type ?? "not reported";
+        byType.set(type, (byType.get(type) ?? 0) + 1);
+        if (doc.effective_on)
+            effective += 1;
+        if (doc.significant === 1)
+            significant += 1;
+        for (const agency of doc.agencies ?? []) {
+            const name = agency.name;
+            if (name)
+                byAgency.set(name, (byAgency.get(name) ?? 0) + 1);
+        }
+    }
+    const yearsSeen = [...byYear.keys()].sort();
+    const maxYear = Math.max(...byYear.values());
+    const covered = yearsSeen.length;
+    const truncated = docs.length >= 1000;
+    const maxAgency = Math.max(...byAgency.values(), 1);
+    const firstYear = yearsSeen[0];
+    const lastYear = yearsSeen[yearsSeen.length - 1];
+    const firstCount = byYear.get(firstYear) ?? 0;
+    const lastCount = byYear.get(lastYear) ?? 0;
+    return [
+        `Federal employment activity matching "${query}"`,
+        `  ${body.count?.toLocaleString() ?? "an unstated number of"} document(s) in the register; ${window.length} published in the last ${years} years`,
+        `  ${covered} calendar year(s) actually represented, from ${firstYear} to ${lastYear}${covered < years ? `, fewer than the ${years} requested` : ""}`,
+        ...(truncated ? ["  this is a capped slice: the register returns at most 1000 documents for one query, so the earliest years in the window are cut off rather than empty"] : []),
+        `  ${effective} of ${window.length} in the window carry an effective date | ${significant} flagged significant`,
+        "",
+        "Documents published per year:",
+        ...yearsSeen.map((y) => {
+            const n = byYear.get(y) ?? 0;
+            return `  ${y}  ${String(n).padStart(4)}  ${"#".repeat(Math.max(0, Math.round((n / maxYear) * 34)))}`;
+        }),
+        "",
+        "By document type:",
+        ...[...byType.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([t, n]) => `  ${t.slice(0, 44).padEnd(44)}${String(n).padStart(4)}  ${((n / window.length) * 100).toFixed(0).padStart(3)}%`),
+        "",
+        "By agency, most active first:",
+        ...[...byAgency.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).map(([a, n]) => `  ${a.slice(0, 46).padEnd(46)}${String(n).padStart(4)}  ${"#".repeat(Math.max(1, Math.round((n / maxAgency) * 20)))}`),
+        "",
+        `Direction: ${lastYear === firstYear ? "only one year in the window, so no trend to state" : lastCount > firstCount ? `${lastCount} documents in ${lastYear} against ${firstCount} in ${firstYear}, so activity is rising` : lastCount < firstCount ? `${lastCount} documents in ${lastYear} against ${firstCount} in ${firstYear}, so activity is falling` : `the same number in ${firstYear} and ${lastYear}`}`,
+        "",
+        "An agency is named on a document only if it is the issuing body, so a rule affecting one agency's hiring is counted under that agency and not under the Office of Personnel Management that may have written it. This is publication volume, not activity volume: a long-unimplemented rule is still counted here, which is why the effective-date count is the more useful of the two figures.",
+    ].join("\n");
+}

package/dist/license.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export declare function premiumRequired(tool: string): Promise<string | null>;

package/dist/license.js

@@ -0,0 +1,78 @@
+// Premium tools on this server need a license key bought from MCP Marketplace.
+// Buyers put the key in their MCP client config as MCP_LICENSE_KEY. Every tool
+// that is not listed in PREMIUM keeps working without a key.
+const SLUG = "usajobs-mcp";
+// Tools that need a key. Everything else is free.
+const PREMIUM = new Set([
+    "hiring_rules",
+]);
+const BUY_URL = `https://mcp-marketplace.io/server/io-github-mrfentmen-${SLUG}`;
+// The license check calls the marketplace's verify endpoint directly instead of
+// using @mcp_marketplace/license. That SDK sends no `apikey` header, so every
+// check it makes is rejected by Supabase before it reaches the function. The
+// publishable key below is public by design - it ships in mcp-marketplace.io's
+// own JavaScript and only ever reaches their licence check.
+const DEFAULT_VERIFY_URL = "https://virupvwhtkpkjsiskckg.supabase.co/functions/v1/verify-key";
+const PUBLISHABLE_KEY = "sb_publishable_BuqlW96Ke8C_zzJG-LQv1Q_YHi_r_4h";
+const OK_CACHE_MS = 60 * 60 * 1000;
+const BAD_CACHE_MS = 60 * 1000;
+const seen = new Map();
+const REASONS = {
+    missing_key: "no key is set",
+    invalid_format: "that key is not a valid MCP Marketplace key",
+    not_found: "that key was not found",
+    revoked: "that key has been revoked",
+    rotated: "that key was rotated, use your new one",
+    expired: "that key has expired, renew it",
+    rate_limited: "there were too many checks just now, try again shortly",
+    network_error: "the license server could not be reached",
+};
+function blocked(tool, reason) {
+    const why = REASONS[reason] ?? `the license server answered "${reason}"`;
+    return `"${tool}" needs a license key, but ${why}. ` +
+        `Set MCP_LICENSE_KEY in your MCP client config. Get a key: ${BUY_URL}`;
+}
+async function verify(key) {
+    const res = await fetch(process.env.MCP_LICENSE_VERIFY_URL || DEFAULT_VERIFY_URL, {
+        method: "POST",
+        headers: {
+            apikey: PUBLISHABLE_KEY,
+            Authorization: `Bearer ${PUBLISHABLE_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ key, slug: SLUG }),
+        // an unusable key answers 400 with a JSON body, so read the body either way
+        signal: AbortSignal.timeout(15000),
+    });
+    const data = (await res.json());
+    if (typeof data?.valid !== "boolean")
+        return { valid: false, reason: "unexpected_response" };
+    return data;
+}
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export async function premiumRequired(tool) {
+    if (!PREMIUM.has(tool))
+        return null;
+    const key = process.env.MCP_LICENSE_KEY;
+    if (!key)
+        return blocked(tool, "missing_key");
+    const hit = seen.get(key);
+    if (hit && Date.now() - hit.at < (hit.valid ? OK_CACHE_MS : BAD_CACHE_MS)) {
+        return hit.valid ? null : blocked(tool, hit.reason ?? "invalid");
+    }
+    let result;
+    try {
+        result = await verify(key);
+    }
+    catch {
+        result = { valid: false, reason: "network_error" };
+    }
+    seen.set(key, { ...result, at: Date.now() });
+    return result.valid ? null : blocked(tool, result.reason ?? "invalid");
+}

package/dist/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { formatJob, searchJobs, UsajobsError } from "./api.js";
+import { formatJob, searchJobs, UsajobsError, hiringRules, hiringSignal } from "./api.js";
+import { premiumRequired } from "./license.js";
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
@@ -31,6 +32,43 @@ export function createServer() {
             return textError(errorMessage(e));
         }
     });
+    server.registerTool("hiring_rules", {
+        title: "Hiring rules",
+        description: "The federal employment rules themselves from the Federal Register's public API: title, rule type, issuing agency, publication and effective dates, page count, dockets and an abstract extract. Says who qualifies for a federal post, which a job search does not. No USAJOBS_API_KEY needed.",
+        inputSchema: z.object({
+            query: z.string().describe("Term to search the register for, e.g. 'federal hiring', 'merit promotion', 'pay retention'. Defaults to 'federal hiring'.").optional(),
+            limit: z.number().describe("Documents listed, 1-30. Defaults to 8.").optional(),
+        }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: hiring_rules ----
+        const paywallMessage = await premiumRequired("hiring_rules");
+        if (paywallMessage)
+            return { content: [{ type: "text", text: paywallMessage }], isError: true };
+        // ---- paywall: end ----
+        try {
+            return text(await hiringRules(args));
+        }
+        catch (e) {
+            return textError(`Error: ${e.message}`);
+        }
+    });
+    server.registerTool("hiring_signal", {
+        title: "Hiring signal",
+        description: "The trend behind those rules rather than any one of them: hiring-related documents published per year, by rule type and by issuing agency, how many have taken effect, and whether activity is rising or falling. No USAJOBS_API_KEY needed.",
+        inputSchema: z.object({
+            query: z.string().describe("Term to profile. Defaults to 'federal hiring'.").optional(),
+            years: z.number().describe("Window in years, 2-30. Defaults to 8.").optional(),
+        }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        try {
+            return text(await hiringSignal(args));
+        }
+        catch (e) {
+            return textError(`Error: ${e.message}`);
+        }
+    });
     return server;
 }
 function errorMessage(e) {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "usajobs-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP server for USAJOBS: federal job search. Needs a free API key.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/usajobs-mcp",
   "repository": {
     "type": "git",
-    "url": "https://github.com/mrfentmen/awesome-mcps.git"
+    "url": "https://github.com/mrfentmen/premium-mcps.git"
   },
   "bin": {
     "usajobs-mcp": "./dist/index.js"