io.github.work0r-ai/workorai

Official29 tools

by work0r-ai · JavaScript

WorkorAI talent marketplace MCP: candidate job search and employer hiring with explainable matching

Talent marketplace MCP for candidate job search and employer hiring with explainable matching.

Topics

agent-skillai-agentantigravity-skillsclaude-skillsclawdbot-skillclawhub-skillcodex-skillgemini-clihermes-skilljob-searchrecruitingtalent-market-research-tooling

Captured live from the server via tools/list.

request_access

Use when someone wants to find work/jobs (candidate) or hire/find candidates (employer) but the authenticated role tools are not usable yet. Explains role-specific onboarding (candidate profile interview, employer key generation), MCP key location, and next steps for both surfaces.

Parameters (1)

rolestring

candidate.search_jobs

Semantically rank published jobs against the authenticated candidate profile (embedding-based fit). Optional tier (best|good|weak) narrows to a match-quality band — start with tier:'best' for the strongest fits and cascade only if needed; omit for the full ranked list (read tierCounts for the band sizes). Each scored row carries matchExplanation (the white-box 'why': fit score, the candidate's skills that match the job's required set, and a rationale). A free-text `q`, or a candidate who has not completed an interview yet, instead browses published jobs by recency — those rows carry NO fit score (`matchScore` is `null`, no bands); treat them as a browse list, not a ranking.

Parameters (8)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
qstring
workModelstring
senioritystring
jobTypestring
limitnumber
offsetnumber
tierstring
Match-quality band. Omit for the full ranked list. START with tier:"best" (strongest fits), cascade to "good"/"weak" only if you need more; read tierCounts to decide. Ignored on a free-text q / no-interview browse (no bands).

candidate.get_job

Fetch a single published job by id.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

candidate.get_applications

List the candidate's own job applications (newest first) with status, dates, the originating interview score, and a job summary. Returns only the caller's applications — no jobId input, so it is not an enumeration surface.

Parameters (1)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.

candidate.set_saved_job

Set whether a PUBLISHED job is in the candidate's saved list (idempotent desired-state, NOT a toggle — pass saved:true to bookmark, saved:false to remove). Returns NOT_FOUND for a missing or non-public job.

Parameters (3)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired
savedbooleanrequired
Desired saved state. true bookmarks the job, false removes the bookmark. Idempotent — a retry never flips the state.

candidate.get_saved_jobs

List the candidate's saved (bookmarked) jobs, newest first. Only currently PUBLISHED jobs are returned — a job saved earlier then closed/archived is omitted.

Parameters (1)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.

candidate.accept_invitation

Accept an employer's invitation to a job (INVITED -> APPLIED). Idempotent — accepting an already-accepted invite succeeds. Returns NOT_INVITED when there is no open invitation (e.g. already withdrawn/declined), and NOT_FOUND when the job/invite is not found or the job is no longer public.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

candidate.decline_invitation

Decline an employer's invitation to a job (INVITED -> DECLINED). TERMINAL — a declined invite blocks any re-invite from the employer, so only decline when the candidate is sure. Idempotent (declining again succeeds). Returns NOT_INVITED when there is no open invitation, NOT_FOUND when the job/invite is not found.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

candidate.withdraw_application

Withdraw the candidate's active application to a job (APPLIED -> WITHDRAWN). Idempotent (withdrawing again succeeds). Returns NOT_APPLIED when there is no active application (e.g. only an open invitation, or already declined), and NOT_FOUND when no application exists for the job.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

candidate.apply_to_job

Apply the candidate to a PUBLISHED job, reusing their evaluated profile interview as evidence. Idempotent (re-applying succeeds; `reused` is true when an application row already existed). Requires a completed + evaluated interview — otherwise returns GATE_LOCKED / GATE_EVALUATING / GATE_FAILED. A missing or non-public job returns NOT_FOUND.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

employer.list_jobs

List jobs owned by the current employer account.

Parameters (4)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
statusany
limitnumber
offsetnumber

employer.get_job

Fetch a single employer job record by id. Returns NOT_FOUND for missing jobs and for jobs owned by another employer (no existence leak).

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

employer.create_job

Parse raw text via Gemini AI and create a DRAFT job under the current employer. Synchronous: latency 5-30s. The agent can then call employer.update_job to refine fields and employer.publish_job to make it live.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
rawTextstringrequired
Free-form job description (up to 10000 characters). Parsed by Gemini AI; the call typically takes 5-30 seconds. On a client-side timeout, recover by calling employer.list_jobs with status=DRAFT and pick the most recent row.

employer.update_job

Update the fields of an existing employer job. Accepts a partial whitelist; rawInput and dataSource are not editable (the wrapper auto-flips dataSource to USER_EDITED on every agent update). Non-owner reads return NOT_FOUND.

Parameters (3)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired
fieldsobjectrequired

employer.publish_job

Transition a DRAFT job to PUBLISHED. Returns NOT_FOUND for missing or non-owner jobs and CONFLICT when the job is not in DRAFT.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

employer.close_job

Transition a PUBLISHED job to CLOSED. Returns NOT_FOUND for missing or non-owner jobs and CONFLICT when the job is not in PUBLISHED.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

employer.archive_job

Transition a CLOSED job to ARCHIVED. Returns NOT_FOUND for missing or non-owner jobs and CONFLICT when the job is not in CLOSED.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

employer.delete_job

Permanently delete a DRAFT job that was never published. Returns NOT_FOUND for missing or non-owner jobs and CONFLICT when the job is not in DRAFT.

Parameters (2)

apiKeystring
Optional WorkorAI MCP key for in-session authentication when the MCP client was initialized anonymously.
jobIdstringrequired

employer.search_candidates_for_job

Semantically rank discoverable (interviewed) candidates against one of the employer's own jobs, with a per-candidate fit score AND a white-box explanation. WORKFLOW for finding the best hire: 1) call with tier:'best' to get the strongest candidates (cover the required skills + proven in interview), cascade to tier:'good' then tier:'weak' only if you need more (read tierCounts to decide; paginate within a band via page.hasMore, not page.total); 2) each row carries matchExplanation — the white-box 'why' (the fit score, the skills the candidate PROVED in their interview, what they're missing, and a plain-English rationale) — use it to explain your shortlist on OUR data, not a black box; 3) for the few you shortlist, call employer.get_candidate_evidence(jobId, userId) for the interview facts + Q&A to write a deeper comparative review. Omit tier for the full ranked pool (back-compat). Returns NOT_FOUND when the job is missing / owned by another employer (no existence leak), or NOT_INDEXED / NO_CATEGORIES when the job is not indexed for semantic search yet (re-save / republish, then retry).

Parameters (6)

apiKeystring
jobIdstringrequired
sortstring
pagenumber
pageSizenumber
tierstring
Match-quality band (required-skill coverage + fit). Omit to get the full ranked pool. To shortlist, START with tier:"best" — the strongest candidates (cover the required skills, proven in interview); only cascade to "good" then "weak" if you need more. Read tierCounts to decide; paginate within a band using page.hasMore (NOT page.total, which is the full pool). Each row carries matchExplanation (the white-box "why"); then call employer.get_candidate_evidence for the interview evidence to explain your ranking. Ignored on sort:"newest" (a recency browse has no bands → tierCounts bands are 0).

employer.search_candidates_by_query

Free-form semantic search across discoverable (interviewed) candidates with no job context. The query is embedded and candidates are ranked by semantic similarity — a preliminary search with no per-vacancy fit score (there is no vacancy to fit). For a scored ranking, use employer.search_candidates_for_job with a job id.

Parameters (4)

apiKeystring
querystringrequired
pagenumber
pageSizenumber

employer.get_candidate

Fetch a discoverable candidate by user id. Returns search-entry shape plus a light interview slice (overallScore + summary + completedAt + evaluatedAt) and `existingApplications`: every JobApplication this candidate has on any of the employer's jobs (all 4 statuses, all 4 job statuses) so the agent can decide whether re-inviting will succeed. Heavy artefacts (transcript, facts, resume, github, linkedin) live behind employer.get_applicant_detail and require an application.

Parameters (2)

apiKeystring
userIdstringrequired

employer.get_candidate_evidence

Fetch the interview EVIDENCE (facts proven in the interview + their Q&A, the interview summary, the résumé summary, and GitHub/LinkedIn signals) for ONE candidate AGAINST one of your published jobs — the white-box basis to explain WHY a candidate ranks where they do. Use it AFTER search_candidates_for_job: shortlist with the scorecard, then read the evidence here for the few you care about and write your own comparative review. Returns NOT_FOUND if the job is missing / not yours / not published, or the candidate is not in that job's searchable pool.

Parameters (3)

apiKeystring
jobIdstringrequired
One of YOUR published vacancies — the evidence is scoped to it (must-linked facts use its required skills).
userIdstringrequired
A candidate from search_candidates_for_job for THIS jobId. The interview evidence to explain your ranking.

employer.invite_candidate

Invite a discoverable candidate to one of the employer's PUBLISHED jobs. Creates a JobApplication with status=INVITED. If a prior WITHDRAWN row exists for this (candidate, job) pair, the row is UPDATEd back to INVITED (re-invite is allowed after the candidate withdrew on their own). INVITED, APPLIED, and DECLINED rows still block with INVITE_BLOCKED: INVITE_NOT_ALLOWED. Inspect `existingApplications` on employer.get_candidate before calling to know which case applies. Returns INVITE_BLOCKED with one of several sub-reasons (JOB_NOT_FOUND, JOB_NOT_PUBLISHED, CANDIDATE_NOT_FOUND, NOT_DISCOVERABLE, INVITE_NOT_ALLOWED) when the invite cannot be created. A missing vacancy and a vacancy owned by another employer both return JOB_NOT_FOUND (you cannot tell them apart — anti-enumeration).

Parameters (3)

apiKeystring
jobIdstringrequired
candidateUserIdstringrequired

employer.list_applicants

List the live (APPLIED) applicants on one of the employer's jobs. The candidate showcase + interview overallScore/summary are always returned; contact fields are only included when the application is SHORTLISTED or HIRED.

Parameters (2)

apiKeystring
jobIdstringrequired

employer.set_review_status

Update the employer review state on an application (NEW / REVIEWING / SHORTLISTED / REJECTED / HIRED). SHORTLISTED and HIRED unlock the candidate's direct contact in subsequent list_applicants / get_applicant_detail calls. WITHDRAWN applications surface as CONFLICT.

Parameters (3)

apiKeystring
applicationIdstringrequired
reviewStatusstringrequired

employer.get_applicant_detail

Full applicant bundle: resume, interview light slice (overallScore + summary + facts), GitHub analysis, LinkedIn analysis. The verbatim transcript is delivered by employer.get_applicant_transcript; the resume's contact fields are blanked unless the application is SHORTLISTED or HIRED.

Parameters (2)

apiKeystring
applicationIdstringrequired

employer.get_applicant_transcript

Verbatim interview transcript for one applicant. Ownership-only gate (same as the UI Download button — no SHORTLISTED/HIRED requirement). Returns an empty array when the source interview never produced turns.

Parameters (2)

apiKeystring
applicationIdstringrequired

employer.list_invitations

List the pending (INVITED) candidates on one of the employer's jobs — candidates who have been invited but have not yet accepted or declined.

Parameters (2)

apiKeystring
Employer MCP API key
jobIdstringrequired
The job to list invitations for

employer.cancel_invitation

Cancel a pending invitation sent to a candidate. The invitation record is deleted; the employer can re-invite the same candidate later.

Parameters (3)

apiKeystring
Employer MCP API key
jobIdstringrequired
The job the invitation belongs to
candidateUserIdstringrequired
The candidate whose invitation to cancel

README.md8 KBView on GitHub

WorkorAI Agent Kit

WorkorAI Agent Kit packages the workorai Agent Skill and a zero-dependency installer for WorkorAI MCP talent marketplace workflows.

It supports both sides of the marketplace through one skill:

Candidates ask prompts like найди мне работу, find me a job, or help me get hired; the skill guides them through onboarding, MCP key setup, and the candidate match tools.
Employers ask prompts like найди кандидатов, hire developers, post a job, or review applicants; the skill walks through the 19-tool employer MCP surface (job lifecycle, candidate discovery, invitations, applicants review).

Both roles share one skill name (workorai) and one credential helper, with role-aware storage slots so a dual-role user can keep both keys.

Install

Install the skill and write MCP config for supported local agents:

bash

npx @workorai/agent-kit install

Install for one client:

bash

npx @workorai/agent-kit install --agent codex
npx @workorai/agent-kit install --agent claude
npx @workorai/agent-kit install --agent opencode
npx @workorai/agent-kit install --agent cursor
npx @workorai/agent-kit install --agent openclaw
npx @workorai/agent-kit install --agent qwen
npx @workorai/agent-kit install --agent antigravity
npx @workorai/agent-kit install --agent deepcode

Use a local development MCP endpoint:

bash

npx @workorai/agent-kit install --endpoint http://127.0.0.1:3001/mcp

For isolated installer tests, set WORKORAI_AGENT_HOME to a temporary directory:

bash

WORKORAI_AGENT_HOME=/tmp/workorai-agent-home npx @workorai/agent-kit install

After install, restart the agent client and ask:

text

find me a job

What Is Included

skills/workorai/SKILL.md - canonical Agent Skill (thin role router).
skills/workorai/agents/openai.yaml - Codex/OpenAI-style UI metadata.
skills/workorai/references/
- candidate-catalog.md - candidate tool mini-schemas
- candidate-recipes.md - candidate calling-order recipes (incl. the Agent Pick result presentation)
- candidate-troubleshooting.md - candidate-side error scenarios
- employer-catalog.md - 19 employer tool mini-schemas
- employer-recipes.md - hire / review / lifecycle recipes
- employer-troubleshooting.md - employer-side error scenarios
- auth-flow.md - candidate and employer onboarding + saved-key flow
- troubleshooting.md - cross-role MCP transport / saved-key issues
skills/workorai/scripts/credential-store.mjs - role-aware consent-based local MCP key storage.
bin/workorai-agent.mjs - installer, MCP config writer, diagnostics, and credential command wrapper.

Supported Targets

Agent target	Skill location	MCP config
`codex`	`~/.codex/skills/workorai`	`~/.codex/config.toml`
`claude`	`~/.claude/skills/workorai`	`~/.claude.json`
`opencode`	`~/.config/opencode/skills/workorai`	`~/.config/opencode/config.json`
`cursor`	`~/.cursor/skills/workorai`	Use WorkorAI MCP config supported by your Cursor setup
`openclaw`	`~/.agents/skills/workorai`	`~/.agents/mcp.json`
`qwen`	`~/.qwen/skills/workorai`	Configure MCP according to your Qwen Code setup
`antigravity`	`~/.gemini/antigravity/skills/workorai`	Configure MCP according to your Antigravity setup
`deepcode`	`~/.agents/skills/workorai`	`~/.agents/mcp.json`
`generic`	`~/.agents/skills/workorai`	`~/.agents/mcp.json`

The default install command installs a canonical copy at ~/.agents/skills/workorai and links or copies compatible client locations.

Commands

bash

npx @workorai/agent-kit --help
npx @workorai/agent-kit install --dry-run
npx @workorai/agent-kit configure --agent all
npx @workorai/agent-kit print-config --agent codex
npx @workorai/agent-kit doctor --agent all
npx @workorai/agent-kit credential get

Credentials

The skill reads WorkorAI MCP keys role-aware. Default --role is candidate; pass --role=employer for the employer slot.

Candidate read order:

WORKORAI_MCP_API_KEY
OS secret store (account candidate)
Shared local fallback at ~/.config/workorai/mcp-token

Employer read order:

WORKORAI_EMPLOYER_MCP_API_KEY
OS secret store (account employer)
Shared local fallback at ~/.config/workorai/mcp-token-employer

Save with OS storage by default:

bash

npx @workorai/agent-kit credential save                  # candidate (default)
npx @workorai/agent-kit credential save --role=employer

Use best-effort storage for headless agent sessions:

bash

npx @workorai/agent-kit credential save --best-effort --role=candidate
npx @workorai/agent-kit credential save --best-effort --role=employer

Use the shared file fallback only after explicit user consent:

bash

npx @workorai/agent-kit credential save --shared-file --role=<role>

Never put real WorkorAI MCP keys in repositories, screenshots, issue text, or MCP config. Redact keys as wai_[REDACTED].

Skill Hub Compatibility

This repository is structured for direct ingestion by major skill surfaces:

GitHub: readable standalone repository with license, security policy, CI, and contribution docs.
npm: @workorai/agent-kit CLI package for one-command install.
Codex/OpenAI-style skills: canonical folder at skills/workorai plus agents/openai.yaml.
Claude Code: standard SKILL.md folder installable into .claude/skills/ or ~/.claude/skills/.
OpenCode: standard SKILL.md folder installable into .opencode/skills/, ~/.config/opencode/skills/, or Claude-compatible locations.
Cursor: standard SKILL.md folder installable into .cursor/skills/ or ~/.cursor/skills/.
Qwen Code: standard SKILL.md folder installable into .qwen/skills/ or ~/.qwen/skills/.
Antigravity / Gemini Antigravity: standard SKILL.md folder installable into ~/.gemini/antigravity/skills/.
Deep Code / DeepSeek: standard SKILL.md folder installable into .deepcode/skills/ or the shared ~/.agents/skills/.
skills.re and similar registries: root skills/ folder with at least one skill directory.
Cursor/Windsurf-compatible hubs: canonical SKILL.md folder plus generic MCP config notes in registry/.

Submission notes live in registry/submission-checklist.md.

Candidate Onboarding

When personalized MCP access is not available, the skill guides the user through:

Register and sign in: https://workorai.com/candidate/login
Complete profile: https://workorai.com/candidate/profile
Complete the profile interview and wait for evaluation.
Generate or copy the MCP key: https://workorai.com/candidate/home?tab=mcp
Paste the key into the agent session for immediate candidate.search_jobs use.

Employer Onboarding

When the user asks to hire, post jobs, or review candidates, the skill guides them through:

Sign in: https://workorai.com/employer/login
Open the Employer Dashboard and locate the Employer MCP card: https://workorai.com/employer/dashboard
Generate or copy the MCP key from the card.
Paste the key into the agent session for immediate employer.* tool use.
Save with --role=employer for future hiring searches.

The 19 employer tools cover the full hire-to-review lifecycle. See skills/workorai/references/employer-catalog.md for the mini-schemas and skills/workorai/references/employer-recipes.md for the four calling-order recipes (hire from a specific job, free-form hire, funnel review, pending-invites cleanup) plus the job lifecycle (create → publish → close → archive).

Development

bash

npm run validate
npm run smoke
npm pack --dry-run

npm run smoke installs into a temporary directory only and does not touch user agent config.

Release

Update CHANGELOG.md.
Run validation, smoke, and npm pack --dry-run.
Tag the GitHub release.
Publish npm:

bash

npm publish --access public

Submit the repository URL to relevant skill hubs using registry/submission-checklist.md.

License

MIT. See LICENSE.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "workorai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://workorai.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.