@sodiumhq/mcp-pm 0.1.0-beta.3964 → 0.1.0-beta.4241

package/README.md

@@ -59,6 +59,7 @@ Only enable write mode with an AI client you trust — it hands the client the a
 ## What it can do today
 
 **Practice**
+- **`get_practice_dashboard`** — one-call "state of the practice right now": overdue/blocked/due-soon work, what clients are sitting on, unassigned steps, unbilled time, open proposal pipeline. *"Give me my morning briefing."*
 - **`get_practice_details`** — consolidated practice overview (counts, connections, settings)
 - **`whoami`** — show the authenticated user (name, email, code), tenant (name, code, status), and practice name. Useful for verifying which account is connected.
 
@@ -66,12 +67,60 @@ Only enable write mode with an AI client you trust — it hands the client the a
 - **`list_clients`** — list and filter clients by search, status, type, assignee, services, saved filters
 - **`get_client_summary`** — one-call composite for a single client: identity + contacts + active services with pricing + business details (company number, VAT, UTR, trading address) + **custom fields** (all user-defined fields with current values, data types, and field codes) + key statutory dates (year-end, accounts due, VAT return due, confirmation statement due) + overdue tasks + tasks due in next 7 days
 - **`get_custom_field_details`** — get the full definition of a custom field by code, including allowed options for Select/MultiSelect fields. Use before setting a dropdown field to discover valid values.
+- **`get_onboarding_status`** — "are we ready to act for this client?": engagement, AML, HMRC authorisations, outstanding requests, and data completeness in one answer.
+- **`get_client_agent_authorisations`** — HMRC agent authorisation status per tax regime for a client. "Do we have SA authorisation for ACME?"
+- **`list_client_documents`** — the document register: what's held, what needs review, what's awaiting client approval. "Do we have ACME's signed engagement letter?"
+- **`list_client_links`** — the URLs saved on a client (website, LinkedIn, accounting software).
+- **`list_portal_users`** — who has client-portal access and who never logged in.
 
 **Tasks**
 - **`list_tasks`** — find and count tasks by assignee (including "my tasks"), client, status, overdue, date range, category, team, or workflow. Answers "what's on my plate?", "what's Jane working on?", "what's overdue for ACME?", "how many tasks are due this week?"
 - **`get_task_context`** — one-call composite for a single task: details + notes + workflow steps + primary client + category
+- **`get_task_history`** — the audit trail: who changed what and when, including client-made changes.
+- **`list_pending_workflow_steps`** — every workflow step actionable right now, across the practice. "What steps are waiting on me?", "what's unassigned?"
+- **`list_recurring_tasks`** — the templates that generate repeating work (monthly bookkeeping, quarterly VAT), with recurrence pattern, linked service/workflow, and next run date. "What recurring work do we run for ACME?"
+
+**Workflows and practice setup**
+- **`list_workflows`** — find workflow templates by name; resolves the workflow codes the report tools need. "What workflows do we have?"
+- **`get_workflow`** — one template's full group/step structure: step types, assignment rules, dependencies, conditions. "What are the steps in our VAT return workflow?"
+- **`list_teams`** — teams with their member rosters. "Who's in the tax team?"
+- **`list_task_categories`** — the practice's task categories and their codes.
+- **`list_saved_task_filters`** / **`list_saved_client_filters`** — the user's saved views, with the criteria each encodes. "Run my Weekly Review view."
+
+**Client requests**
+- **`list_document_requests`** — document requests across the practice: status, deadline, chase history, linked task. "What are we waiting on from clients right now?"
+- **`list_data_form_requests`** — questionnaire/data-form requests: who's been sent what, who's responded, which answers await review. "Who still hasn't returned the SA questionnaire?"
+- **`list_data_forms`** — the questionnaire templates the practice can send.
+
+**Emails**
+- **`list_sent_emails`** — the delivery audit trail of everything Sodium sent (proposals, chases, invitations) with status. "Did the proposal email to ACME actually go out?", "which emails failed this week?"
+- **`get_sent_email`** — one sent email's full delivery record: recipients, timeline, retries, errors, attachments.
+- **`list_client_emails`** — a client's two-way email threads from the practice's synced mailbox. "Has ACME replied about the VAT return?"
+- **`get_client_email_thread`** — one conversation in full: every message with sender and preview.
+- **`list_email_broadcasts`** / **`get_email_broadcast`** — campaign history with per-client delivery results. "How did the newsletter do — who bounced?"
+
+**AML / KYC**
+- **`list_aml_clients`** — the AML register: status, risk level, and which records still have incomplete checks. "Which clients have outstanding AML checks?"
+- **`get_aml_client`** — one AML record in full: per-contact onboarding and check statuses plus risk-assessment history. "Do any ACME directors still need ID checks?"
+
+**Billing**
+- **`list_billing_line_items`** — the service-billing pipeline: pending, approved, and invoiced lines with values and periods. "What's waiting to be billed?", "what are we billing ACME this month?"
+- **`list_invoice_submissions`** — the hand-off to the accounting system: submitted, failed, and forecast invoices. "Did ACME's invoice go through to Xero?"
+- **`list_service_packages`** — bundled offerings with contents and pricing.
+
+**Time tracking**
+- **`list_time_entries`** — recorded time by person, client, task, date range, billable and billed flags. "How much time have I logged this week?"
+- **`list_unbilled_time_clients`** — unbilled time totalled per client. "What WIP is sitting unbilled, and where?"
+
+**Companies House**
+- **`search_companies_house`** — live search of the public register by name or number. "Look up Bristol Roofing."
+- **`get_companies_house_profile`** — one company's full record: status, registered office, SIC codes, accounts and confirmation-statement deadlines with overdue flags, insolvency/charges flags, and officers. "When are ACME's accounts due at Companies House?"
+
+**Help**
+- **`get_usage_examples`** — a built-in cookbook of example prompts by topic. Ask *"what can you do?"* and the assistant will show you.
 
 **Proposals and engagements**
+- **`get_engagement_pipeline_summary`** — pipeline counts and values by status in one call. "What's our proposal pipeline worth?"
 - **`list_proposals`** and **`list_engagement_letters`** — aliased tools for the same underlying engagement pipeline (pre-acceptance vs signed). Filter by status, client, date range.
 - **`get_proposal_summary`** and **`get_engagement_letter_summary`** — aliased drill-ins: identity + client + value breakdown + services with pricing + PDFs + email history + acceptance record
 
@@ -85,7 +134,30 @@ Only enable write mode with an AI client you trust — it hands the client the a
 **Team**
 - **`list_users`** — find team members by name, email, role, or status — supports "who is Jane?", "list all partners", "who has been invited but not joined?"
 
+**Reports**
+- **`get_service_delivery_report`** — turnaround and on-time/statutory compliance for tasks completed in a period, grouped by service, client, assignee, or month. "How fast do we turn around VAT returns?"
+- **`get_service_delivery_steps`** — per-step bottlenecks inside one service's workflow, split client-wait vs internal. "Why do accounts jobs take so long?"
+- **`get_deadline_compliance_report`** — every due or statutory deadline that fell in a period: met, completed late, or missed and still open, plus a forward view of what's due next. "Which statutory deadlines did we miss last quarter?"
+- **`get_client_responsiveness_report`** — how fast clients answer document requests, approvals, confirmations, and data forms, and how much chasing it takes. "Is it us or the client?"
+- **`get_team_workload_report`** — open workload per person right now alongside completion throughput over a period. "Who has capacity?"
+- **`get_wip_ageing_report`** — live snapshot of open work by age, status, or the workflow step it's stuck at. "What's been sitting untouched the longest?"
+- **`get_workflow_step_analysis`** — step-by-step duration distributions (median/avg/p90/best/worst) across every completed run of one workflow template. "For our VAT workflow, where does the time go?"
+- **`list_workflow_occurrences`** — a workflow's completed runs, slowest first, with the client-wait vs internal split. "Show me the ten slowest VAT runs this quarter."
+- **`get_service_time_report`** — where recorded time goes: totals by service (or by client within one service) with estimate-vs-actual variance. "Where did our time go last month?"
+
 **Write tools** (require `--enable-writes` — see [Write mode](#write-mode))
+- **`create_task`** — create a one-off task with dates, client, assignee (person or team), category, service link, and a checklist. "Create a task to chase ACME's rental schedule, due Friday."
+- **`update_task`** — change a task's status, dates, assignment, or details. Only the fields you mention change; everything else is preserved. "Mark TSK-123 complete", "push the deadline to Friday", "reassign it to Jane."
+- **`update_workflow_step`** — complete, skip, block, or reassign a single workflow step on a task. "Mark the review step as done", "skip the client-approval step — they confirmed by phone."
+- **`add_client_service`** — put a client on a catalogue service with frequency, pricing, and start date. "Put ACME on monthly bookkeeping."
+- **`update_client_service_stage`** — move a client's service across the kanban board. "Move ACME's VAT return to Records In."
+- **`create_document_request`** — draft (never send) a document request for a client. Sending stays in the Sodium UI.
+- **`send_data_form`** — send a questionnaire to a client. Sends immediately, so your assistant confirms with you first.
+- **`create_proposal`** — draft a proposal/letter of engagement in Unsent state. Sending stays in the Sodium UI.
+- **`update_client_dates`** — set year-end, VAT, PAYE, and other key dates on a client.
+- **`update_client_business_details`** — update UTR, PAYE ref, VAT registration, trading name, addresses. Only the fields you mention change.
+- **`create_saved_task_filter`** — save a task query as a reusable view. "Save that as 'Monday Review' and pin it to my menu."
+- **`log_time_entry`** — record time after the fact, optionally against a client, task, or workflow step. "Log 2 hours on ACME for today — reviewing the draft accounts."
 - **`add_task_note`** — capture a note against a specific task. Attributed to your API user, timestamped to now.
 - **`add_client_note`** — capture a note against a client record. Same shape as `add_task_note` but scoped to the client.
 - **`update_client_custom_fields`** — set or clear custom field values on a client. Accepts a map of field codes to values, validates against the field's data type (Text, Number, Date, Boolean, Select, MultiSelect). Pass null to clear a field. Field codes are discoverable via `get_client_summary`.
@@ -93,6 +165,22 @@ Only enable write mode with an AI client you trust — it hands the client the a
 
 More tools land iteratively as the beta progresses.
 
+## Example prompts
+
+Ask in plain English — the assistant picks the right tools:
+
+- *"What's on my plate today, and what's overdue across the team?"*
+- *"Brief me for my call with ACME Ltd"* — services, deadlines, open work, outstanding requests, notes
+- *"What are we waiting on from clients right now?"*
+- *"Which statutory deadlines did we miss last quarter, and which are at risk this week?"*
+- *"Look up this prospect on Companies House — directors, filing deadlines, insolvency history"*
+- *"How much unbilled time do we have on ACME?"*
+- *"Who on the team has capacity?"*
+
+With writes enabled: *"Create a task to chase ACME's rental schedule, due Friday"*, *"mark TSK-123 complete"*, *"log 45 minutes on the Greggs VAT task"*.
+
+For the full cookbook, just ask your assistant **"what can you do with Sodium?"** — the server ships a built-in `get_usage_examples` tool with example prompts by topic.
+
 ## Requirements
 
 - Node.js 20 or later