agencyhandy-mcp 1.7.0 → 1.7.2

package/PRODUCTION.md

@@ -28,4 +28,6 @@ Repo: https://github.com/AgencyHandy/agency-backend-mcp
 
 ## Version
 
+`1.7.2` — API builder context resource (`ah://api-context`): leads/orders/tasks/comments/labels/clients/invoices/vouchers/forms gotchas + unit/mutation tests.
+`1.7.1` — Security harden (SSRF path/url guards, axios/deps audit clean) + mutation/npx entry tests; owner insights tolerate null/sparse API rows.
 `1.7.0` — Owner insights: cash risk, proposal pipeline aging, lead segments, client churn heuristics; plus advanced context packs.

package/README.md

@@ -129,10 +129,11 @@ Until the package is on npm, developers can run from this repo:
 
 | Ask | Tool |
 |---|---|
-| Who owes us / aging AR | `ah_cash_risk` |
-| Which proposals are rotting | `ah_proposal_pipeline` |
-| How do leads segment | `ah_lead_segments` (optional `customFieldName`) |
-| Who might churn | `ah_client_churn_risk` |
+| Top AR clients + past 30/60/90 — who to chase today | `ah_cash_risk` → then `ah_invoice_context` / send |
+| Stale or expiring proposals — bump vs write off | `ah_proposal_pipeline` → `ah_proposal_context` |
+| Lead mix by source / Industry — volume vs converting | `ah_lead_segments` (`customFieldName`) |
+| Quiet + overdue clients — watchlist & one next action | `ah_client_churn_risk` → order/invoice context |
+| Monday pulse: cash + cold proposals + slipping work | `ah_dashboard_digest` + the tools above |
 
 **Custom fields**
 
@@ -208,11 +209,11 @@ Order create is intentionally omitted (multipart / service-package heavy). Use `
 - **Lists / gets:** proposals, projects, tickets, tasks, invoices, members, client companies, services, forms, dashboard
 - **Platform:** chat, email-to-ticket settings, webhooks, order & platform subscriptions
 
-Prefer `*_context` tools and the `ah://full-context` resource before inventing ObjectIds.
+Prefer `*_context` tools and the `ah://full-context` resource before inventing ObjectIds. For custom API tooling, also read `ah://api-context` (leads/orders/tasks/comments/labels/clients/invoices/vouchers/forms gotchas).
 
 ### Resources & prompts
 
-Resources: `ah://full-context`, `ah://glossary`, `ah://models`, `ah://fields`, `ah://workflows`, `ah://workflows-platform`, `ah://usage`, …
+Resources: `ah://full-context`, `ah://glossary`, `ah://models`, `ah://fields`, `ah://workflows`, `ah://workflows-platform`, `ah://api-context`, `ah://usage`, …
 
 Prompts: `agency_handy_orientation`, `investigate_ticket`, `investigate_project`, `investigate_proposal`, `investigate_task`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agencyhandy-mcp",
-  "version": "1.7.0",
-  "description": "Official Agency Handy MCP server — owner insights + advanced context packs",
+  "version": "1.7.2",
+  "description": "Official Agency Handy MCP server — owner insights, context packs, API builder context",
   "type": "module",
   "main": "src/server.js",
   "bin": {
@@ -19,10 +19,12 @@
   "scripts": {
     "start": "node src/server.js",
     "dev": "node --watch src/server.js",
-    "test": "node scripts/smoke.mjs && node scripts/unit-custom-fields.mjs && node scripts/unit-work-context.mjs && node scripts/unit-owner-insights.mjs",
+    "test": "node scripts/smoke.mjs && node scripts/unit-api-context.mjs && node scripts/unit-custom-fields.mjs && node scripts/unit-work-context.mjs && node scripts/unit-owner-insights.mjs && node scripts/unit-security-mutate.mjs",
+    "test:security": "node scripts/unit-security-mutate.mjs",
+    "test:api-context": "node scripts/unit-api-context.mjs",
     "test:live": "SMOKE_LIVE=1 node scripts/smoke.mjs",
     "test:live:custom-fields": "node scripts/live-custom-fields.mjs",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test && npm audit --audit-level=high"
   },
   "keywords": [
     "agencyhandy",
@@ -34,7 +36,7 @@
   "license": "UNLICENSED",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.3",
-    "axios": "^1.9.0",
+    "axios": "^1.19.0",
     "dotenv": "^16.5.0",
     "zod": "^3.24.4"
   }

package/src/lib.js

@@ -1,10 +1,76 @@
 import axios from "axios";
 import { z } from "zod";
 
-export const VERSION = "1.7.0";
+export const VERSION = "1.7.2";
 
 export const READ_ONLY = false;
 
+/**
+ * Block SSRF / open redirects via axios absolute URLs or path traversal.
+ * All backend calls must be relative paths under /api/.
+ */
+export function assertSafeBackendPath(pathname) {
+  if (typeof pathname !== "string" || !pathname) {
+    return { ok: false, error: "backend path missing" };
+  }
+  if (/[\u0000-\u001f]/.test(pathname)) {
+    return { ok: false, error: "backend path contains control characters" };
+  }
+  const trimmed = pathname.trim();
+  if (
+    trimmed.startsWith("//") ||
+    /^https?:/i.test(trimmed) ||
+    /^[a-z][a-z0-9+.-]*:/i.test(trimmed)
+  ) {
+    return { ok: false, error: "backend path must not be an absolute URL" };
+  }
+  if (!trimmed.startsWith("/")) {
+    return { ok: false, error: "backend path must be absolute on the API host (start with /)" };
+  }
+  if (trimmed.includes("\\") || trimmed.includes("..")) {
+    return { ok: false, error: "backend path must not contain traversal sequences" };
+  }
+  if (!trimmed.startsWith("/api/")) {
+    return { ok: false, error: "backend path must start with /api/" };
+  }
+  return { ok: true, path: trimmed };
+}
+
+/**
+ * Validate AGENCY_BACKEND_URL before axios.create.
+ * Allow http only for loopback (local smoke); require https otherwise.
+ */
+export function assertSafeBackendUrl(rawUrl) {
+  if (typeof rawUrl !== "string" || !rawUrl.trim()) {
+    return { ok: false, error: "AGENCY_BACKEND_URL missing" };
+  }
+  let u;
+  try {
+    u = new URL(rawUrl.trim());
+  } catch {
+    return { ok: false, error: "AGENCY_BACKEND_URL is not a valid URL" };
+  }
+  if (u.username || u.password) {
+    return { ok: false, error: "AGENCY_BACKEND_URL must not embed credentials" };
+  }
+  const host = u.hostname.toLowerCase();
+  const loopback =
+    host === "localhost" ||
+    host === "127.0.0.1" ||
+    host === "::1" ||
+    host === "[::1]";
+  if (u.protocol === "https:") {
+    return { ok: true, url: `${u.origin}${u.pathname}`.replace(/\/$/, "") || u.origin };
+  }
+  if (u.protocol === "http:" && loopback) {
+    return { ok: true, url: `${u.origin}${u.pathname}`.replace(/\/$/, "") || u.origin };
+  }
+  return {
+    ok: false,
+    error: "AGENCY_BACKEND_URL must use https (http allowed only for localhost)",
+  };
+}
+
 export const ALLOWED_WRITE_TOOLS = [
   "ah_lead_create",
   "ah_client_create",
@@ -202,6 +268,10 @@ export function createRateLimiter({ maxPerMinute = 120 } = {}) {
 }
 
 export function createApi(env) {
+  const urlCheck = assertSafeBackendUrl(env.AGENCY_BACKEND_URL);
+  if (!urlCheck.ok) {
+    throw new Error(urlCheck.error);
+  }
   const headers = { "x-api-key": env.AGENCY_BACKEND_API_KEY };
   const companyId =
     env.AGENCY_COMPANY_ID || companyIdFromApiKey(env.AGENCY_BACKEND_API_KEY);
@@ -210,9 +280,10 @@ export function createApi(env) {
 
   const timeout = Number(env.AGENCY_BACKEND_TIMEOUT_MS) || 45_000;
   const client = axios.create({
-    baseURL: env.AGENCY_BACKEND_URL.replace(/\/$/, ""),
+    baseURL: urlCheck.url,
     headers,
     timeout,
+    maxRedirects: 0,
     // Keep 4xx/5xx as resolved responses so callers can map status → ok.
     validateStatus: (s) => s >= 200 && s < 600,
   });
@@ -268,7 +339,21 @@ export function withWs(base = {}, ws = null) {
   return ws ? { ...base, workspaceId: ws } : { ...base };
 }
 
+function rejectUnsafePath(pathname) {
+  const check = assertSafeBackendPath(pathname);
+  if (check.ok) return null;
+  logEvent("error", "backend_path_rejected", { path: String(pathname), error: check.error });
+  return {
+    ok: false,
+    path: pathname,
+    status: null,
+    message: check.error,
+  };
+}
+
 export async function backendGet(api, pathname, query = {}) {
+  const rejected = rejectUnsafePath(pathname);
+  if (rejected) return rejected;
   const started = Date.now();
   try {
     const { data, status } = await api.get(pathname, {
@@ -302,6 +387,8 @@ export async function backendGet(api, pathname, query = {}) {
 }
 
 export async function backendPost(api, pathname, body, query = {}) {
+  const rejected = rejectUnsafePath(pathname);
+  if (rejected) return rejected;
   const started = Date.now();
   try {
     const { data, status } = await api.post(pathname, body, {
@@ -334,6 +421,8 @@ export async function backendPost(api, pathname, body, query = {}) {
 }
 
 export async function backendDelete(api, pathname, body, query = {}) {
+  const rejected = rejectUnsafePath(pathname);
+  if (rejected) return rejected;
   const started = Date.now();
   try {
     const { data, status } = await api.delete(pathname, {
@@ -368,6 +457,8 @@ export async function backendDelete(api, pathname, body, query = {}) {
 }
 
 export async function backendPut(api, pathname, body, query = {}) {
+  const rejected = rejectUnsafePath(pathname);
+  if (rejected) return rejected;
   const started = Date.now();
   try {
     const { data, status } = await api.put(pathname, body, {

package/src/ownerInsights.js

@@ -42,6 +42,12 @@ function amountOf(invoice) {
   return Number.isFinite(n) ? n : 0;
 }
 
+function solidRows(list) {
+  return (Array.isArray(list) ? list : []).filter(
+    (row) => row != null && typeof row === "object" && !Array.isArray(row)
+  );
+}
+
 /**
  * Cash at risk: open invoices aged into buckets + top clients by amount due.
  */
@@ -53,7 +59,9 @@ export async function buildCashRisk(api, { limit, ws, backendGet, withWs }) {
     "/api/v1/invoices",
     withWs({ status: "open", limit: fetchLimit, skip: 0 }, ws)
   );
-  const rows = pickList(invoicesRes, ["invoices", "docs", "items", "results"]);
+  const rows = solidRows(
+    pickList(invoicesRes, ["invoices", "docs", "items", "results"])
+  );
   const summarized = rows.map((row) => {
     const s = summarizeInvoice(row) || {};
     const dueDays = daysSince(s.dueDate || row.dueDate, now);
@@ -159,13 +167,15 @@ export async function buildProposalPipeline(
     "/api/v1/quotations",
     withWs({ page: 1, limit: Math.min(Math.max(limit * 4, 40), 100), sortBy: "updatedAt", order: "desc" }, ws)
   );
-  const rows = pickList(proposalsRes, [
-    "quotations",
-    "proposals",
-    "docs",
-    "items",
-    "results",
-  ]);
+  const rows = solidRows(
+    pickList(proposalsRes, [
+      "quotations",
+      "proposals",
+      "docs",
+      "items",
+      "results",
+    ])
+  );
 
   const items = rows.map((row) => {
     const s = summarizeProposal(row) || {};
@@ -242,19 +252,21 @@ export async function buildLeadSegments(
     backendGet(api, "/api/v1/custom-fields", withWs({ type: "lead" }, ws)),
   ]);
 
-  const leads = pickList(leadsRes, [
-    "acceptedMembers",
-    "members",
-    "docs",
-    "items",
-    "results",
-  ]);
-  const fieldDefs = (() => {
+  const leads = solidRows(
+    pickList(leadsRes, [
+      "acceptedMembers",
+      "members",
+      "docs",
+      "items",
+      "results",
+    ])
+  );
+  const fieldDefs = solidRows((() => {
     const data = unwrap(fieldsRes);
     if (Array.isArray(data?.leadCustomFields)) return data.leadCustomFields;
     if (Array.isArray(data)) return data;
     return pickList(fieldsRes, ["leadCustomFields", "docs", "items"]);
-  })();
+  })());
 
   const byStatus = {};
   const bySource = {};
@@ -382,15 +394,21 @@ export async function buildClientChurnRisk(
     ),
   ]);
 
-  const clients = pickList(clientsRes, [
-    "acceptedMembers",
-    "members",
-    "docs",
-    "items",
-    "results",
-  ]);
-  const invoices = pickList(invoicesRes, ["invoices", "docs", "items", "results"]);
-  const orders = pickList(ordersRes, ["orders", "docs", "items", "results"]);
+  const clients = solidRows(
+    pickList(clientsRes, [
+      "acceptedMembers",
+      "members",
+      "docs",
+      "items",
+      "results",
+    ])
+  );
+  const invoices = solidRows(
+    pickList(invoicesRes, ["invoices", "docs", "items", "results"])
+  );
+  const orders = solidRows(
+    pickList(ordersRes, ["orders", "docs", "items", "results"])
+  );
 
   const unpaidByClient = new Map();
   for (const inv of invoices) {

package/src/prompts.js

@@ -76,12 +76,13 @@ export function getPrompt(name, args = {}) {
             type: "text",
             text: `Read MCP resource ah://full-context (preferred single read).
 If the host cannot load the bundle, read in order:
-ah://glossary → ah://models → ah://fields → ah://workflows → ah://workflows-platform → ah://usage → ah://tool-guide → ah://response-shape
+ah://glossary → ah://models → ah://fields → ah://workflows → ah://workflows-platform → ah://api-context → ah://usage → ah://tool-guide → ah://response-shape
 
 Then confirm:
 - proposal=quotation, project=order(pid), ticket=task type=issue
+- leads live under /members (bulk-lead, isConvertedClient=false); never PUT /accounts/update without accountId
 - Core delivery workflows (A–O) plus platform/ops (P–CC): auth, email-to-ticket, chat, webhooks, subscriptions
-- Field meanings from ah://fields
+- Field meanings from ah://fields; path/permission gotchas from ah://api-context
 - Prefer *_context tools; never invent ObjectIds
 - People by name: ah_member_resolve first (unique|ambiguous|none). If ambiguous, ask user. Never guess.
 - Status by label: ah_status_resolve first. Same rule.

package/src/resources.js

@@ -9,7 +9,7 @@ export const RESOURCES = [
     name: "Full Agency Handy MCP context (bundle)",
     mimeType: "text/markdown",
     description:
-      "Single bundle: glossary, models, fields, product + platform workflows, usage, tools.",
+      "Single bundle: glossary, models, fields, product + platform workflows, API builder context, usage, tools.",
   },
   {
     uri: "ah://glossary",
@@ -68,6 +68,13 @@ export const RESOURCES = [
     mimeType: "text/markdown",
     description: "How to interpret ok/status/data from ah_* tools.",
   },
+  {
+    uri: "ah://api-context",
+    name: "API builder context (gotchas)",
+    mimeType: "text/markdown",
+    description:
+      "Missing/ambiguous API context for MCP builders: leads, orders, tasks, comments, invoices, forms, webhooks, permissions.",
+  },
 ];
 
 function md(uri, text) {
@@ -88,6 +95,7 @@ const GLOSSARY = `# Agency Handy glossary
 | Client company | ClientCompany | \`/api/v1/client-companies\` | B2B org |
 | Form | Form / PublicForm | \`/forms\`, \`/public-forms\` | Intake → lead/order |
 | Comment | Comment / QuotationComment | \`/comments\`, \`/quotation-comments\` | Different namespaces |
+| Lead | Member (client role, not converted) | \`/members\` + \`bulk-lead\` | **No** \`/leads\` mount — see \`ah://api-context\` |
 | Time entry | TimeTracker | \`/time-trackers\` | \`taskId\` / \`projectId\` |
 | Task status | TaskStatus | \`/taskStatus\` | Board lane ObjectIds |
 | Company | Company | \`/company\` | Workspace tenant |
@@ -96,6 +104,7 @@ const GLOSSARY = `# Agency Handy glossary
 | Dashboard | Dashboard | \`/dashboards\` | Aggregates |
 
 Auth: \`x-api-key\` (member API token). Optional \`AGENCY_WORKSPACE_ID\`.
+Read **\`ah://api-context\`** for path renames, permission names, and write-side gotchas.
 `;
 
 const MODELS = `# Domain models & relationships
@@ -134,6 +143,7 @@ Company (workspace)
 - **Ticket vs Task**: same collection; filter/list with \`type=issue\` vs \`type=task\`.
 - **Project vs Order**: UI "Project" = API \`orders\` = tool \`pid\`.
 - **Proposal vs Quotation**: UI "Proposal" = API \`quotations\`.
+- **Lead vs Client vs Team**: same \`Member\` collection — lead = client role + \`isConvertedClient=false\`; client = converted; team = non-client role.
 - **Human ids**: \`taskId\`, order \`id\`/\`customId\`/\`prefix\` are display ids — MCP tools need Mongo \`_id\`.
 
 ## ID args for tools
@@ -679,7 +689,7 @@ If only tools: \`ah_ping\` → use \`forAnyLlm\`; still call \`ah_*_context\`.
 
 ## Startup (every model)
 1. \`ah_ping\`
-2. Read \`ah://full-context\` OR (\`ah://models\` + \`ah://fields\` + \`ah://workflows\` + \`ah://workflows-platform\` + \`ah://usage\`)
+2. Read \`ah://full-context\` OR (\`ah://models\` + \`ah://fields\` + \`ah://workflows\` + \`ah://workflows-platform\` + \`ah://api-context\` + \`ah://usage\`)
 3. One context pack / investigate prompt
 4. Filtered lists before more gets
 
@@ -691,6 +701,7 @@ If only tools: \`ah_ping\` → use \`forAnyLlm\`; still call \`ah_*_context\`.
 - Billing → \`ah_invoice_list\` → \`ah_invoice_context\`
 - Board → \`ah_task_statuses\` then filtered \`ah_task_list\` / \`ah_ticket_list\`
 - Email-created ticket / chat / webhooks → \`ah://workflows-platform\` then ticket/project tools
+- Path / permission / lead confusion → \`ah://api-context\`
 
 ## Token hygiene
 - Prefer \`*_context\` (1 call) over 3–5 gets
@@ -701,9 +712,10 @@ If only tools: \`ah_ping\` → use \`forAnyLlm\`; still call \`ah_*_context\`.
 ## Anti-patterns
 - Inventing ObjectIds
 - Ticket id as \`pid\`
-- Writes (MCP is read-oriented)
-- Company-wide task list when \`pid\` known → use \`ah_project_tasks\`
+- Calling stale OpenAPI paths (\`/projects\`, \`/company/.../members\`)
+- \`PUT /accounts/update\` without \`accountId\` (updates API-key owner)
 - Mixing \`type=issue\` / \`type=task\`
+- Treating \`/subscriptions\` as client order-subscriptions
 `;
 
 const TOOL_GUIDE = `# Tool selection
@@ -760,7 +772,7 @@ const MODULES = `# Modules
 | Platform SaaS sub | \`ah_platform_subscription_list\` | subscriptions/list |
 | Meta | \`ah_ping\` | local |
 
-Resources: full-context, glossary, models, fields, workflows, workflows-platform, usage, tool-guide, modules, response-shape.
+Resources: full-context, glossary, models, fields, workflows, workflows-platform, usage, tool-guide, modules, response-shape, api-context.
 Prompts: orientation + investigate_*.
 `;
 
@@ -803,6 +815,126 @@ Zod argument errors: \`{ ok:false, error:"Invalid tool arguments", details:[...]
 Config errors: \`Invalid MCP server environment variables\`.
 `;
 
+const API_CONTEXT = `# API builder context (missing / easy-to-miss)
+
+Use this when mapping product tools to live Agency Handy HTTP APIs, or when OpenAPI and runtime disagree. Prefer \`ah_*\` tools when available — this doc is the ground truth for paths and gotchas.
+
+## Cross-cutting
+- Live base: \`/api/v1/*\`. OpenAPI often still shows stale \`/projects/*\` and \`/company/{id}/members/*\` — **do not call those**.
+- Auth: \`x-api-key\` **or** bearer — never both. API key JWT sets company from claims.
+- Many deletes are **PUT + id array**, not HTTP DELETE (\`/tasks\`, \`/invoices\`, \`/quotations\`, \`/vouchers\`, \`/webhooks\`, \`/orders/delete\`, \`/members/bulk-delete\`).
+- Pagination: orders/invoices/tasks often \`skip\`+\`limit\`; quotations use \`page\`+\`limit\`.
+- 403 \`PermissionError\` ("Restricted - No permission…") = missing **permission name** on the API-key member role — not a broken token.
+- Subscription expired: key still authenticates; routes with \`subscriptionExpireCheck\` return 403 \`SubscriptionExpirationError\` after grace.
+
+## Leads (no \`/leads\` API)
+- Leads are \`Member\` rows: client role + \`isConvertedClient=false\` (same collection as team/clients).
+- Create: \`POST /members/bulk-lead\` (not \`/members\` or \`/members/bulk\`).
+- List: \`GET /members?isConvertedClient=false\` (+ optional pipeline \`status\`).
+- Update / convert: \`PUT /accounts/update\` with **required \`accountId\`**.
+- **Without \`accountId\`**, update targets the **API-key owner** (can rename the token user).
+- Delete: \`PUT /members/bulk-delete\`.
+- Custom fields: \`/custom-fields?type=lead\` (separate from \`client\` / \`task\`).
+- Pipeline statuses: \`New | Contacted | Qualified | Working | Proposal Sent | Negotiation\`.
+- Permissions: \`addNewMemberToCompany\`, \`getEmployeeDirectory\`. Plan may return \`Lead limit reached\`.
+- MCP: \`ah_lead_create\`, \`ah_lead_convert\`, \`ah_member_update\` (always pass account/member id).
+
+## Orders / Projects
+- UI Project = \`/orders\` only (not \`/projects\`).
+- Get: \`GET /orders/:pid\`. Update: \`PUT /orders?pid=\` (query \`pid\` required).
+- Status enum (title case): \`Pending | Ongoing | Review | Completed | Cancelled | Payment Failed\`.
+- Client accept/reject: \`PUT /orders/:pid/actions\` with \`orderStatus: accept|reject\` — not the same as agency status PUT.
+- Create needs \`service\`, \`packageId\`, \`packageName\`, \`clientTargetType\`, \`paymentType\` (\`oneTime|subscription\`), plus \`clientId\` **or** (\`clientCompanyId\` + \`sentToClientIds\`).
+- Soft delete: \`PUT /orders/delete\`.
+
+## Tasks / tickets / statuses
+- Board tickets = \`Task\` with \`type=issue\` via \`/company/all-tasks?type=issue|task\` — **not** the legacy \`/tickets\` collection.
+- List/filter \`status\` = TaskStatus **ObjectId(s)**. Update \`PUT /tasks/:taskId\` \`status\` = **status name string** (controller resolves name → id). Passing ObjectId on update fails.
+- Complete: \`PUT /tasks/mark-as-completed\` (needs \`_id\`, \`pid\`, \`memberId\`, \`assingedPersons\` — typo is real). Not the same as status \`done\`.
+- OpenAPI \`POST /tasks/{id}/subtask\` and \`PATCH /tasks/{id}/reopen\` are **not mounted**. Reopen ≈ \`PUT\` with \`status: open\` on closed issues (limited). Subtasks = model \`type=subTask\` only — no external create route.
+- Create requires \`name\`, \`priority\` (0–4), \`labels[]\` (required, may be \`[]\`), \`type\`; \`client\` required unless visibility \`internal|order\`.
+- Permissions: \`updateTask\`, \`deleteTask\`; tickets delete via \`deleteTicket\` / \`PUT /tasks/delete-ticket\`.
+- \`GET /taskStatus\` returns all types — filter \`type\` (\`task\` vs \`issue\`) client-side.
+
+## Assignment
+- Add: \`POST /tasks/member/:taskId\` body \`{ assignmembers: [memberIds] }\`.
+- Remove: \`PUT /tasks/member/:taskId\` body \`{ assignedMemberIds: [...] }\` — **different field name**.
+- IDs are workspace **member** ObjectIds, not emails. Resolve with \`ah_member_resolve\`.
+- Order PMs: \`assignedProjectManagers\` on \`PUT /orders?pid=\`, not task member endpoints.
+
+## Comments
+- Task/ticket: \`/comments\` — create needs \`text\`, \`type\` (\`agencyComment|clientComment|…\`), \`taskId\`, and query **\`memberId\` required**.
+- Update: \`POST /comments/:commentId/update\` (not PUT).
+- Proposal comments: separate \`/quotation-comments\` — do not reuse \`/comments\`.
+- \`agencyComment\` vs \`clientComment\` controls portal visibility.
+
+## Labels
+- Company catalog create: \`POST /labels/create-for-company\`; suggest: \`GET /labels/suggest-by-company\`.
+- \`POST /labels/\` is **task-scoped** (requires task id) — not global create.
+- Attach/detach: \`/labels/task/:task\`, bulk \`/labels/bulk/:taskId\`.
+
+## Clients / members / groups
+- Live path: \`/members\` (not OpenAPI \`/company/{COMPANY_ID}/members\`).
+- List permission: \`getEmployeeDirectory\`. \`type\` is \`individual|company|leadCompanyMember\` — not \`client\`/\`lead\`. Role filter is a role ObjectId. \`tab=client|team\` only on \`/members/basic\`.
+- Invite: \`POST /members/send-client-invite\`. Bulk team \`/members/bulk\`, bulk client \`/members/bulk-client\`, bulk lead \`/members/bulk-lead\`.
+- Soft delete: \`PUT /members/bulk-delete\` (+ optional async poll).
+- Client companies: \`/client-companies\` (B2B org ids) ≠ individual client members — orders/invoices need the right \`clientTargetType\`.
+- Groups: \`/client-groups\` (hard DELETE on group id).
+
+## Invoices
+- Mount: \`/invoices\`. Permissions: \`getInvoice\`, \`createInvoice\`, \`updateInvoice\`, \`deleteInvoice\`.
+- Status: \`draft | open | paid | void | uncollectable\` (+ processing in places).
+- Resend: \`PUT /invoices/resend\`. Public: \`/invoices/public/:id\`. Delete: \`PUT /invoices\` + ids.
+- Create: \`currency\` + one of \`client\` | \`externalEmail\` | \`clientCompanyId\`; line items via \`additionalFields\` when required.
+
+## Proposals / quotations
+- UI Proposal = \`/quotations\` always.
+- Permissions: \`createQuotation\`, \`updateQuotation\`, \`deleteQuotation\`.
+- Recipient: \`clientId\` **or** \`leadId\` **or** external email object.
+- Send: \`PUT /quotations/send/:id\`. Accept/reject: \`/accept/:id\`, \`/reject/:id\`. Public: \`/quotations/public/:id\`.
+- \`acceptAction\`: \`doNothing | createOrder | createOrderAndInvoice\` — accept can spawn order/invoice.
+- Pagination: \`page\` (min 1) + \`limit\`.
+
+## Services & packages
+- No \`/packages\` resource — packages nested on \`/services\`.
+- Order create needs both \`packageId\` and \`packageName\` + parent \`service\` id.
+- Permissions: \`createService\`, \`updateService\`, \`deleteService\`. Catalog: \`/services/catalog\`.
+
+## Vouchers
+- Admin CRUD permissions: \`createVoucher\`, \`getVouchers\`, \`getVoucher\`, \`updateVoucher\`, \`deleteVoucher\`.
+- \`POST /vouchers/apply\` is **unauthenticated checkout** (\`code\`, \`email\`, \`serviceId\`, \`packageId\`, \`quantity\`) — not admin CRUD.
+- Delete: \`PUT /vouchers\` + \`voucherIds[]\`.
+
+## Webhooks
+- Event ids on create come from \`GET /webhooks/events/list\` (ObjectIds), not free-form strings.
+- Delete: \`PUT /webhooks\` + \`webhookIds[]\`. Logs: \`GET /webhooks/logs\`; attempts under \`/logs/:id/attempts\`.
+- Auth configs (\`/webhook-auths\`) are separate from webhook URL rows.
+
+## Forms
+- Three surfaces: agency \`/forms\`, share \`/forms/share/:formId\` + \`/forms/public/:shareToken/respond\`, and \`/public-forms\`.
+- Agency submit: \`POST /forms/respond\` (and \`respond-update\`).
+- \`GET /forms/:formId\` auth may be open — treat payload as potentially public-facing.
+
+## System
+- Notifications \`GET /notifications\` = **caller inbox only**, not company-wide.
+- Custom fields types: \`task|client|lead\`; mutate often admin/superAdmin only; values via \`/custom-fields/respond\` with \`resourceId\`.
+- Roles: permission **camelCase names** from \`GET /roles/permissions\` (\`createOrder\`, \`getInvoice\`, \`addNewMemberToCompany\`, …).
+- Email templates \`/email-templates\` ≠ builder \`/email-template-builder\`.
+- \`/order-subscriptions\` = client recurring orders. \`/subscriptions\` = Agency Handy **SaaS** plan for the workspace — never mix them.
+
+## Highest-risk misunderstandings
+1. \`/projects\` vs \`/orders\`
+2. Proposal vs \`/quotations\`
+3. Board ticket vs legacy \`/tickets\`
+4. Status **name on write** / **ObjectId on list**
+5. OpenAPI subtask/reopen routes not mounted
+6. \`PUT /accounts/update\` without \`accountId\`
+7. Permission camelCase names → 403 "security"
+8. PUT-as-delete
+9. \`/subscriptions\` vs \`/order-subscriptions\`
+10. Leads sharing \`/members\` without \`isConvertedClient=false\`
+`;
+
 const CONTENT = {
   "ah://glossary": GLOSSARY,
   "ah://models": MODELS,
@@ -813,6 +945,7 @@ const CONTENT = {
   "ah://tool-guide": TOOL_GUIDE,
   "ah://modules": MODULES,
   "ah://response-shape": RESPONSE_SHAPE,
+  "ah://api-context": API_CONTEXT,
 };
 
 export function readResource(uri) {
@@ -837,6 +970,8 @@ export function readResource(uri) {
       MODULES,
       "---",
       RESPONSE_SHAPE,
+      "---",
+      API_CONTEXT,
     ].join("\n");
     return md(uri, text);
   }

package/src/server.js

@@ -16,6 +16,7 @@ import {
 import {
   VERSION,
   asText,
+  assertSafeBackendUrl,
   createApi,
   createRateLimiter,
   logEvent,
@@ -56,6 +57,14 @@ if (!envResult.success) {
 }
 
 const env = envResult.data;
+const urlCheck = assertSafeBackendUrl(env.AGENCY_BACKEND_URL);
+if (!urlCheck.ok) {
+  logEvent("error", "backend_url_invalid", { error: urlCheck.error });
+  process.stderr.write(`[agencyhandy-mcp] ${urlCheck.error}\n`);
+  process.exit(1);
+}
+env.AGENCY_BACKEND_URL = urlCheck.url;
+
 const strictKey =
   env.AGENCY_MCP_STRICT_API_KEY === "1" ||
   env.NODE_ENV === "production";

package/src/tools.js

@@ -761,6 +761,7 @@ export async function handleTool(name, args, ctx) {
           "ah://fields",
           "ah://workflows",
           "ah://workflows-platform",
+          "ah://api-context",
           "ah://usage",
           "ah://tool-guide",
           "ah://modules",