findyet-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 freehire contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# Findyet MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [MCP](https://modelcontextprotocol.io) server over the [Findyet](https://findyet.devjoys.com)
+job API. It lets any MCP host — Claude Desktop, Claude Code, or a compatible agent —
+**search, filter, track and tailor applications** without a browser, authenticating with a
+personal API key. Postings come straight from company career pages, normalized into one
+schema and tagged with stack, seniority, region and work mode.
+
+## Install
+
+### Hosted endpoint (no install)
+
+Findyet serves MCP over Streamable HTTP, so most hosts need nothing installed:
+
+- `https://findyet.devjoys.com/api/v1/mcp` — read-only catalogue (search, jobs, employers,
+  salaries, market stats). No key.
+- `https://findyet.devjoys.com/api/v1/mcp/account` — your account (profile, saved jobs,
+  tracking, market fit). Send your key as `Authorization: Bearer fyk_…`.
+
+In Claude Code:
+
+```bash
+claude mcp add --transport http findyet https://findyet.devjoys.com/api/v1/mcp/account \
+  --header "Authorization: Bearer fyk_xxxxxxxx"
+```
+
+In other hosts, add the URL as a custom remote connector with that header.
+
+### Local server (stdio)
+
+This package is the full tool set (CV tailoring, experience bank, submissions) as a local
+stdio server. Build it and point your host at `dist/index.js`:
+
+```json
+{
+  "mcpServers": {
+    "findyet": {
+      "command": "node",
+      "args": ["/path/to/findyet/mcp/dist/index.js"],
+      "env": { "FINDYET_TOKEN": "fyk_xxxxxxxx" }
+    }
+  }
+}
+```
+
+Create the `fyk_…` key in the web app (findyet.devjoys.com → account menu → **API keys**).
+
+## Authentication
+
+The token and API base URL resolve with precedence
+**env → `~/.findyet/creds.json` → default `https://findyet.devjoys.com`**:
+
+| What | Sources |
+|------|---------|
+| Token | `FINDYET_TOKEN` → creds file |
+| API base URL | `FINDYET_API_URL` → creds file → `https://findyet.devjoys.com` |
+
+The server only reads the credentials file (it never writes it). If no token is configured,
+tools return a clear "not authenticated" error rather than the server failing to start.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `whoami` | Authenticated user (verify the key). |
+| `facets` | The filter/skill vocabulary: every facet's live values with counts. **Call first.** |
+| `search` | Keyword + facet job search; returns jobs **with their full description as markdown** and the total match count. |
+| `market_fit` | Score a skill list against live market demand (coverage + gaps). |
+| `job` | A single job's full content by slug. |
+| `company` | A company and its open jobs by slug. |
+| `apply` | Mark a job applied. |
+| `save` / `unsave` | Bookmark / remove a bookmark. |
+| `stage` | Set the application stage (server-validated). |
+| `note` | Attach a free-text note. |
+| `my` | The caller's tracked jobs (all/viewed/saved/applied) with stage + note. |
+| `cv_tailor` | Start (or reopen) tailoring for a vacancy; returns the CV id the other `cv_*` tools take. |
+| `cv_list` | The caller's tailored CVs with the vacancy each was written for. |
+| `cv_context` | The fit analysis a tailored CV should reframe toward (missing_have vs missing_gap). |
+| `cv_get` | A tailored CV's full document. |
+| `cv_edit` | Apply a batch of path-addressed edits to a tailored CV, atomically (server-validated; uncited claims are refused). |
+| `cv_render` | Render a tailored CV to a PDF, returned as a base64 `application/pdf` resource. |
+| `experience_list` | The candidate's experience bank, with each achievement's **provenance**. `cv_edit`'s `evidence_id` comes from here. |
+| `experience_add_employment` / `experience_add_achievement` | Record a place, or one piece of evidence. |
+| `experience_update_employment` / `experience_update_achievement` | Correct one. Field-level: what you do not name is kept. |
+| `experience_remove_employment` / `experience_remove_achievement` | Delete one. No undo; a place must be empty first. |
+| `submit` | Submit a vacancy for moderation. |
+| `my_submissions` | The caller's submissions with status. |
+| `jobs_add` / `jobs_edit` | Moderator: author / edit a job (403 without the role). |
+| `submissions_pending` | Moderator: the review queue. |
+| `submission_approve` / `submission_reject` | Moderator: decide on a submission. |
+
+**Filters.** `search`, `market_fit`, and `facets` share the same market-filter
+parameters: `remote`, `region`, `country`, `city`, `company`, `category`, `role`,
+`seniority`, `employment_type`, `english_level`, `exclude_skill`, `salary_min`, `visa`,
+plus a generic `facets` map (`{"source": "greenhouse"}`) for any other facet in the
+vocabulary. Discover valid values with the `facets` tool — do not invent them. In
+`search`, `skills` is a filter; in `market_fit`, `skills` is the measured set.
+
+**Geography widens.** `region`, `country` and `city` are ONE OR-group: `region: ["eu"]`
+with `country: ["IT"]` means "in Europe **or** in Italy" and returns everything the
+region alone would. To search a single country, pass `country` and omit `region`. The
+three name a single concept — *where* — so picking two places reads as "either", which
+is what makes `region: ["eu"]` with `country: ["BR"]` ("Europe or Brazil") useful. There
+is no AND to switch on: `_mode=and` does not apply to geography.
+
+**Unread params are ignored, not refused.** A filter key the API does not recognize
+does not fail the request, it widens it. Such keys come back in the result's `ignored`
+list, with `did_you_mean` when only the grammatical number was wrong. `search` reports it
+alongside `total`; `facets` and `market_fit` answer a single object, so they wrap it as
+`{data, ignored}` — and only then, leaving a clean call's shape untouched. Any number from
+a result carrying `ignored` answers a broader question than the one asked — retry with the
+suggested name before reporting it.
+
+**Descriptions.** `search` reads the API's agent endpoint, so every hit already carries
+the posting's full description rendered as markdown — a host can screen a result set
+without a `job` call per hit. Descriptions are long, so keep `limit` modest.
+
+**The evidence rule.** Every achievement in the bank records who asserted it.
+`cv_import`, `stated_in_chat` and `manual` mean the candidate did, and may be cited on a
+CV; `agent_inferred` means a model read it into the record, and may not. `cv_edit`
+refuses any claim about the candidate without an `evidence_id` pointing at a citable one,
+which is why `experience_list` is the tool that makes `cv_edit` usable at all.
+
+Correcting an achievement does not move that label: an `agent_inferred` one stays
+uncitable however it is reworded. The only way it becomes citable is to ask the
+candidate, then record what **they** say with `experience_add_achievement`.
+
+**Removing is final** — the bank has no undo. A place must be emptied before it can go,
+because deleting one would take every achievement under it. Folding two achievements into
+one, keeping the numbers from both, is on the site.
+
+Each tool returns the raw API `data` as JSON text; an API error becomes an `isError`
+result carrying the HTTP status (a 401 adds an auth hint).
+
+## Develop
+
+```bash
+npm install
+npm test        # vitest: config, client (mock server), facets, tool dispatch
+npm run build   # tsc → dist/
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/client.js

@@ -0,0 +1,391 @@
+// A thin HTTP client for the freehire API. It authenticates with an API key
+// (Authorization: Bearer) and returns the raw `data` field of each response, so
+// tools can serialize it verbatim for the agent. Mirrors the freehire CLI client.
+/** ApiError is a non-2xx API response, carrying the HTTP status so callers can
+ * branch on it (e.g. 401 → prompt to authenticate). */
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message ? `api error ${status}: ${message}` : `api error ${status}`);
+        this.name = "ApiError";
+        this.status = status;
+    }
+}
+/** Client talks to the freehire API, sending the API key as a bearer token on
+ * every request. fetchImpl is injectable for testing. */
+export class Client {
+    baseURL;
+    token;
+    fetchImpl;
+    constructor(baseURL, token, fetchImpl = fetch) {
+        this.baseURL = baseURL.replace(/\/+$/, "");
+        this.token = token;
+        this.fetchImpl = fetchImpl;
+    }
+    /** me returns the authenticated user (GET /auth/me); the whoami by API key. */
+    async me() {
+        return (await this.do("GET", "/api/v1/auth/me")).data;
+    }
+    /** search runs a keyword job search with optional facet filters
+     * (GET /agent/jobs/search). That endpoint runs the same query as the web's
+     * /jobs/search but, for programmatic consumers, replaces the index's truncated
+     * preview with each job's full description — so a host can screen a result set
+     * without a follow-up `job` call per hit. Markdown keeps the posting's lists and
+     * headings intact. params carries the facet query values; q/limit/offset are set here. */
+    async search(query, limit, offset, params) {
+        params.set("q", query);
+        params.set("limit", String(limit));
+        params.set("offset", String(offset));
+        // The endpoint always returns full descriptions, so only the rendering needs
+        // asking for. It used to also send semantic_ratio=0 and include_description=true;
+        // the first died with the hybrid index and the second was never read, and the API
+        // now reports unread params as warnings — so sending them would hand the model two
+        // it cannot act on.
+        params.set("description_format", "markdown");
+        const env = await this.do("GET", `/api/v1/agent/jobs/search?${params.toString()}`);
+        const page = { data: env.data, total: env.meta?.total ?? 0 };
+        if (env.meta?.ignored_params?.length)
+            page.ignored = env.meta.ignored_params;
+        return page;
+    }
+    /** coverage scores a skill list against the facet-filtered market
+     * (POST /market/coverage): skills go in the body, facets in the query string. */
+    async coverage(skills, params) {
+        return withIgnored(await this.do("POST", withQuery("/api/v1/market/coverage", params), { skills }));
+    }
+    /** facets returns the market's facet-value distributions under an optional
+     * filter (GET /jobs/facets): the filter/skill vocabulary with counts. */
+    async facets(params) {
+        return withIgnored(await this.do("GET", withQuery("/api/v1/jobs/facets", params)));
+    }
+    /** recommendations returns open jobs ranked for the caller's CV skills and job
+     * preferences, each with a 0-100 score, reasons and gaps (GET /me/recommendations). */
+    async recommendations(limit, offset, refresh) {
+        const q = new URLSearchParams({ limit: String(limit), offset: String(offset) });
+        if (refresh)
+            q.set("refresh", "1");
+        const env = await this.do("GET", `/api/v1/me/recommendations?${q.toString()}`);
+        return { data: env.data, meta: env.meta };
+    }
+    /** getJob fetches a single job by its public slug (GET /jobs/:slug). */
+    async getJob(slug) {
+        return (await this.do("GET", `/api/v1/jobs/${encodeURIComponent(slug)}`)).data;
+    }
+    /** getCompany fetches a company and its open jobs by slug (GET /companies/:slug). */
+    async getCompany(slug) {
+        return (await this.do("GET", `/api/v1/companies/${encodeURIComponent(slug)}`)).data;
+    }
+    /** apply marks a job applied for the authenticated user (POST /jobs/:slug/apply). */
+    async apply(slug) {
+        return (await this.do("POST", `/api/v1/jobs/${encodeURIComponent(slug)}/apply`)).data;
+    }
+    /** save bookmarks a job (POST /jobs/:slug/save). */
+    async save(slug) {
+        return (await this.do("POST", `/api/v1/jobs/${encodeURIComponent(slug)}/save`)).data;
+    }
+    /** unsave removes a job's bookmark (DELETE /jobs/:slug/save). */
+    async unsave(slug) {
+        return (await this.do("DELETE", `/api/v1/jobs/${encodeURIComponent(slug)}/save`)).data;
+    }
+    /** track sets a job's application stage and/or notes (PATCH /jobs/:slug/track).
+     * An omitted field is left unchanged by the server (partial update). */
+    async track(slug, fields) {
+        return (await this.do("PATCH", `/api/v1/jobs/${encodeURIComponent(slug)}/track`, fields)).data;
+    }
+    /** myJobs lists the caller's tracked jobs (GET /me/tracking), filtered by
+     * all/viewed/saved/applied. */
+    async myJobs(filter, limit, offset) {
+        const q = new URLSearchParams();
+        if (filter)
+            q.set("filter", filter);
+        q.set("limit", String(limit));
+        q.set("offset", String(offset));
+        const env = await this.do("GET", `/api/v1/me/tracking?${q.toString()}`);
+        return { data: env.data, total: env.meta?.total ?? 0 };
+    }
+    /** createJob creates a hand-curated job (POST /jobs, moderator only). Re-creating
+     * the same URL updates the posting (idempotent upsert on the server). */
+    async createJob(params) {
+        return (await this.do("POST", "/api/v1/jobs", params)).data;
+    }
+    /** editJob partially updates a manual job (PATCH /jobs/:slug, moderator only). */
+    async editJob(slug, params) {
+        return (await this.do("PATCH", `/api/v1/jobs/${encodeURIComponent(slug)}`, params)).data;
+    }
+    /** submit queues a vacancy for moderation (POST /submissions). */
+    async submit(params) {
+        return (await this.do("POST", "/api/v1/submissions", params)).data;
+    }
+    /** mySubmissions lists the caller's own submissions with their status
+     * (GET /me/submissions). */
+    async mySubmissions() {
+        return (await this.do("GET", "/api/v1/me/submissions")).data;
+    }
+    /** pendingSubmissions lists the moderator review queue (GET /submissions). */
+    async pendingSubmissions() {
+        return (await this.do("GET", "/api/v1/submissions")).data;
+    }
+    /** approveSubmission approves a pending submission, minting a live job
+     * (POST /submissions/:id/approve, moderator only). */
+    async approveSubmission(id) {
+        return (await this.do("POST", `/api/v1/submissions/${id}/approve`)).data;
+    }
+    /** rejectSubmission rejects a pending submission with an optional reason
+     * (POST /submissions/:id/reject, moderator only). */
+    async rejectSubmission(id, reason) {
+        return (await this.do("POST", `/api/v1/submissions/${id}/reject`, { reason })).data;
+    }
+    // CV-tailoring endpoints (beta-gated on the server), acting as the authenticated
+    // user. Mirrors the freehire CLI's `cv` command group.
+    /** listCVs returns the caller's tailored CVs, newest edit first, each with the vacancy
+     * it was written for (GET /me/cvs). This is where a CV id comes from: every other CV
+     * method takes one, and the id is opaque, so it has to be read rather than constructed. */
+    async listCVs() {
+        return (await this.do("GET", "/api/v1/me/cvs")).data;
+    }
+    /** tailorCV starts (or reopens) tailoring for a vacancy and returns the tailored CV's
+     * id, the base it was copied from, and the bound agent session (POST /me/cvs/tailor).
+     *
+     * Idempotent per vacancy: calling it again for the same slug returns the copy that
+     * already exists rather than making a second one, so it is safe to call when you do not
+     * know whether one exists. It debits an AI credit the first time it creates the copy
+     * (402 when the balance will not cover it) and 409s when the candidate has no résumé to
+     * seed a base CV from. It never calls a model itself. */
+    async tailorCV(jobSlug) {
+        return (await this.do("POST", "/api/v1/me/cvs/tailor", { job_slug: jobSlug })).data;
+    }
+    /** tailorCVContext returns the cached fit-analysis context a tailored CV should
+     * reframe toward — verdict, recommendation, and the missing_have / missing_gap
+     * requirement split (GET /me/cvs/:id/tailor-context). */
+    async tailorCVContext(cvID) {
+        return (await this.do("GET", `${cvPath(cvID)}/tailor-context`)).data;
+    }
+    /** getCV fetches a CV with its full document (GET /me/cvs/:id). */
+    async getCV(cvID) {
+        return (await this.do("GET", cvPath(cvID))).data;
+    }
+    /** patchCV applies a batch of path operations to a CV (PATCH /me/cvs/:id).
+     *
+     * The server decodes the body strictly — unknown fields are rejected — so it has to
+     * be exactly `{ops, note?}`, with each op addressed by a path into the document
+     * (`experience[0].bullets[1]`). Sending a bare patch object is a 422, not a
+     * best-effort apply.
+     *
+     * The whole batch applies or none of it does, and it lands as one entry in the
+     * candidate's revision history, so related edits belong in one call. */
+    async patchCV(cvID, ops, note) {
+        const body = { ops };
+        if (note)
+            body.note = note;
+        return (await this.do("PATCH", cvPath(cvID), body)).data;
+    }
+    /** renderCV downloads a CV rendered to PDF (GET /me/cvs/:id/pdf). Unlike the other
+     * endpoints this returns raw PDF bytes, not the JSON envelope, so it bypasses do(). */
+    async renderCV(cvID) {
+        const resp = await this.fetchImpl(this.baseURL + `${cvPath(cvID)}/pdf`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${this.token}`, Accept: "application/pdf" },
+        });
+        const buf = new Uint8Array(await resp.arrayBuffer());
+        if (!resp.ok) {
+            let message = "";
+            try {
+                message = JSON.parse(Buffer.from(buf).toString("utf8")).error ?? "";
+            }
+            catch {
+                // A non-JSON error body just leaves the message empty; the status still carries.
+            }
+            throw new ApiError(resp.status, message);
+        }
+        return buf;
+    }
+    /** listExperience returns the caller's whole bank, grouped by employment
+     * (GET /me/experience). Achievements attached to no place come back under `unplaced`.
+     *
+     * This is where an `evidence_id` for patchCV comes from — without it the honest wall
+     * has no key, since every claim about the candidate has to cite a banked achievement. */
+    async listExperience() {
+        return (await this.do("GET", "/api/v1/me/experience")).data;
+    }
+    /** addEmployment records a place evidence was produced — a job or a project
+     * (POST /me/experience/employments). */
+    async addEmployment(params) {
+        return (await this.do("POST", "/api/v1/me/experience/employments", params)).data;
+    }
+    /** addAchievement records one piece of evidence (POST /me/experience/atoms).
+     *
+     * Provenance is not a parameter: the server stamps a POST-created achievement `manual`
+     * whatever is sent, because there is no transcript behind a plain HTTP call to check a
+     * stronger claim against. A claim already in the bank, under any spelling, comes back
+     * as 409 rather than a duplicate row — which is why correcting one matters. */
+    async addAchievement(params) {
+        return (await this.do("POST", "/api/v1/me/experience/atoms", params)).data;
+    }
+    /** updateEmployment corrects a banked place (PUT /me/experience/employments/:id).
+     *
+     * The API REPLACES the whole row, so this reads the bank first and sends it back with
+     * only the named fields changed. Passing the caller's fields straight through would
+     * write empty over everything they did not mention. */
+    async updateEmployment(id, changes) {
+        const current = await this.findEmployment(id);
+        const body = { ...current, ...definedOnly(changes) };
+        return (await this.do("PUT", `/api/v1/me/experience/employments/${encodeURIComponent(id)}`, body)).data;
+    }
+    /** updateAchievement corrects a banked achievement (PUT /me/experience/atoms/:id), with
+     * the same read-then-replace care as updateEmployment — a claim-only fix must not delete
+     * the metrics and skills that made the achievement worth citing.
+     *
+     * A keyed correction does NOT move the claim's provenance: the server keeps whatever the
+     * row already carried, so an agent cannot promote its own inference into something
+     * citable on a CV. Only the candidate's own edit on the site stamps `manual`. */
+    async updateAchievement(id, changes) {
+        const current = await this.findAchievement(id);
+        const body = { ...current, ...definedOnly(changes) };
+        return (await this.do("PUT", `/api/v1/me/experience/atoms/${encodeURIComponent(id)}`, body)).data;
+    }
+    /** removeAchievement deletes one owned achievement (DELETE /me/experience/atoms/:id).
+     * It takes nothing else with it, and there is no undo. */
+    async removeAchievement(id) {
+        await this.do("DELETE", `/api/v1/me/experience/atoms/${encodeURIComponent(id)}`);
+        return { removed: id };
+    }
+    /** removeEmployment deletes one owned place (DELETE /me/experience/employments/:id).
+     *
+     * The server refuses this with 409 while achievements still hang off the place, because
+     * the row's foreign key cascades and would delete them too. Move them with
+     * updateAchievement first, then remove the empty place. */
+    async removeEmployment(id) {
+        await this.do("DELETE", `/api/v1/me/experience/employments/${encodeURIComponent(id)}`);
+        return { removed: id };
+    }
+    /** findEmployment reads one banked place, so an update can replace the row without
+     * losing what the caller did not name. A missing id fails here rather than being sent
+     * as a write the server would refuse anyway. */
+    async findEmployment(id) {
+        const bank = (await this.listExperience());
+        const found = (bank?.employments ?? []).find((e) => e.id === id);
+        if (!found) {
+            throw new ApiError(404, `no employment ${id} in your bank — read experience_list for the ids`);
+        }
+        return {
+            kind: found.kind,
+            // A project's label is served under `name`; a job's under `company`. Both map to the
+            // same stored field, and the server picks by kind on the way back in.
+            company: found.company ?? found.name,
+            role: found.role,
+            location: found.location,
+            start: found.start,
+            end: found.end,
+            current: found.current,
+            summary: found.summary,
+            stack: found.stack,
+            link: found.link,
+        };
+    }
+    async findAchievement(id) {
+        const bank = (await this.listExperience());
+        for (const e of bank?.employments ?? []) {
+            const hit = (e.atoms ?? []).find((a) => a.id === id);
+            // The grouping is the authority on which place an achievement belongs to, so the
+            // employment id comes from the group rather than the row.
+            if (hit)
+                return { ...achievementFields(hit), employment_id: e.id };
+        }
+        const loose = (bank?.unplaced ?? []).find((a) => a.id === id);
+        if (loose)
+            return achievementFields(loose);
+        throw new ApiError(404, `no achievement ${id} in your bank — read experience_list for the ids`);
+    }
+    async mailboxStatus() {
+        return (await this.do("GET", "/api/v1/me/mailbox")).data;
+    }
+    async mailConversations(folder, q) {
+        const params = new URLSearchParams();
+        if (folder)
+            params.set("folder", folder);
+        if (q)
+            params.set("q", q);
+        return (await this.do("GET", withQuery("/api/v1/me/mail/conversations", params))).data;
+    }
+    async mailThread(id) {
+        const params = new URLSearchParams({ id });
+        return (await this.do("GET", withQuery("/api/v1/me/mail/thread", params))).data;
+    }
+    async mailReplyDraft(threadId, instruction) {
+        return (await this.do("POST", "/api/v1/me/mail/thread/reply-draft", {
+            thread_id: threadId,
+            instruction,
+        })).data;
+    }
+    async mailReply(threadId, body, idempotencyKey) {
+        return (await this.do("POST", "/api/v1/me/mail/reply", {
+            thread_id: threadId,
+            body,
+            idempotency_key: idempotencyKey,
+        })).data;
+    }
+    async mailLink(threadId, applicationId) {
+        return (await this.do("POST", "/api/v1/me/mail/thread/link", {
+            thread_id: threadId,
+            application_id: applicationId,
+        })).data;
+    }
+    async do(method, path, body) {
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            Accept: "application/json",
+        };
+        let payload;
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            payload = JSON.stringify(body);
+        }
+        const resp = await this.fetchImpl(this.baseURL + path, { method, headers, body: payload });
+        const text = await resp.text();
+        let env = {};
+        if (text.length > 0) {
+            try {
+                env = JSON.parse(text);
+            }
+            catch (err) {
+                // A malformed body on a 2xx is unexpected; surface it. On a non-2xx an
+                // unparseable body just leaves env.error empty (the status still carries).
+                if (resp.ok)
+                    throw new Error(`decode response: ${err.message}`);
+            }
+        }
+        if (!resp.ok)
+            throw new ApiError(resp.status, env.error ?? "");
+        return env;
+    }
+}
+/** withQuery appends the encoded params to path, omitting the "?" when empty. */
+function withQuery(path, params) {
+    const enc = params.toString();
+    return enc ? `${path}?${enc}` : path;
+}
+/** cvPath is the base API path for a tailored CV by id. */
+function cvPath(cvID) {
+    return `/api/v1/me/cvs/${encodeURIComponent(cvID)}`;
+}
+function achievementFields(a) {
+    return { claim: a.claim, context: a.context, metrics: a.metrics, skills: a.skills };
+}
+/** definedOnly drops undefined entries so a spread of caller-supplied changes leaves the
+ * banked value in place instead of overwriting it with undefined. */
+function definedOnly(o) {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+}
+/** withIgnored returns an envelope's `data`, wrapped as `{data, ignored}` when the
+ * API reported params it did not read.
+ *
+ * Wrapped only then: these endpoints answer a single object, and hosts already
+ * parse it directly, so a permanent wrapper would be churn on every clean call.
+ * The warning has to travel in the payload — a count or a coverage percentage
+ * computed under a dropped filter reads exactly as authoritative as a real one. */
+function withIgnored(env) {
+    const ignored = env.meta?.ignored_params;
+    if (!ignored?.length)
+        return env.data;
+    return { data: env.data, ignored };
+}

package/dist/config.js

@@ -0,0 +1,58 @@
+// Resolves and reads the Findyet credentials: the API token and base URL.
+// Precedence: environment variable (FINDYET_*, then the upstream FREEHIRE_* names, which
+// keep working) > ~/.findyet/creds.json > ~/.freehire/creds.json (written by the upstream
+// CLI) > built-in default, the production Findyet API.
+// The MCP server only reads the credentials file.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** DEFAULT_API_URL is the production API base when none is configured. */
+export const DEFAULT_API_URL = "https://findyet.devjoys.com";
+/** Environment variables that override the stored credentials. */
+export const ENV_TOKEN = "FINDYET_TOKEN";
+export const ENV_API_URL = "FINDYET_API_URL";
+/** The upstream variable names, still honoured so existing configurations keep working. */
+export const LEGACY_ENV_TOKEN = "FREEHIRE_TOKEN";
+export const LEGACY_ENV_API_URL = "FREEHIRE_API_URL";
+/** NotAuthenticatedError is thrown by resolveConfig when no token is configured. */
+export class NotAuthenticatedError extends Error {
+    constructor() {
+        super("not authenticated: set FINDYET_TOKEN (create an API key in Findyet: account menu → API keys)");
+        this.name = "NotAuthenticatedError";
+    }
+}
+/** credsPath returns Findyet's credentials file path (~/.findyet/creds.json). */
+export function credsPath() {
+    return path.join(os.homedir(), ".findyet", "creds.json");
+}
+/** legacyCredsPath is the upstream CLI's credentials file, read when Findyet's is absent. */
+export function legacyCredsPath() {
+    return path.join(os.homedir(), ".freehire", "creds.json");
+}
+/** loadCreds reads the first credentials file that exists; none yields empty creds. */
+export function loadCreds() {
+    for (const file of [credsPath(), legacyCredsPath()]) {
+        try {
+            return JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                continue;
+            throw err;
+        }
+    }
+    return {};
+}
+/**
+ * resolveConfig computes the effective token and API URL with precedence
+ * env > creds file > default. The token is required (else NotAuthenticatedError);
+ * the URL falls back to DEFAULT_API_URL.
+ */
+export function resolveConfig(env = process.env) {
+    const creds = loadCreds();
+    const token = env[ENV_TOKEN] || env[LEGACY_ENV_TOKEN] || creds.token || "";
+    if (!token)
+        throw new NotAuthenticatedError();
+    const apiURL = env[ENV_API_URL] || env[LEGACY_ENV_API_URL] || creds.api_url || DEFAULT_API_URL;
+    return { token, apiURL };
+}

package/dist/facets.js

@@ -0,0 +1,92 @@
+// The shared market-filter surface for the search, market_fit, and facets tools.
+// Mirrors the freehire CLI's facet flags: named convenience filters for the
+// high-traffic facets plus a generic `facets` escape hatch for the long tail.
+import { z } from "zod";
+/** marketFacetShape is a Zod raw shape spread into the input schema of every tool
+ * that filters the market. Each named facet maps to an API query param; `facets`
+ * reaches any other param in the vocabulary. */
+export const marketFacetShape = {
+    remote: z.boolean().optional().describe("Only remote jobs (sets work_mode=remote)."),
+    region: z
+        .array(z.string())
+        .optional()
+        .describe("Region codes: global|ru|cis|central_asia|eu|us. WIDENS with country/city — " +
+        "region+country means 'in the region OR the country', not 'the country inside " +
+        "the region'. To search one country, pass country and OMIT region."),
+    country: z
+        .array(z.string())
+        .optional()
+        .describe("ISO-3166 country codes, e.g. BR, US. Omit `region` when narrowing to a country — " +
+        "the two OR together, so region+country returns everything the region alone would."),
+    city: z.array(z.string()).optional().describe("City slugs. ORs with region and country."),
+    company: z.array(z.string()).optional().describe("Company slugs."),
+    category: z
+        .array(z.string())
+        .optional()
+        .describe("Role categories: backend|frontend|fullstack|devops|ml_ai|qa|..."),
+    role: z.array(z.string()).optional().describe("Role facet values, e.g. senior_backend."),
+    seniority: z
+        .array(z.string())
+        .optional()
+        .describe("Seniority: intern|junior|middle|senior|staff|principal|lead|c_level."),
+    employment_type: z
+        .array(z.string())
+        .optional()
+        .describe("Employment type, e.g. full_time, contract."),
+    english_level: z.array(z.string()).optional().describe("English level, e.g. a2, b1, b2, c1."),
+    exclude_skill: z
+        .array(z.string())
+        .optional()
+        .describe("Skills to filter OUT, e.g. python — drops jobs TAGGED with any of them. Tags come " +
+        "from a curated dictionary read off the description, so this is a discovery filter, " +
+        "not a fit test: a mention the dictionary does not recognise leaves the job untagged " +
+        "and in the results, and a job whose real core is a stack the candidate lacks is not " +
+        'removed by excluding a different one. Any other facet excludes the same way through ' +
+        '`facets`, e.g. {"company_type_exclude": "outstaff"}.'),
+    salary_min: z.number().int().min(0).optional().describe("Minimum salary (enrichment.salary_min)."),
+    visa: z.boolean().optional().describe("Only jobs offering visa sponsorship."),
+    facets: z
+        .record(z.string(), z.union([z.string(), z.array(z.string())]))
+        .optional()
+        .describe('Any other facet param as key→value(s), e.g. {"source": "greenhouse"}. ' +
+        "Discover valid keys and values with the `facets` tool."),
+};
+/** namedFacets binds each convenience filter to the API facet param it fills. */
+const namedFacets = {
+    region: "regions",
+    country: "countries",
+    city: "cities",
+    company: "company_slug",
+    category: "category",
+    role: "role",
+    seniority: "seniority",
+    employment_type: "employment_type",
+    english_level: "english_level",
+    exclude_skill: "skills_exclude",
+};
+/** buildFacetParams collects the shared market-filter inputs into API query params. */
+export function buildFacetParams(f) {
+    const q = new URLSearchParams();
+    for (const [key, param] of Object.entries(namedFacets)) {
+        const vals = f[key];
+        if (vals)
+            for (const v of vals)
+                q.append(param, v);
+    }
+    if (f.remote)
+        q.set("work_mode", "remote");
+    if (f.salary_min && f.salary_min > 0)
+        q.set("salary_min", String(f.salary_min));
+    if (f.visa)
+        q.set("visa_sponsorship", "true");
+    if (f.facets) {
+        for (const [k, v] of Object.entries(f.facets)) {
+            if (Array.isArray(v))
+                for (const x of v)
+                    q.append(k, x);
+            else
+                q.append(k, v);
+        }
+    }
+    return q;
+}

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// findyet-mcp (forked from freehire-mcp) — an MCP server over the Findyet job API. The host (Claude Desktop,
+// Claude Code, …) launches this binary over stdio; it exposes the freehire API as
+// tools, authenticating with a personal API key resolved from the environment or
+// the freehire CLI's credentials file.
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Client } from "./client.js";
+import { resolveConfig } from "./config.js";
+import { registerTools } from "./tools.js";
+import { VERSION } from "./version.js";
+/** makeClientResolver returns a getClient that resolves the config once and caches
+ * the client. It resolves lazily (on first tool call, not at launch) so a missing
+ * token surfaces as a tool error instead of a failed server start — and a token
+ * added after launch is still picked up on the next attempt. */
+function makeClientResolver() {
+    let cached = null;
+    return () => {
+        if (cached)
+            return cached;
+        const { token, apiURL } = resolveConfig(process.env);
+        cached = new Client(apiURL, token);
+        return cached;
+    };
+}
+async function main() {
+    const server = new McpServer({ name: "findyet", version: VERSION }, {
+        instructions: "Tools over the Findyet job API (a local Findyet instance by default). Start with `facets` to discover real filter values and skill slugs, " +
+            "then `search`. Address jobs by their public_slug. Use `recommendations` for jobs ranked against the user's own CV and preferences, and `market_fit` to measure skills against demand.",
+    });
+    registerTools(server, makeClientResolver());
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("findyet-mcp: fatal:", err);
+    process.exit(1);
+});

package/dist/tools.js

@@ -0,0 +1,408 @@
+// Registers the Findyet tools on an McpServer. Each tool is a thin wrapper over a
+// client method: it returns the raw API `data` as JSON text, and an API failure
+// becomes an isError result (so the agent sees the status, not a crash).
+import { z } from "zod";
+import { ApiError } from "./client.js";
+import { buildFacetParams, marketFacetShape } from "./facets.js";
+/** ok serializes API data as pretty JSON text — faithful to the API for the agent. */
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+/** fail turns an error into an isError result, adding an auth hint on a 401. */
+function fail(err) {
+    let msg = err instanceof Error ? err.message : String(err);
+    if (err instanceof ApiError && err.status === 401) {
+        msg += " (set FINDYET_TOKEN to an API key created in Findyet)";
+    }
+    return { content: [{ type: "text", text: msg }], isError: true };
+}
+/** run executes a client call, mapping success/failure to a tool result. */
+async function run(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (err) {
+        return fail(err);
+    }
+}
+const slug = z.string().min(1).describe("The job's public slug (from search or facets results).");
+/** registerTools wires every Findyet tool onto server, resolving the client lazily
+ * through getClient on each call. */
+export function registerTools(server, getClient) {
+    server.registerTool("whoami", {
+        description: "Return the authenticated Findyet user (verifies the API key). Call this to confirm auth before other tools.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => run(() => getClient().me()));
+    server.registerTool("facets", {
+        description: "List the market's filter vocabulary: every facet's live values with a vacancy count each, plus the skills list and numeric ranges. Call this FIRST to discover real values for `search` and `market_fit` — do not invent facet values. A filter key the API does not recognise is ignored rather than refused, so a result wrapped as {data, ignored} counted a broader market than the one asked for — retry with the suggested name before quoting any number from it.",
+        inputSchema: { ...marketFacetShape },
+        annotations: { readOnlyHint: true },
+    }, async (input) => run(() => getClient().facets(buildFacetParams(input))));
+    server.registerTool("search", {
+        description: "Search open jobs by keyword with optional facet filters. Each result carries the job's FULL description as markdown alongside title, company, location and public_slug, plus the total match count — so you can screen a whole result set without calling `job` per hit. Use the returned slug with `job`, `apply`, `save`, etc. " +
+            "Two traps worth knowing. Geography (region/country/city) is ONE OR-group: passing region AND country widens rather than narrows, so drop the region to search a single country. And a filter param the API does not recognize is ignored rather than refused — the search still runs, just broader — so when a result carries an `ignored` list, its `total` answers a wider question than the one asked; retry with the suggested name before reporting the number.",
+        inputSchema: {
+            query: z.string().describe("Keyword query, e.g. 'golang backend'. Empty string matches all."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Max results to return. Each result includes a full job description, so prefer a modest value."),
+            offset: z.number().int().min(0).default(0).describe("Pagination offset."),
+            skills: z
+                .array(z.string())
+                .optional()
+                .describe("Filter to jobs listing these skills (canonical slugs from the `facets` tool)."),
+            ...marketFacetShape,
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ query, limit, offset, skills, ...facets }) => {
+        const params = buildFacetParams(facets);
+        if (skills)
+            for (const s of skills)
+                params.append("skills", s);
+        return run(() => getClient().search(query, limit, offset, params));
+    });
+    server.registerTool("market_fit", {
+        description: "Score a skill list against the live open-vacancy market for a filtered role: headline coverage (% of vacancies listing ≥1 skill), must-have skills held, and the missing skills that unlock the most vacancies. Here `skills` is the MEASURED set, not a filter — use facet params to define the role. One skill probes that skill's demand.",
+        inputSchema: {
+            skills: z
+                .array(z.string())
+                .min(1)
+                .describe("The candidate's skills to measure (canonical slugs). One value probes a single skill."),
+            ...marketFacetShape,
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ skills, ...facets }) => run(() => getClient().coverage(skills, buildFacetParams(facets))));
+    server.registerTool("recommendations", {
+        description: "Personalized job recommendations for the authenticated user, computed from their Findyet profile/CV skills, seniority and location/work-mode preferences. Each item has the job, a 0-100 `score`, `reasons` (why it fits) and `gaps` (what to check), as codes with params. `meta.state` explains an empty feed (no_profile, no_skills). Dismissed and applied jobs are excluded.",
+        inputSchema: {
+            limit: z.number().int().min(1).max(50).default(10).describe("How many recommendations to return."),
+            offset: z.number().int().min(0).default(0).describe("Pagination offset."),
+            refresh: z.boolean().default(false).describe("Recompute instead of using the server's short-lived cache."),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ limit, offset, refresh }) => run(() => getClient().recommendations(limit, offset, refresh)));
+    server.registerTool("job", {
+        description: "Fetch a single job's full content by slug (title, company, location, posting URL, description).",
+        inputSchema: { slug },
+        annotations: { readOnlyHint: true },
+    }, async ({ slug }) => run(() => getClient().getJob(slug)));
+    server.registerTool("company", {
+        description: "Fetch a company and its open jobs by company slug.",
+        inputSchema: { slug: z.string().min(1).describe("The company slug (from a job's company_slug).") },
+        annotations: { readOnlyHint: true },
+    }, async ({ slug }) => run(() => getClient().getCompany(slug)));
+    server.registerTool("apply", {
+        description: "Mark a job as applied for the authenticated user. Idempotent.",
+        inputSchema: { slug },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ slug }) => run(() => getClient().apply(slug)));
+    server.registerTool("save", {
+        description: "Bookmark a job for later. Idempotent.",
+        inputSchema: { slug },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ slug }) => run(() => getClient().save(slug)));
+    server.registerTool("unsave", {
+        description: "Remove a job's bookmark. A no-op if it was not saved.",
+        inputSchema: { slug },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ slug }) => run(() => getClient().unsave(slug)));
+    server.registerTool("stage", {
+        description: "Set a job's application stage. The server validates the value; valid stages are applied/screening/responded/interview/offer/accepted/rejected/withdrawn.",
+        inputSchema: {
+            slug,
+            stage: z.string().min(1).describe("Application stage, e.g. interview, offer, rejected."),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ slug, stage }) => run(() => getClient().track(slug, { stage })));
+    server.registerTool("note", {
+        description: "Attach a free-text note to a tracked job (overwrites the existing note).",
+        inputSchema: {
+            slug,
+            note: z.string().describe("Free-text note to store on the job."),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ slug, note }) => run(() => getClient().track(slug, { notes: note })));
+    server.registerTool("my", {
+        description: "List the caller's tracked jobs (viewed/saved/applied) with their stage and note. Filter narrows the set.",
+        inputSchema: {
+            filter: z
+                .enum(["all", "viewed", "saved", "applied"])
+                .default("all")
+                .describe("Which tracked jobs to list."),
+            limit: z.number().int().min(1).max(100).default(20),
+            offset: z.number().int().min(0).default(0),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ filter, limit, offset }) => run(() => getClient().myJobs(filter, limit, offset)));
+    // CV tailoring — read the fit context, read/patch the CV document, render a PDF.
+    // Beta-gated on the server; acts as the authenticated user. Addressed by CV id.
+    // The id is opaque: the API hands it out and the caller passes it back. The schema
+    // deliberately does not describe its format — a client that validates the shape
+    // bakes today's format into a released package, which is what an opaque id avoids.
+    const cvId = z
+        .string()
+        .min(1)
+        .describe("The CV id, from cv_tailor or cv_list (or the tailoring workspace URL /tailor/<job>?cv=<id>). Opaque — never construct or guess one.");
+    // The two entry points. Every other CV tool takes an id, so without these the cycle can
+    // be driven but not started.
+    server.registerTool("cv_list", {
+        description: "List the caller's tailored CVs, newest edit first, each with the vacancy it was written for. Use this to find the id the other cv_* tools take, or to check whether a vacancy already has a tailored copy.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => run(() => getClient().listCVs()));
+    server.registerTool("cv_tailor", {
+        description: "Start tailoring a CV to a vacancy, returning the tailored CV's id (plus the base it was copied from and the bound session). Idempotent per vacancy — calling it again for the same slug reopens the copy that already exists, so it is safe when you do not know whether one exists. It spends one of the candidate's AI credits the first time it creates the copy (402 when the balance will not cover it) and 409s when they have no résumé on the site to seed a base CV from — tell them to upload one; you cannot. It does not call a model: the reframing is your work, through cv_context and cv_edit.",
+        inputSchema: { job_slug: slug },
+        annotations: { readOnlyHint: false },
+    }, async ({ job_slug }) => run(() => getClient().tailorCV(job_slug)));
+    server.registerTool("cv_context", {
+        description: "Show the cached fit-analysis context a tailored CV should reframe toward: verdict, recommendation, dimension comments, and the requirement split — missing_have (reframe existing evidence) vs missing_gap (ask the candidate before adding). Read this before editing.",
+        inputSchema: { id: cvId },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => run(() => getClient().tailorCVContext(id)));
+    server.registerTool("cv_get", {
+        description: "Fetch a tailored CV with its full document (header, summary, experience bullets, skill groups).",
+        inputSchema: { id: cvId },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => run(() => getClient().getCV(id)));
+    // Edits are addressed by a path into the document, the same model the CLI and the web
+    // editor use. Send everything that belongs together in ONE call: the batch is atomic
+    // and lands as a single, individually undoable entry in the candidate's history.
+    const cvOp = z
+        .object({
+        kind: z
+            .enum(["set", "insert", "remove", "move"])
+            .describe("set replaces a node, insert adds one, remove deletes one, move reorders within its list."),
+        path: z
+            .string()
+            .min(1)
+            .describe("Where to edit, 0-indexed over what cv_get returned: summary, experience[2].bullets[1], experience[0].stack[0], skills[0].items[3], education[1].degree, style.font_size."),
+        value: z.unknown().optional().describe("The new content. Omit for remove and move."),
+        to: z.number().int().optional().describe("Destination index. Only for move."),
+        evidence_id: z
+            .string()
+            .optional()
+            .describe("Id of the banked achievement backing this claim. Required for anything stating what the candidate did."),
+    })
+        .describe("One path-addressed operation.");
+    server.registerTool("cv_edit", {
+        description: "Apply a batch of path-addressed edits to a tailored CV, atomically. Read cv_context and cv_get first — indices are counted over the document cv_get returned. THE HONEST WALL: editing with an API key edits as the tailoring agent, and the server enforces it — the candidate's own name, email, phone and links are refused, and anything stating what they DID needs evidence_id, the id of something they asserted themselves. One uncited op rejects the whole batch. For a missing_have requirement, reframe an existing bullet; for a missing_gap, ask the candidate before writing anything. A bad path is a 422 and the CV is untouched. Export with cv_render.",
+        inputSchema: {
+            id: cvId,
+            ops: z.array(cvOp).min(1).describe("Every edit that belongs together, in one call."),
+            note: z
+                .string()
+                .optional()
+                .describe("Your own one-line reason for the change; shown to the candidate as the agent's words."),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ id, ops, note }) => run(() => getClient().patchCV(id, ops, note)));
+    server.registerTool("cv_render", {
+        description: "Render a tailored CV to an ATS PDF, returned as a base64 resource (application/pdf). The bytes are large and not human-readable to the model — call it to produce the deliverable, not to inspect content.",
+        inputSchema: { id: cvId },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, async ({ id }) => {
+        try {
+            const pdf = await getClient().renderCV(id);
+            return {
+                content: [
+                    {
+                        type: "resource",
+                        resource: {
+                            uri: `cv://${id}.pdf`,
+                            mimeType: "application/pdf",
+                            blob: Buffer.from(pdf).toString("base64"),
+                        },
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+    // The experience bank is the durable record of what the candidate has actually done, and
+    // it is what cv_edit's evidence_id points into. Without these tools the honest wall has
+    // no key: every claim about the candidate needs a citation and there would be no way to
+    // obtain one.
+    const employmentId = z
+        .string()
+        .min(1)
+        .describe("The employment id, from experience_list. Opaque — read it, never construct one.");
+    const achievementId = z
+        .string()
+        .min(1)
+        .describe("The achievement id, from experience_list. This is also cv_edit's evidence_id.");
+    server.registerTool("experience_list", {
+        description: "Read the candidate's whole experience bank: every employment and the achievements attached to it, plus the ones attached to no place under `unplaced`. Each achievement carries a PROVENANCE — cv_import, stated_in_chat and manual mean the candidate asserted it and it may be cited on a CV; agent_inferred means a model read it into the record and it may NOT. Take evidence_id for cv_edit from here.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => run(() => getClient().listExperience()));
+    const employmentShape = {
+        kind: z.enum(["job", "project"]).optional().describe('"job" or "project"; defaults to job on create.'),
+        company: z.string().optional().describe("Company name, or the project's name."),
+        role: z.string().optional().describe("The candidate's title or role there."),
+        location: z.string().optional().describe("Free-text location."),
+        start: z.string().optional().describe('A free-form date as it would be printed, e.g. "Mar 2021".'),
+        end: z.string().optional().describe("Same format as start; omit while ongoing."),
+        current: z.boolean().optional().describe("True while the candidate is still there."),
+        summary: z.string().optional().describe("One line about the place, for context."),
+    };
+    server.registerTool("experience_add_employment", {
+        description: "Record a place where evidence was produced — a job or a side project. At least company or role is required. Use the returned id to attach achievements with experience_add_achievement.",
+        inputSchema: employmentShape,
+        annotations: { readOnlyHint: false },
+    }, async (input) => run(() => getClient().addEmployment(input)));
+    server.registerTool("experience_add_achievement", {
+        description: "Record one piece of evidence — the sentence a CV bullet would carry. Only record what the CANDIDATE told you; the server stamps anything created here `manual`, which means they asserted it, and that stamp is what lets it be cited on a CV. A claim already in the bank, under any spelling, is refused as 409 rather than duplicated — so correct the existing one with experience_update_achievement instead of re-adding it.",
+        inputSchema: {
+            claim: z.string().min(1).describe("The achievement as one CV-bullet-grade sentence."),
+            context: z.string().optional().describe("How it was done, in a sentence or two."),
+            metrics: z.array(z.string()).optional().describe('Numbers as stated, e.g. ["20s->1s"].'),
+            skills: z.array(z.string()).optional().describe('Canonical skill slugs, e.g. ["go", "kubernetes"].'),
+            employment_id: employmentId.optional().describe("The place this belongs to; omit to leave it unplaced."),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (input) => run(() => getClient().addAchievement(input)));
+    server.registerTool("experience_update_employment", {
+        description: "Correct a place already in the bank. Only the fields you pass change — everything else is carried over from what is banked, because the API replaces the whole row. Use this to fix a name, a role, or dates.",
+        inputSchema: { id: employmentId, ...employmentShape },
+        annotations: { readOnlyHint: false },
+    }, async ({ id, ...changes }) => run(() => getClient().updateEmployment(id, changes)));
+    server.registerTool("experience_update_achievement", {
+        description: "Correct an achievement already in the bank — most often a typo in the claim, which cannot be fixed by re-adding it. Only the fields you pass change; metrics and skills REPLACE the whole list when given. Correcting does NOT change who is held to have said it: an agent_inferred achievement stays agent_inferred and stays uncitable on a CV. Confirming it with the candidate then recording what THEY said is the only way it becomes citable.",
+        inputSchema: {
+            id: achievementId,
+            claim: z.string().optional().describe("The corrected sentence."),
+            context: z.string().optional().describe("How it was done."),
+            metrics: z.array(z.string()).optional().describe("Replaces the whole metrics list."),
+            skills: z.array(z.string()).optional().describe("Replaces the whole skills list."),
+            employment_id: employmentId.optional().describe("Move it to this place."),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ id, ...changes }) => run(() => getClient().updateAchievement(id, changes)));
+    server.registerTool("experience_remove_achievement", {
+        description: "Delete one achievement from the bank. There is no undo, so confirm with the candidate first — read it back to them and remove it only on a clear yes. It takes nothing else with it. This is how a duplicate goes: keep the richer entry, remove the other.",
+        inputSchema: { id: achievementId },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ id }) => run(() => getClient().removeAchievement(id)));
+    server.registerTool("experience_remove_employment", {
+        description: "Delete a place from the bank. It must hold no achievements — removing a place would delete everything recorded under it, and the server refuses that here (409). To retire a duplicate place, move its achievements to the one being kept with experience_update_achievement, then remove the empty shell. There is no undo; confirm with the candidate first.",
+        inputSchema: { id: employmentId },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async ({ id }) => run(() => getClient().removeEmployment(id)));
+    server.registerTool("submit", {
+        description: "Submit a vacancy for moderation. The server stores it as pending and returns it. URL (the dedup key), title, and company are required.",
+        inputSchema: createJobShape(),
+        annotations: { readOnlyHint: false },
+    }, async (input) => run(() => getClient().submit(input)));
+    server.registerTool("my_submissions", {
+        description: "List the caller's own vacancy submissions with their moderation status.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => run(() => getClient().mySubmissions()));
+    // Moderator-only tools. A regular API key gets a 403 (surfaced as isError).
+    server.registerTool("jobs_add", {
+        description: "Moderator: create a hand-curated job. URL is the dedup key — re-adding the same URL updates the posting. `description` is stored and rendered as HTML. Requires the moderator role (403 otherwise).",
+        inputSchema: createJobShape(),
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async (input) => run(() => getClient().createJob(input)));
+    server.registerTool("jobs_edit", {
+        description: "Moderator: partially update a manual job by slug. Only the provided fields change; the URL identity is not editable. Requires the moderator role (403 otherwise).",
+        inputSchema: {
+            slug,
+            title: z.string().optional(),
+            company: z.string().optional(),
+            location: z.string().optional(),
+            remote: z.boolean().optional(),
+            description: z.string().optional().describe("Stored and rendered as HTML."),
+            posted_at: z.string().optional().describe("RFC3339 timestamp."),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ slug, ...params }) => run(() => getClient().editJob(slug, params)));
+    server.registerTool("submissions_pending", {
+        description: "Moderator: list the pending submission review queue. Requires the moderator role (403 otherwise).",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => run(() => getClient().pendingSubmissions()));
+    server.registerTool("submission_approve", {
+        description: "Moderator: approve a pending submission, minting a live job. Requires the moderator role (403 otherwise).",
+        inputSchema: { id: z.number().int().describe("The submission id.") },
+        annotations: { readOnlyHint: false },
+    }, async ({ id }) => run(() => getClient().approveSubmission(id)));
+    server.registerTool("submission_reject", {
+        description: "Moderator: reject a pending submission with an optional reason. Requires the moderator role (403 otherwise).",
+        inputSchema: {
+            id: z.number().int().describe("The submission id."),
+            reason: z.string().default("").describe("Optional rejection reason."),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ id, reason }) => run(() => getClient().rejectSubmission(id, reason)));
+    server.registerTool("mail_mailbox_status", {
+        description: "Read the signed-in user's Findyet mailbox: whether it is claimed, the address, and whether delivery is local testing or external. Does not create an alias.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => run(() => getClient().mailboxStatus()));
+    server.registerTool("mail_conversations_list", {
+        description: "List the signed-in user's Findyet Mail conversations. folder is inbox, archived, sent, or all.",
+        inputSchema: {
+            folder: z.enum(["inbox", "archived", "sent", "all"]).default("inbox"),
+            q: z.string().default(""),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ folder, q }) => run(() => getClient().mailConversations(folder, q)));
+    server.registerTool("mail_thread_read", {
+        description: "Read one Findyet Mail thread, including messages and attachment metadata. Marks it read.",
+        inputSchema: { thread_id: z.string().min(1) },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ thread_id }) => run(() => getClient().mailThread(thread_id)));
+    server.registerTool("mail_reply_draft", {
+        description: "Ask AI for a reply draft. This never sends mail. The draft is returned for the user to edit and confirm.",
+        inputSchema: {
+            thread_id: z.string().min(1),
+            instruction: z.string().default(""),
+        },
+        annotations: { readOnlyHint: true },
+    }, async ({ thread_id, instruction }) => run(() => getClient().mailReplyDraft(thread_id, instruction)));
+    server.registerTool("mail_reply", {
+        description: "Send a reply from the claimed Findyet mailbox, or from the alias already on a historical thread. Requires confirm: true. Local development captures the message in Mailpit; it is not delivered on the public internet.",
+        inputSchema: {
+            thread_id: z.string().min(1),
+            body: z.string().min(1),
+            idempotency_key: z.string().min(1),
+            confirm: z.literal(true).describe("Must be true. The tool does not send without this explicit authorization."),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ thread_id, body, idempotency_key, confirm }) => {
+        if (confirm !== true) {
+            return fail(new Error("explicit confirm: true is required before sending"));
+        }
+        return run(() => getClient().mailReply(thread_id, body, idempotency_key));
+    });
+    server.registerTool("mail_link", {
+        description: "Link a Findyet Mail conversation to one of the user's tracked applications. Does not change the application stage.",
+        inputSchema: {
+            thread_id: z.string().min(1),
+            application_id: z.number().int(),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true },
+    }, async ({ thread_id, application_id }) => run(() => getClient().mailLink(thread_id, application_id)));
+}
+/** createJobShape is the shared input schema for `submit` and `jobs_add`. */
+function createJobShape() {
+    return {
+        url: z.string().url().describe("The posting URL — the dedup key. Required."),
+        title: z.string().min(1).describe("Job title. Required."),
+        company: z.string().min(1).describe("Company name. Required."),
+        source: z.string().optional().describe("The posting's real origin (defaults to 'manual' server-side)."),
+        location: z.string().optional(),
+        remote: z.boolean().optional(),
+        description: z.string().optional().describe("Stored and rendered as HTML."),
+        posted_at: z.string().optional().describe("RFC3339 timestamp."),
+    };
+}

package/dist/version.js

@@ -0,0 +1,11 @@
+import { createRequire } from "node:module";
+/** The version the host displays in serverInfo. Read from package.json rather than
+ * written out by hand: this string sat at 0.1.0 through four releases, because
+ * nothing fails when it goes stale.
+ *
+ * `../package.json` resolves from `dist/` in the npm package and from `server/` in
+ * the MCPB bundle alike.
+ *
+ * It lives in its own module so tests can assert on it without importing index.ts,
+ * which starts the stdio server as a side effect of being imported. */
+export const VERSION = createRequire(import.meta.url)("../package.json").version;

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "findyet-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Findyet MCP server: search jobs, get CV-based recommendations, track applications and tailor CVs with your Findyet API key.",
+  "type": "module",
+  "bin": {
+    "findyet-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "build:mcpb": "node scripts/build-mcpb.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "findyet",
+    "jobs",
+    "ats"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.10"
+  },
+  "homepage": "https://findyet.devjoys.com/cli#mcp"
+}