io.github.rctruta/ashby-location-filter
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ashby-location-filter
A multi-company job search and filtering engine tailored for public Ashby job boards. It aggregates job postings from multiple companies into a single cohesive interface, normalizes inconsistent recruiter location entries, tracks daily additions and delistings, and provides real-time multi-faceted filtering.
What Problems This Solves
Multi-Company Aggregation: Search across all your target companies (e.g. Cohere, Ramp, Linear, InfluxData) in one place instead of opening dozens of career tabs.
Normalized City & Country Hierarchy: Recruiter strings like
"Toronto"(Cohere) and"Toronto, ON"(Ramp) are automatically merged into a single bucket (Toronto (76)), avoiding fragmented search buckets.Collision-Proof Location Scoping: Grouped by country (
optgroup) and scoped strictly by country code, ensuringLondon, ON(Canada) never merges withLondon(UK).Multi-Select Company & Workplace: Compare any subset of companies (e.g., Ramp + Linear) or view all companies with one click. Filter across Remote, Hybrid, and In-office simultaneously.
Diff Tracking: Highlights new openings added since the last run and marks roles delisted/removed by companies.
Zero-Build Architecture: Modern ES modules and CSS with no Node.js build step or bundler needed. Runs directly in any modern browser.
Related MCP server: io.github.groundtruthtools/ats-jobs-mcp
Getting Started
1. Prerequisites
Python 3.10+
uv (recommended) or standard Python
pipA modern web browser
2. Setup
Clone the repository and install dependencies:
git clone https://github.com/rctruta/ashby-location-filter.git
cd ashby-location-filter
uv syncImportant for contributors: To enable repository quality and security guardrails:
git config core.hooksPath .githooks
Workflow & Usage
1. Validate, Add, or Remove Companies
You can add or remove any company that uses Ashby for its careers page using the built-in CLI:
# Test & validate an Ashby job board without changing configuration
python3 -m tools.add_company notion --dry-run
# Automatically validate endpoint, register in config, and fetch snapshot
python3 -m tools.add_company https://jobs.ashbyhq.com/notion --name "Notion"
# Remove a company from publish_snapshot.yaml, delete its snapshot, and update manifest.json
python3 -m tools.add_company influxdata --removeThe CLI:
Extracts the company slug from a name, slug, or full career URL.
Validates the remote Ashby Posting API.
Checks
isListedjob counts.Appends the company configuration to
tools/publish_snapshot.yaml.Fetches the snapshot to
docs/data/<slug>.jsonand rebuildsdocs/data/manifest.json.
2. Update Job Board Snapshots
Refresh snapshots for all configured companies from live feeds:
python3 tools/publish_snapshot.py --allOr refresh an individual company or parse from a local test file:
python3 tools/publish_snapshot.py --company ramp
python3 tools/publish_snapshot.py path/to/sample_feed.json3. Launch the Web Interface Locally
Start a local web server to view and interact with the application:
python3 -m http.server 8080 --directory docsThen open http://localhost:8080 in your browser.
Integrating the Normalizer in Custom Job Boards
If you are building a custom career site with Ashby's Posting API, you can install and import the canonical normalizer directly (zero runtime dependencies, native Unicode CLDR):
npm install github:rctruta/ashby-location-filterimport { normalizeLocation, classifyScope } from "ashby-location-filter";
const result = normalizeLocation({
rawName: "San Fransisco, CA [Hiring Immediately]",
locality: "San Francisco",
region: "California",
country: "USA"
});
console.log(result);
// {
// canonicalCity: "San Francisco",
// canonicalRegion: "California",
// canonicalCountry: "United States",
// scope: "metro",
// isRemote: false,
// displayName: "San Francisco, United States",
// compoundKey: "p:United States|||San Francisco"
// }MCP Server (Claude Desktop, Cursor, Antigravity)
This repository includes a zero-dependency Model Context Protocol (MCP) server (mcp-name: io.github.rctruta/ashby-location-filter) that exposes canonical Ashby job search, location normalization, and scope classification tools over stdio:
normalize_location— Normalize raw ATS location strings + postal addresses using Unicode CLDR (Intl.DisplayNames) and recruiter alias rules.list_companies— List tracked Ashby job boards available in local snapshots.search_jobs— Search and filter jobs across tracked companies (or any live Ashby company slug) by canonical country, city, scope (global,country,region,metro), workplace type, department, or keyword.
Add to your MCP client configuration (e.g. claude_desktop_config.json or .cursor/mcp.json):
{
"mcpServers": {
"ashby-location-filter": {
"command": "npx",
"args": ["-y", "github:rctruta/ashby-location-filter"]
}
}
}Hosting Your Own Job Board Filter
You can easily fork this repository and host your own custom job board tracker for your personal list of target companies:
Option A: Free Static Hosting (GitHub Pages)
Fork this repository on GitHub.
Customize your company list: Edit
tools/publish_snapshot.yamlto include the companies you want to track, then runpython3 tools/publish_snapshot.py --all.Enable GitHub Pages: Go to your repository Settings → Pages → Source: Deploy from branch (
main, folder/docs).Daily Updates: The included GitHub Actions workflow (
.github/workflows/update_snapshots.yml) will automatically run every day at 06:00 UTC, fetch fresh postings, compute diffs, and commit them back to your repo.
Option B: Serverless On-Demand Hosting (Vercel)
If you want an on-demand deployment where visitors can query any company dynamically via an API proxy:
Connect your repository to Vercel: Import your GitHub fork into Vercel.
The included
vercel.jsonandapi/jobs.pyautomatically configure:Serving
docs/as the fast static frontend.An API proxy at
/api/jobs?company=<slug>that fetches live Ashby feeds and injects CORS headers.
Test locally with the serverless endpoint:
python3 api/jobs.py # In another terminal: curl "http://localhost:3000/api/jobs?company=linear"
Automated Daily Sync (GitHub Actions)
The repository includes a GitHub Actions workflow (.github/workflows/update_snapshots.yml):
Daily Cron: Runs automatically at 06:00 UTC every day.
Manual Trigger: Run on demand via Actions → Update Job Board Snapshots → Run workflow.
Automatically commits and pushes updated snapshots back to
main, keeping live deployments up-to-date with zero manual intervention.
Configuration (tools/publish_snapshot.yaml)
Companies and fields are configured declaratively:
posting_fields:
- id
- title
- department
- team
- location
- address
- secondaryLocations
- workplaceType
- jobUrl
companies:
- id: cohere
name: Cohere
provider: Ashby
feed_url: https://api.ashbyhq.com/posting-api/job-board/cohere
output: docs/data/cohere.json
- id: ashby
name: Ashby
provider: Ashby
feed_url: https://api.ashbyhq.com/posting-api/job-board/ashby
output: docs/data/ashby.json
manifest_output: docs/data/manifest.jsonRepository Guardrails & Integrity
This repository adheres to strict agent and human pair-programming contracts documented in AGENTS.md:
pre-commitandpre-pushhooks enforce clean trees, conventional commits, secret detection, and test suite passage.Run gate proof suite:
sh .gates/tests/prove_gates.sh.Run pytest suite:
uv run pytest.Run Node.js normalizer & MCP test suite:
npm test.
Future Roadmap
UI-Based Company Persistence: Allow users to add, pin, and persist custom Ashby company boards directly from the browser UI alongside daily repository snapshots.
Additional ATS Normalizer Adapters: Extend canonical location normalization and scope classification adapters to Greenhouse and Lever feeds.
License
Dual-licensed under the Apache License 2.0 (code and tools) and Creative Commons Attribution 4.0 International (CC BY 4.0) (documentation and published snapshot data).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Open jobs from Greenhouse, Lever, Ashby and 4 more ATSs in one schema, with new-job monitoring.
Ashby ATS job scraper pulls live postings via API with team filtering.
Open jobs at any company from Greenhouse, Lever, Ashby, Personio and Recruitee boards.
Search job postings across Indeed, LinkedIn, and more from one request - titles, companies
Related MCP Servers
- AlicenseAqualityBmaintenanceSearch and read public Ashby job boards for named companies, with filtering, full job details, and side-by-side compensation comparison. No API key required.579 npmMIT
- AlicenseAqualityCmaintenanceEnables querying open job postings directly from company applicant-tracking systems (Greenhouse, Ashby, Lever), finding a company's job board, listing and comparing roles, and accessing salary data, all without scraping or API keys.360 PyPI1MIT
- AlicenseAqualityDmaintenanceEnables real-time job search across thousands of companies' open roles from Greenhouse, Lever, Ashby, and SmartRecruiters, with full-text filtering and company-specific queries, no API key required.2MIT
- AlicenseAqualityCmaintenanceEnables querying job boards for a company's open roles, pulling from Greenhouse, Workday, and an opt-in LinkedIn source and normalizing the results into one shape. It discovers boards, searches one or many companies at once, and returns full postings with title-based AI/ML and junior filtering.7MIT