{
  "schema_version": "2025-06-18",
  "name": "SOVIQ AI",
  "description": "Construction billing MCP server — read, draft, and confirmed act",
  "version": "1.1.0",
  "transport": {
    "type": "streamable-http",
    "url": "https://app.soviqai.com/mcp"
  },
  "authentication": {
    "type": "oauth2",
    "authorization_url": "https://app.soviqai.com/oauth/authorize",
    "token_url": "https://app.soviqai.com/oauth/token"
  },
  "tools": [
    {
      "name": "list_projects",
      "title": "List projects",
      "tier": "read",
      "description": "List all projects for the connected company with Pulse money (billed, held, collected, open).",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_project",
      "title": "Get project",
      "tier": "read",
      "description": "Get a project Pulse snapshot and the last 50 timeline events.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "list_pay_apps",
      "title": "List pay apps",
      "tier": "read",
      "description": "List pay applications for a project (number, status, amount due, sent and paid dates).",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_pay_app",
      "title": "Get pay app",
      "tier": "read",
      "description": "Get pay app lines, G702 totals, attachment metadata, and a 15-minute signed PDF URL.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_ar",
      "title": "Get accounts receivable",
      "tier": "read",
      "description": "Company accounts receivable: all open pay apps (not cash-forecast eligibility). Each row includes days_past_due (vs payment due date) and owner pay-speed (same copy rules as weekly cash email). Legacy days_late equals days_past_due here.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "list_change_orders",
      "title": "List change orders",
      "tier": "read",
      "description": "List change orders for a project (deleted rows excluded).",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_weekly_cash",
      "title": "Get weekly cash",
      "tier": "read",
      "description": "Weekly cash email numbers: tiles, forecast, and suggested actions.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_cash_forecast",
      "title": "Get cash forecast",
      "tier": "read",
      "description": "13-week computed cash forecast (in/out, position, confidence, lowest week, suggested action).",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "list_slow_payers",
      "title": "List slow payers",
      "tier": "read",
      "description": "Open PAs on forecast-eligible projects paying slower than that owner’s median. Rows include days_slower_than_usual (submit→today minus median) and days_past_due.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "search",
      "title": "Search",
      "tier": "read",
      "description": "Search projects, pay apps, vendors, and document filenames by text.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_co_template",
      "title": "Get CO template",
      "tier": "read",
      "description": "Preview change-order lines, markups, and revised contract total (no write).",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_playbook",
      "title": "Get playbook",
      "tier": "read",
      "description": "Weekly cash actions, cash-forecast prompt, approved unbilled change orders, and the open playbook prompts (each with a stable id for answer_prompt) plus the owner’s recent answers.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_project_context",
      "title": "Get project context",
      "tier": "read",
      "description": "What happened on a project (or the whole company) in the last N days: observations the assistant recorded, actions it took with evidence, draft pay apps waiting, unbilled change orders, open playbook prompts and the owner’s past answers, plus a voice-ready summary. Read this first every morning; chats are disposable, SOVIQ is the memory.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "list_observations",
      "title": "List observations",
      "tier": "read",
      "description": "Observations recorded by assistants (unverified facts seen in email, web, phone, documents), newest first.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "get_project_margin",
      "title": "Get project margin",
      "tier": "read",
      "description": "Profit on a project: revised contract, billed, collected, job costs to date by category (labor, materials, equipment, permits, credit_card, other), committed to subs, projected cost, projected profit and margin %, last labor entry, and a link to the Costs & Margin chart in SOVIQ. Ask for labor and material changes when last_labor_on is old or missing.",
      "annotations": {
        "readOnlyHint": true
      }
    },
    {
      "name": "record_observation",
      "title": "Record observation",
      "tier": "draft",
      "description": "Record something seen in the world (an owner payment notice, an approval email, a supplier invoice, a quote) as an UNVERIFIED observation with its source and excerpt. Saved immediately, changes nothing in the books, never asks. One observation per call, or up to 50 in items[].",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "set_job_costs",
      "title": "Set job costs",
      "tier": "draft",
      "description": "Propose dated job costs on a project (labor, materials, equipment, permits, credit_card, other) so projected profit updates. Read-back lists every line and the total; confirm_action writes them. Nothing is saved until confirm_action.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "record_action",
      "title": "Record action",
      "tier": "draft",
      "description": "Record something the assistant did outside SOVIQ (RFQ sent, QuickBooks invoice created, email sent, posted a listing) with evidence (message id, URL, external id, amount, recipient) and an outcome. Saved immediately; this is the audit trail, not a request to do it.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "answer_prompt",
      "title": "Answer prompt",
      "tier": "draft",
      "description": "Save the owner’s answer (yes, no, later) to a playbook prompt from get_playbook or get_project_context, so SOVIQ stops asking and the next chat knows what was decided. \"later\" asks again tomorrow.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "set_weekly_costs",
      "title": "Set weekly costs",
      "tier": "draft",
      "description": "Propose this week’s Labor, subs, materials, other, fuel, and credit cards (week_start defaults to owner TZ Monday). Partial numbers and “fuel 1800, rest same” carry the saved week and per-line history. Nothing is saved until confirm_action or an in-app tap.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "set_bank_balance",
      "title": "Set bank balance",
      "tier": "draft",
      "description": "Propose a bank balance as of a date (balance_dollars or balance_cents). confirm_action writes bank_balance_entries in cents. Nothing is saved until confirm_action.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "set_recurring_costs",
      "title": "Set recurring costs",
      "tier": "draft",
      "description": "Propose recurring monthly outflows. Each item: name (string), amount_dollars (number), day_of_month (1–28). confirm_action persists to recurring_costs. Nothing is saved until confirm_action.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "set_billing_schedule",
      "title": "Set billing schedule",
      "tier": "draft",
      "description": "Propose project billing days (billing_days_of_month array replaces the whole schedule, e.g. [1, 15]). billing_day_of_month is deprecated: each call adds one day to the saved schedule. Nothing is saved until confirm_action.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "draft_pay_app",
      "title": "Draft pay app",
      "tier": "draft",
      "description": "Create a draft pay app from a percent or dollar amount per line, or a rule such as “20% on all except roofing”. Tags the draft proposed_by_client. Nothing is submitted.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "draft_change_order",
      "title": "Draft change order",
      "tier": "draft",
      "description": "Store a change-order proposal with optional line-level template (title, amount, lines[], markups). Read-back includes every line and revised total before confirm.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "draft_reminder",
      "title": "Draft reminder",
      "tier": "draft",
      "description": "Store an editable reminder subject and body for a pay app. Nothing is emailed.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "propose_payment",
      "title": "Propose payment",
      "tier": "draft",
      "description": "Store a proposed payment (amount, method, date). Nothing is recorded until confirm_action.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "discard_draft",
      "title": "Discard draft",
      "tier": "draft",
      "description": "Soft-delete a draft pay app proposed by a connected client. Posted pay apps stay in place.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "propose_action",
      "title": "Propose action",
      "tier": "act",
      "description": "Ask to submit a pay app, send a reminder, or record a payment. Returns confirmation_id and a plain-English summary. Nothing happens until confirm_action.",
      "annotations": {
        "destructiveHint": false
      }
    },
    {
      "name": "confirm_action",
      "title": "Confirm action",
      "tier": "act",
      "description": "Perform a proposed action within 10 minutes, one use, or confirm a weekly-cost proposal. A second call does not repeat the action.",
      "annotations": {
        "destructiveHint": false
      }
    }
  ]
}
