Tools reference¶

The MCP Worker exposes 18 read-only tools, built in src/server.ts by buildServer(env). Every tool resolves to a single GET against the swapps-app API via apiGet(env, path, params) and returns the response as pretty-printed JSON text (or a readable error string on failure).

The tool names and behavior mirror the local Python server in tools/swapps-app-mcp/, so a client can switch between local and remote transports without changing how tools are called.

Common input types¶

• pk — a positive integer primary key. Schema: z.number().int().
• contract_pk — the parent contract's integer id, for nested resources. Schema: z.number().int().
• params — an optional object of DRF query parameters (filters / pagination / search) whose values are string | number | boolean. Schema: z.record(z.union([z.string(), z.number(), z.boolean()])).optional(). Example: {"status": "open", "page": 2}.

Tools at a glance¶

Tool	Inputs	Downstream GET	Purpose
list_clients	params?	clients/	List registered clients.
get_client	pk	clients/{pk}/	Get a client by id.
list_contracts	params?	contracts/	List contracts.
get_contract	pk	contracts/{pk}/	Get a contract by id.
list_contract_services	contract_pk, params?	contracts/{contract_pk}/services/	List a contract's services.
get_contract_service	contract_pk, pk	contracts/{contract_pk}/services/{pk}/	Get one service of a contract.
list_contract_installments	contract_pk, params?	contracts/{contract_pk}/installments/	List a contract's installments.
get_contract_installment	contract_pk, pk	contracts/{contract_pk}/installments/{pk}/	Get one installment of a contract.
list_contract_level_rates	contract_pk, params?	contracts/{contract_pk}/level-rates/	List a contract's per-level rates.
get_contract_level_rate	contract_pk, pk	contracts/{contract_pk}/level-rates/{pk}/	Get one level-rate of a contract.
list_reports	params?	reports/	List reports.
get_report	pk	reports/{pk}/	Get a report by id.
list_tasks	params?	tasks/	List tasks.
get_task	pk	tasks/{pk}/	Get a task by id.
list_time_entries	params?	time-entries/	List time entries.
get_time_entry	pk	time-entries/{pk}/	Get a time entry by id.
get_celery_task_status	task_id?	get-task-status/	Check a Celery async task's status.
api_request	path, params?	{path}	Read-only GET escape hatch to any API route.

Per-tool detail¶

Clients¶

list_clients¶

List the clients registered in swapps-app.

• Input: { params?: object } — optional DRF filters / pagination.
• Behavior: GET clients/ (with params as query string).

get_client¶

Get a single client by id.

• Input: { pk: integer }.
• Behavior: GET clients/{pk}/.

Contracts¶

list_contracts¶

List contracts.

• Input: { params?: object }.
• Behavior: GET contracts/.

get_contract¶

Get a contract by id.

• Input: { pk: integer }.
• Behavior: GET contracts/{pk}/.

Contract services¶

list_contract_services¶

List the services of a contract.

• Input: { contract_pk: integer, params?: object }.
• Behavior: GET contracts/{contract_pk}/services/.

get_contract_service¶

Get a specific service of a contract.

• Input: { contract_pk: integer, pk: integer }.
• Behavior: GET contracts/{contract_pk}/services/{pk}/.

Contract installments¶

list_contract_installments¶

List the installments of a contract.

• Input: { contract_pk: integer, params?: object }.
• Behavior: GET contracts/{contract_pk}/installments/.

get_contract_installment¶

Get a specific installment of a contract.

• Input: { contract_pk: integer, pk: integer }.
• Behavior: GET contracts/{contract_pk}/installments/{pk}/.

Contract level-rates¶

list_contract_level_rates¶

List the per-level rates of a contract.

• Input: { contract_pk: integer, params?: object }.
• Behavior: GET contracts/{contract_pk}/level-rates/.

get_contract_level_rate¶

Get a specific level-rate of a contract.

• Input: { contract_pk: integer, pk: integer }.
• Behavior: GET contracts/{contract_pk}/level-rates/{pk}/.

Reports¶

list_reports¶

List reports.

• Input: { params?: object }.
• Behavior: GET reports/.

get_report¶

Get a report by id.

• Input: { pk: integer }.
• Behavior: GET reports/{pk}/.

Tasks¶

list_tasks¶

List tasks.

• Input: { params?: object } — e.g. {"status": "open"}.
• Behavior: GET tasks/.

get_task¶

Get a task by id.

• Input: { pk: integer }.
• Behavior: GET tasks/{pk}/.

Time entries¶

list_time_entries¶

List time entries.

• Input: { params?: object }.
• Behavior: GET time-entries/.

get_time_entry¶

Get a time entry by id.

• Input: { pk: integer }.
• Behavior: GET time-entries/{pk}/.

Misc¶

get_celery_task_status¶

Check the status of a Celery async task.

• Input: { task_id?: string } — when provided, sent as the task_id query param.
• Behavior: GET get-task-status/ (optionally ?task_id=<task_id>).

api_request¶

Read-only escape hatch: performs a GET against any API route (relative to the base URL). It does not allow create / update / delete.

• Input: { path: string, params?: object }.
• Behavior: GET {path} with params as query string. A leading slash on path is stripped and the path is joined onto SWAPPS_API_BASE_URL.