{
  "markdown": "# federal-compass-mcp\n\n> Your AI compass from private sector to federal career\n\n[![npm version](https://img.shields.io/npm/v/federal-compass-mcp.svg)](https://npmjs.org/package/federal-compass-mcp)\n[![CI](https://github.com/skivuha/federal-compass-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/skivuha/federal-compass-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blue.svg)](https://modelcontextprotocol.io)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/skivuha/federal-compass-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/skivuha/federal-compass-mcp)\n\nFederal job descriptions are 5 pages of legal language. GS grades, clearance levels, hiring paths — none of this is explained anywhere. `federal-compass-mcp` connects Claude to the official [USAJobs API](https://developer.usajobs.gov) and turns it into an AI advisor that speaks plain English.\n\nBuilt for tech professionals transitioning from private sector to federal/government careers.\n\n---\n\n## What it does\n\n- **Searches** federal job openings with optional filters — keyword, location, salary, clearance level\n- **Translates** federal job descriptions into plain language — what they actually want, without the jargon\n- **Analyzes** your CV against specific job postings and tells you if you qualify\n- **Explains** federal concepts — GS grades, pay plans, security clearances, hiring paths\n- **Saves** your CV locally so Claude can reference it automatically\n\n---\n\n## Getting started\n\n### 1. Get your free USAJobs API key\n\nRegister at [developer.usajobs.gov](https://developer.usajobs.gov/apirequest/index) — takes about 3 minutes. Verify your email and you'll receive an API token.\n\n### 2. Add to your MCP client\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"federal-compass\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"federal-compass-mcp@latest\"],\n      \"env\": {\n        \"USAJOBS_API_KEY\": \"your_api_key\",\n        \"USAJOBS_EMAIL\": \"your@email.com\"\n      }\n    }\n  }\n}\n```\n\n**VS Code / Cursor / Windsurf** — same config, different config file path. See your client's MCP documentation.\n\n### 3. Try it\n\n```\nFind me senior software developer jobs in Raleigh, NC\n```\n\n```\nWhat is a GS-13 and how much does it pay?\n```\n\n```\nSave my CV [attach file]\n```\n\n```\nLook at this job posting — am I qualified?\n```\n\n---\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `search_jobs` | Search federal job openings. All filters optional — keyword, location, salary, grade, agency, remote |\n| `get_job_details` | Get full details for a specific job posting |\n| `compare_jobs` | Compare 2-5 job postings side by side |\n| `save_cv` | Save your CV locally for automatic use in analysis |\n| `get_cv` | Read your saved CV |\n| `explain_federal_concept` | Explain GS grades, clearances, hiring paths, pay plans |\n| `calculate_salary` | Calculate GS salary with locality pay for any grade, step, and location |\n| `find_matching_jobs` | Find jobs matching your CV — extracts skills and searches USAJobs |\n| `check_qualification` | Compare your CV against a specific job posting |\n| `extract_ksa` | Extract KSA requirements from a job posting, optionally match against your CV |\n\n---\n\n## CV storage\n\nYour CV is stored locally on your machine — never sent to any server:\n\n```\n~/.federal-compass/\n  cv.json\n  config.json\n  codelists/     <- cached USAJobs reference data\n```\n\n---\n\n## Why federal jobs are confusing (and how this helps)\n\nComing from private sector, federal job postings feel like a different language:\n\n- **GS-13 Step 1-10** — what grade am I? what does step mean?\n- **TS/SCI with polygraph** — do I need this? how long does it take?\n- **Competitive vs Excepted Service** — which one can I apply to?\n- **HiringPath: fed-transition** — what is this and why does it matter?\n\n`federal-compass-mcp` answers all of these through natural conversation with Claude.\n\n---\n\n## Requirements\n\n- Node.js v22+\n- Free [USAJobs API key](https://developer.usajobs.gov/apirequest/index)\n- Any MCP-compatible client (Claude Desktop, VS Code, Cursor, etc.)\n\n---\n\n## Contributing\n\nIssues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n*Built by [@skivuha](https://github.com/skivuha) — a Senior Frontend Engineer navigating the private-to-federal transition firsthand.*\n",
  "bytes": 4543,
  "sha": "b8a279fe1437dbc3b508c94e916a546a6071ab54c4d236cd525dd332b697010a",
  "repo_slug": "skivuha/federal-compass-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_skivuha_federal_compass_mcp_0bdcfee3/readme"
}