usajobs-mcp 1.0.0

package/README.md

@@ -0,0 +1,25 @@
+# USAJOBS MCP
+
+MCP server for USAJOBS: federal job search. Needs a free API key.
+
+## Setup
+
+Get a key at https://developer.usajobs.gov/ (free), then:
+
+```bash
+export USAJOBS_API_KEY=your_key_here
+export USAJOBS_EMAIL=you@example.com  # required contact in User-Agent
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `search_jobs`: Keyword + 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.

package/dist/api.d.ts

@@ -0,0 +1,17 @@
+export declare class UsajobsError extends Error {
+}
+export interface FedJob {
+    title?: string;
+    agency?: string;
+    locations: string[];
+    pay?: string;
+    grade?: string;
+    posted?: string;
+    closes?: string;
+    url?: string;
+}
+export declare function searchJobs(keyword: string, location?: string, limit?: number): Promise<{
+    total: number;
+    jobs: FedJob[];
+}>;
+export declare function formatJob(j: FedJob, index?: number): string;

package/dist/api.js

@@ -0,0 +1,58 @@
+/**
+ * USAJOBS API client. Needs USAJOBS_API_KEY (free at https://developer.usajobs.gov/)
+ * plus a contact email in the User-Agent header (USAJOBS_EMAIL).
+ * Docs: https://developer.usajobs.gov/
+ */
+const BASE = "https://data.usajobs.gov/api";
+export class UsajobsError extends Error {
+}
+function headers() {
+    const key = process.env.USAJOBS_API_KEY;
+    const email = process.env.USAJOBS_EMAIL ?? "mcp@example.com";
+    if (!key)
+        throw new UsajobsError("Set USAJOBS_API_KEY first (free at developer.usajobs.gov).");
+    return { "User-Agent": email, Accept: "application/json", "Authorization-Key": key };
+}
+async function getJson(path) {
+    const res = await fetch(`${BASE}${path}`, {
+        headers: headers(),
+        signal: AbortSignal.timeout(20000),
+    });
+    if (res.status === 401 || res.status === 403)
+        throw new UsajobsError("USAJOBS refused (401/403). Check API key.");
+    if (!res.ok)
+        throw new UsajobsError(`USAJOBS error ${res.status}`);
+    return (await res.json());
+}
+export async function searchJobs(keyword, location = "", limit = 5) {
+    const qs = new URLSearchParams({ Keyword: keyword.trim(), ResultsPerPage: String(Math.min(Math.max(limit, 1), 50)) });
+    if (location.trim())
+        qs.set("LocationName", location.trim());
+    const data = await getJson(`/search?${qs}`);
+    const sr = data.SearchResult ?? {};
+    const rows = Array.isArray(sr.SearchResultItems) ? sr.SearchResultItems : [];
+    const total = Number(sr.SearchResultCount ?? rows.length);
+    return {
+        total: isFinite(total) ? total : rows.length,
+        jobs: rows.slice(0, limit).map((it) => {
+            const d = it.MatchedObjectDescriptor ?? {};
+            const pay = d.PositionRemuneration?.[0] ?? {};
+            const locs = Array.isArray(d.PositionLocation) ? d.PositionLocation : [];
+            return {
+                title: d.PositionTitle,
+                agency: d.OrganizationName,
+                locations: locs.map((l) => String(l.LocationName ?? l.CityName ?? "")).filter(Boolean).slice(0, 3),
+                pay: pay.MinimumRange && pay.MaximumRange ? `$${pay.MinimumRange}-$${pay.MaximumRange}` : undefined,
+                grade: Array.isArray(d.JobGrade) ? d.JobGrade.map((g) => g.Code).join(",") : undefined,
+                posted: d.PublicationStartDate ? String(d.PublicationStartDate).slice(0, 10) : undefined,
+                closes: d.ApplicationCloseDate ? String(d.ApplicationCloseDate).slice(0, 10) : undefined,
+                url: d.PositionURI,
+            };
+        }),
+    };
+}
+export function formatJob(j, index) {
+    const prefix = index !== undefined ? `${index + 1}. ` : "";
+    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}` : ""}`;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,42 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { formatJob, searchJobs, UsajobsError } 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 };
+export function createServer() {
+    const server = new McpServer({
+        name: "usajobs-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_jobs", {
+        title: "Search federal jobs",
+        description: "US federal jobs by keyword and location, with pay bands and closing dates.",
+        inputSchema: z.object({
+            keyword: z.string().describe("Keyword, e.g. 'data scientist', 'park ranger'"),
+            location: z.string().default("").describe("Location, e.g. 'Washington, DC', empty = anywhere"),
+            limit: z.number().int().min(1).max(50).default(5),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ keyword, location, limit }) => {
+        try {
+            if (!keyword.trim())
+                return textError("Error: keyword is empty.");
+            const { total, jobs } = await searchJobs(keyword, location, limit);
+            if (jobs.length === 0)
+                return text("No federal jobs found.");
+            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 server;
+}
+function errorMessage(e) {
+    if (e instanceof UsajobsError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "usajobs-mcp",
+  "version": "1.0.0",
+  "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"
+  },
+  "bin": {
+    "usajobs-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "usajobs",
+    "jobs",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}