agencyhandy-mcp 1.7.1 → 1.7.2

package/PRODUCTION.md

@@ -28,5 +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

@@ -209,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.1",
-  "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,8 +19,9 @@
   "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 && node scripts/unit-security-mutate.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 && npm audit --audit-level=high"

package/src/lib.js

@@ -1,7 +1,7 @@
 import axios from "axios";
 import { z } from "zod";
 
-export const VERSION = "1.7.1";
+export const VERSION = "1.7.2";
 
 export const READ_ONLY = false;
 

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/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",