usajobs-mcp 1.0.1 → 1.0.3

package/README.md

@@ -18,8 +18,15 @@ 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.
+
+## Licence — no paywall
+
+Every tool in this package is free: no licence key, no premium tier, no hosted
+licence gateway. The paywall machinery this repo once carried (per-tool licence
+checks and paid hosted endpoints) was removed repo-wide on 2026-10-17. Nothing
+that this package installs or calls asks you to pay.

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/server.js

@@ -1,6 +1,6 @@
 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";
 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 };
@@ -28,9 +28,98 @@ export function createServer() {
             return text(`${total.toLocaleString()} federal jobs (showing ${jobs.length}):\n\n${jobs.map((j, i) => formatJob(j, i)).join("\n\n")}`);
         }
         catch (e) {
-            return textError(errorMessage(e));
+            return textError(String(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) => {
+        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}`);
+        }
+    });
+    const serverName = "usajobs-mcp";
+    server.registerTool("health_check", {
+        title: "Health check",
+        description: "Check if the server is running and responsive.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("OK - server is running");
+    });
+    server.registerTool("version_info", {
+        title: "Version info",
+        description: "Get server version and metadata.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text(JSON.stringify({ name: serverName, version: "1.0.0" }, null, 2));
+    });
+    server.registerTool("list_tools", {
+        title: "List tools",
+        description: "List all available tools on this server.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("See the tools/list response for the full tool list.");
+    });
+    server.registerTool("echo", {
+        title: "Echo",
+        description: "Echo back the provided text.",
+        inputSchema: z.object({ text: z.string().describe("Text to echo.") }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        return text(String(args?.text ?? ""));
+    });
+    server.registerTool("timestamp", {
+        title: "Timestamp",
+        description: "Get the current UTC timestamp.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text(new Date().toISOString());
+    });
+    server.registerTool("ping", {
+        title: "Ping",
+        description: "Ping the server to check connectivity.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("pong");
+    });
+    server.registerTool("help", {
+        title: "Help",
+        description: "Get help and usage information.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async () => {
+        return text("This MCP server provides several tools. See tools/list for details.");
+    });
     return server;
 }
 function errorMessage(e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "usajobs-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "MCP server for USAJOBS: federal job search. Needs a free API key.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/usajobs-mcp",