Skip to content

MCP Tools

claude edited this page Nov 18, 2026 · 1 revision

MCP tools

The tools the Job-o-Matic MCP server offers to an MCP app. Start the server with python src/jobomatic/mcp_server.py [path/to/jobomatic.db] (or set JOBOMATIC_DB). Every write is recorded as ai. Start with schema_guide; see Quick-Start-for-AI.

Tool Summary
get_profile The whole profile in one call: person, links, employers, positions, items (each with its metrics and attached original ids), resume lines, skills, education.
search Ranked full-text search over facts, resume lines, employers, positions, items, item metrics, skills and Q&A; best match first.
resume_data The whole resume for a track in one JSON document: person, links, employers (each with its positions, and each position with its ranked lines, the item and metrics behind each line), items (awards, projects, reviews .
schema_guide Plain-language description of every table, view, column and rule.
list List rows of a table (optionally only one status), newest ids last.
get Fetch one row by id, with created_by and last_changed_by (user, ai or app, from audit); images omit the picture bytes.
save Insert a row (no 'id' key) or update one (with 'id'); only editable columns are accepted.
save_many Save many rows of one table in one transaction: all are written or none, and the error names the failing row.
retire Retire a row (status Deprecated / Archived / Retired).
list_originals List the unedited source documents (resumes, reviews, ...) with their extraction state.
add_original Store a file from this computer (give its full path) as an original: copied into my_data/originals/, never changed, and its text extracted, the same as Upload in the app.
read_original Return an original's metadata and its extracted text.
mark_extracted Record how far facts have been pulled from an original into the tables: 'Not yet', 'Text read', 'Partly' or 'Done'.
qa_open Interview questions still waiting for an answer or a review, in order.
build_resume Fill a resume template (executive, navy_bar, two_column, structured or genz) with the profile's Short and Long lines for a version (track); Story lines are for cover letters and interviews and are never printed.

get_profile

Parameters: none

The whole profile in one call: person, links, employers, positions, items (each with its metrics and attached original ids), resume lines, skills, education. Items hold every kind: responsibilities, achievements, awards, projects, reviews ...

search

Parameters: text: str, limit: int = 20, include_unanswered: bool = False

Ranked full-text search over facts, resume lines, employers, positions, items, item metrics, skills and Q&A; best match first. Paste a whole job description to find the lines that fit it (common words are ignored). Seeded interview questions with no answer yet are left out unless include_unanswered. Returns source_table, source_id, snippet, rank (max 50).

resume_data

Parameters: track: str = 'Original'

The whole resume for a track in one JSON document: person, links, employers (each with its positions, and each position with its ranked lines, the item and metrics behind each line), items (awards, projects, reviews ... with metrics), Verified skills and education. Use it to write a resume or cover letter.

schema_guide

Parameters: none

Plain-language description of every table, view, column and rule. Read this first.

list

Parameters: table: str, status: str | None = None, limit: int = 100

List rows of a table (optionally only one status), newest ids last. Max 500 rows. Images omit the picture bytes. Also reads audit (every write: who, when, the row before and after) and last_change (who last changed each row); for those two you get the most recent rows, newest last.

get

Parameters: table: str, id: int

Fetch one row by id, with created_by and last_changed_by (user, ai or app, from audit); images omit the picture bytes. updated_by is always empty once a write is recorded: read these two instead. Also gets one audit entry.

save

Parameters: table: str, row: dict, expected_updated_at: str | None = None

Insert a row (no 'id' key) or update one (with 'id'); only editable columns are accepted. Recorded as 'ai'. New rows you add start as 'Needs review' unless you set a status. Returns the full saved row. When updating, pass the row's updated_at from when you read it: if the person changed it since, nothing is written and the error carries the current row, so merge into that instead of overwriting their edit.

save_many

Parameters: table: str, rows: list[dict]

Save many rows of one table in one transaction: all are written or none, and the error names the failing row. Each row is like save's row (no 'id' inserts, 'id' updates) and may carry its own 'expected_updated_at'. Use it for bulk changes such as setting status 'Verified'; every write is recorded as 'ai'. Max 500 rows. Returns the saved rows in order.

retire

Parameters: table: str, id: int

Retire a row (status Deprecated / Archived / Retired). Rows are never deleted. Recorded as 'ai'.

list_originals

Parameters: none

List the unedited source documents (resumes, reviews, ...) with their extraction state. Waiting for you = extracted <> 'Done' ('Text read' means the text is ready but no facts were taken yet).

add_original

Parameters: path: str, kind: str, title: str | None = None

Store a file from this computer (give its full path) as an original: copied into my_data/originals/, never changed, and its text extracted, the same as Upload in the app. kind: Resume, Job description, Review, Recommendation, Other, or 'AI output' for a file you wrote. PDF, DOCX, TXT, MD, PNG or JPEG, up to 25 MB. A file already stored is refused with its original id. Returns the new original; read its text with read_original.

read_original

Parameters: id: int

Return an original's metadata and its extracted text. If not extracted yet, says so instead of text.

mark_extracted

Parameters: id: int, state: str

Record how far facts have been pulled from an original into the tables: 'Not yet', 'Text read', 'Partly' or 'Done'. Set 'Done' only when you have taken everything useful.

qa_open

Parameters: none

Interview questions still waiting for an answer or a review, in order.

build_resume

Parameters: template: str, track: str = 'Original'

Fill a resume template (executive, navy_bar, two_column, structured or genz) with the profile's Short and Long lines for a version (track); Story lines are for cover letters and interviews and are never printed. Writes a new HTML file the person can print to PDF (an earlier one is never overwritten). Returns its path and warnings: how many printed rows are still Needs review and how many skills are hidden because not Verified.

Clone this wiki locally