postulo-mcp: let an AI agent operate Postulo through the Model Context Protocol #19

New issue

Closed

opened 2026-09-05 12:29:19 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-09-05 12:29:19 +00:00

Owner

Observation

postulo-mcp - control by AI agents

Consistent with "no AI in v1"

docs/PLAN.md: "AI assistance — Not in v1. The application is complete and useful without an API key. A plugin can add it later against the same contracts." MCP is that sentence the other way round: no model inside Postulo, no API key in Postulo's settings. The agent lives wherever the person already runs one — Claude Desktop, Claude Code, an IDE, a self-hosted agent — and Postulo answers it through the API like any other client. Someone who wants nothing to do with AI installs nothing and nothing changes. Someone who does gets an agent that knows their job hunt without pasting it into a chat window.

Shape

A separate package, postulo-mcp, in Python on the official mcp SDK (FastMCP). stdio transport first, which is what local agents speak; Streamable HTTP later for remote agents — that transport expects OAuth 2.1, which #12 deliberately does not propose yet.
Configured with the instance URL and a personal access token (#12). Read-only by default: a token with the read scope can do no harm, and the server also accepts --read-only regardless of what the token allows. Writing requires a write token and the flag off.
Tools, each one API call, named as the agent's vocabulary:
- reading: list_applications (status, company, since), get_application (with its timeline), search_postings, list_reminders (due), list_companies, get_contacts, get_cv (structured or as text), get_cover_letter, get_insights
- writing: record_application, change_status (through the service, so the event log is written), add_note, add_reminder, complete_reminder, create_cover_letter_draft, request_render
- nothing destructive: no delete, anywhere
Resources: an application, a CV, a letter addressable as postulo://… and returned as text, so an agent can read a CV without a tool call.
Prompts (MCP prompt templates): "prepare me for the interview at Company" — posting, company notes, contacts, timeline, in one shot; "weekly review" — what is waiting, what is due, what went quiet.
Attribution. Every write lands in the timeline as "via API token name" (#12 item 4), so the person always sees which changes an agent made and can undo them by hand. The event log is what makes letting an agent write acceptable.
Files. The server never returns PDF bytes unless the token carries documents:read; CVs travel as text.
Documentation. The two or three lines of client configuration for Claude Desktop and Claude Code, and a plain paragraph on what a read token exposes to the model the person chose.

Classification

Enhancement. A separate package; changes nothing unless someone runs it. Not breaking.

Depends on

#12 — scoped personal access tokens, the read resources, the writes through services, and the actor on the event log.

Open questions

Which write tools ship first? Proposal: add_note, add_reminder, change_status; record_application once the shape settles.
Publish to PyPI as postulo-mcp and to the MCP registry?
Remote transport with OAuth: only if a real request appears; a self-hoster running the server beside their agent has no need for it.

## Observation > postulo-mcp - control by AI agents ## Consistent with "no AI in v1" `docs/PLAN.md`: "AI assistance — Not in v1. The application is complete and useful without an API key. A plugin can add it later against the same contracts." MCP is that sentence the other way round: **no model inside Postulo, no API key in Postulo's settings.** The agent lives wherever the person already runs one — Claude Desktop, Claude Code, an IDE, a self-hosted agent — and Postulo answers it through the API like any other client. Someone who wants nothing to do with AI installs nothing and nothing changes. Someone who does gets an agent that knows their job hunt without pasting it into a chat window. ## Shape - **A separate package, `postulo-mcp`**, in Python on the official `mcp` SDK (FastMCP). **stdio** transport first, which is what local agents speak; **Streamable HTTP** later for remote agents — that transport expects OAuth 2.1, which #12 deliberately does not propose yet. - **Configured with** the instance URL and a personal access token (#12). Read-only by default: a token with the `read` scope can do no harm, and the server also accepts `--read-only` regardless of what the token allows. Writing requires a `write` token *and* the flag off. - **Tools**, each one API call, named as the agent's vocabulary: - reading: `list_applications` (status, company, since), `get_application` (with its timeline), `search_postings`, `list_reminders` (due), `list_companies`, `get_contacts`, `get_cv` (structured or as text), `get_cover_letter`, `get_insights` - writing: `record_application`, `change_status` (through the service, so the event log is written), `add_note`, `add_reminder`, `complete_reminder`, `create_cover_letter_draft`, `request_render` - nothing destructive: no delete, anywhere - **Resources**: an application, a CV, a letter addressable as `postulo://…` and returned as text, so an agent can read a CV without a tool call. - **Prompts** (MCP prompt templates): "prepare me for the interview at *Company*" — posting, company notes, contacts, timeline, in one shot; "weekly review" — what is waiting, what is due, what went quiet. - **Attribution.** Every write lands in the timeline as "via API token *name*" (#12 item 4), so the person always sees which changes an agent made and can undo them by hand. The event log is what makes letting an agent write acceptable. - **Files.** The server never returns PDF bytes unless the token carries `documents:read`; CVs travel as text. - **Documentation.** The two or three lines of client configuration for Claude Desktop and Claude Code, and a plain paragraph on what a `read` token exposes to the model the person chose. ## Classification Enhancement. A separate package; changes nothing unless someone runs it. Not breaking. ## Depends on #12 — scoped personal access tokens, the read resources, the writes through services, and the actor on the event log. ## Open questions 1. Which write tools ship first? Proposal: `add_note`, `add_reminder`, `change_status`; `record_application` once the shape settles. 2. Publish to PyPI as `postulo-mcp` and to the MCP registry? 3. Remote transport with OAuth: only if a real request appears; a self-hoster running the server beside their agent has no need for it.

tiagoagueda added this to the 0.2.0 milestone

2026-09-05 12:29:19 +00:00

tiagoagueda added the

enhancement

label

2026-09-05 12:29:19 +00:00

tiagoagueda referenced this issue

2026-09-05 12:29:21 +00:00

A general API with personal access tokens and scopes, beyond the capture API #12

tiagoagueda referenced this issue

2026-09-05 14:04:08 +00:00

One search box over everything: listings, companies, contacts, notes and the text of what was sent #29