io.github.rctruta/ashby-location-filter
by rctruta
README.md
# ashby-location-filter
[](https://github.com/rctruta/ashby-location-filter/actions/workflows/ci.yml)
[](https://github.com/rctruta/ashby-location-filter/actions/workflows/update_snapshots.yml)
[](https://github.com/rctruta/ashby-location-filter/blob/main/package.json)
[](https://github.com/rctruta/ashby-location-filter#mcp-server-claude-desktop-cursor-antigravity)
[](https://github.com/rctruta/ashby-location-filter/blob/main/LICENSE)
[](https://rctruta.github.io/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
1. **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.
2. **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.
3. **Collision-Proof Location Scoping:** Grouped by country (`optgroup`) and scoped strictly by country code, ensuring `London, ON` (Canada) never merges with `London` (UK).
4. **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.
5. **Diff Tracking:** Highlights new openings added since the last run and marks roles delisted/removed by companies.
6. **Zero-Build Architecture:** Modern ES modules and CSS with no Node.js build step or bundler needed. Runs directly in any modern browser.
---
## Getting Started
### 1. Prerequisites
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (recommended) or standard Python `pip`
- A modern web browser
### 2. Setup
Clone the repository and install dependencies:
```sh
git clone https://github.com/rctruta/ashby-location-filter.git
cd ashby-location-filter
uv sync
```
> **Important for contributors:** To enable repository quality and security guardrails:
> ```sh
> 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:
```sh
# 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 --remove
```
The CLI:
- Extracts the company slug from a name, slug, or full career URL.
- Validates the remote Ashby Posting API.
- Checks `isListed` job counts.
- Appends the company configuration to `tools/publish_snapshot.yaml`.
- Fetches the snapshot to `docs/data/<slug>.json` and rebuilds `docs/data/manifest.json`.
### 2. Update Job Board Snapshots
Refresh snapshots for all configured companies from live feeds:
```sh
python3 tools/publish_snapshot.py --all
```
Or refresh an individual company or parse from a local test file:
```sh
python3 tools/publish_snapshot.py --company ramp
python3 tools/publish_snapshot.py path/to/sample_feed.json
```
### 3. Launch the Web Interface Locally
Start a local web server to view and interact with the application:
```sh
python3 -m http.server 8080 --directory docs
```
Then 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):
```sh
npm install github:rctruta/ashby-location-filter
```
```javascript
import { 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)
<!-- mcp-name: io.github.rctruta/ashby-location-filter -->
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`):
```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)
1. **Fork this repository** on GitHub.
2. **Customize your company list:** Edit `tools/publish_snapshot.yaml` to include the companies you want to track, then run `python3 tools/publish_snapshot.py --all`.
3. **Enable GitHub Pages:** Go to your repository **Settings → Pages → Source: Deploy from branch (`main`, folder `/docs`)**.
4. **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:
1. **Connect your repository to Vercel:** Import your GitHub fork into [Vercel](https://vercel.com).
2. The included [`vercel.json`](vercel.json) and [`api/jobs.py`](api/jobs.py) automatically 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.
3. Test locally with the serverless endpoint:
```sh
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:
```yaml
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.json
```
---
## Repository Guardrails & Integrity
This repository adheres to strict agent and human pair-programming contracts documented in `AGENTS.md`:
- `pre-commit` and `pre-push` hooks 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](LICENSE) (code and tools) and [Creative Commons Attribution 4.0 International (CC BY 4.0)](LICENSE) (documentation and published snapshot data).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues