agencyhandy-mcp 1.4.0

package/.env.example

@@ -0,0 +1,13 @@
+# Production MCP — copy to .env and fill from Agency Handy UI
+# Settings → API tokens (member API key / x-api-key JWT)
+
+AGENCY_BACKEND_URL=https://api.agencyhandy.com
+AGENCY_BACKEND_API_KEY=
+
+# Optional overrides
+# AGENCY_COMPANY_ID=                 # normally decoded from API key JWT
+# AGENCY_WORKSPACE_ID=
+# AGENCY_BACKEND_TIMEOUT_MS=45000
+# AGENCY_MCP_MAX_RPM=120             # in-process tool call rate limit
+# AGENCY_MCP_STRICT_API_KEY=1        # require JWT exp (default on when NODE_ENV=production)
+# NODE_ENV=production

package/PRODUCTION.md

@@ -0,0 +1,31 @@
+# Production checklist — Agency Handy MCP
+
+npm package name: **`agencyhandy-mcp`**  
+Repo: https://github.com/AgencyHandy/agency-backend-mcp
+
+## End-user flow
+
+1. Agency Handy → **Workspace Config → API Key** → Generate  
+2. Copy MCP config (key filled in once)  
+3. Paste into Cursor `.mcp.json` or Claude Desktop config  
+4. Restart host (Node.js 20+)
+
+## Ship checklist
+
+1. Push this repo to GitHub  
+2. `npm publish --access public` (so `npx -y agencyhandy-mcp@1` works)  
+3. Merge/deploy ah-client PR that shows the MCP copy UI on the API Key tab  
+
+## Runtime guarantees
+
+- Fail fast on missing / placeholder / expired API keys  
+- Stderr JSON audit logs (stdout = MCP protocol only)  
+- Secret redaction, rate limit (120 RPM), one retry on 502/503  
+- `companyid` from JWT; `ah_health` probes backend  
+- Writes allowlisted: CRM, work assign/status, invoices (+send), proposals, orders (create/update/assign)
+- Owner digest: `ah_dashboard_digest`
+- Resolve-only ids: `ah_member_resolve`, `ah_status_resolve` (no invented ObjectIds)
+
+## Version
+
+`1.4.0` — DB-backed member/status resolve; assign/status writes require real ids.

package/README.md

@@ -0,0 +1,239 @@
+# Agency Handy MCP
+
+Official [Model Context Protocol](https://modelcontextprotocol.io) server for **Agency Handy**.
+
+Connect Claude Desktop, Cursor, or any MCP host to your Agency Handy workspace: inspect proposals, projects, tickets, invoices, and create leads & clients — using your existing workspace API key.
+
+| | |
+|---|---|
+| **npm** | `agencyhandy-mcp` (publish after this repo is set up) |
+| **Node** | ≥ 20 |
+| **Auth** | Workspace API key (`x-api-key`) from Agency Handy |
+| **API** | Your Agency Handy backend (`AGENCY_BACKEND_URL`) |
+
+---
+
+## Quick start (Agency Handy users)
+
+1. In Agency Handy go to **Workspace Config → API Key**
+2. **Generate** a key (or use one you already saved)
+3. **Copy MCP config** from that page (or use the JSON below)
+4. Paste into:
+   - **Cursor:** project or user `.mcp.json`
+   - **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+5. Restart the host. Requires **Node.js 20+**.
+
+```json
+{
+  "mcpServers": {
+    "agency-handy": {
+      "command": "npx",
+      "args": ["-y", "agencyhandy-mcp@1"],
+      "env": {
+        "NODE_ENV": "production",
+        "AGENCY_BACKEND_URL": "https://api.agencyhandy.com",
+        "AGENCY_BACKEND_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+> Prefer the in-app config: it fills the correct API base URL for your environment (production, staging, etc.).
+
+Until the package is on npm, developers can run from this repo:
+
+```json
+{
+  "mcpServers": {
+    "agency-handy": {
+      "command": "node",
+      "args": ["/absolute/path/to/agency-backend-mcp/src/server.js"],
+      "env": {
+        "AGENCY_BACKEND_URL": "https://api.agencyhandy.com",
+        "AGENCY_BACKEND_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+---
+
+## What you can do
+
+### Product naming → API
+
+| In Agency Handy | Backend |
+|-----------------|---------|
+| Proposal | Quotations |
+| Project | Orders (`pid`) |
+| Ticket | Tasks with `type=issue` |
+| Task | Tasks with `type=task` |
+
+### Write tools
+
+| Tool | Purpose |
+|------|---------|
+| `ah_lead_create` | Create lead(s) — `POST /api/v1/members/bulk-lead` |
+| `ah_client_create` | Create client(s) — `POST /api/v1/members/bulk-client` |
+| `ah_client_company_create` | Create client company — `POST /api/v1/client-companies` |
+| `ah_member_update` | Update lead/client — `PUT /api/v1/accounts/update` |
+| `ah_lead_convert` | Convert lead → client — `PUT /api/v1/accounts/update` |
+| `ah_client_invite` | Send portal invite — `POST /api/v1/members/send-client-invite` |
+| `ah_ticket_create` / `ah_ticket_update` | Ticket (`type=issue`) — `POST/PUT /api/v1/tasks` |
+| `ah_task_create` / `ah_task_update` | Task (`type=task`) — `POST/PUT /api/v1/tasks` |
+| `ah_comment_create` | Comment on ticket/task — `POST /api/v1/comments` |
+| `ah_invoice_create` / `ah_invoice_update` | Invoice — `POST/PUT /api/v1/invoices` |
+| `ah_proposal_create` / `ah_proposal_update` | Proposal — `POST/PUT /api/v1/quotations` |
+| `ah_proposal_send` | Send proposal — `PUT /api/v1/quotations/send/:id` |
+| `ah_order_update` | Update order — `PUT /api/v1/orders?pid=` |
+| `ah_order_create` | Create order from service package — `POST /api/v1/orders/create` |
+| `ah_order_assign` | Set order PMs — `PUT /orders?pid=` |
+| `ah_invoice_send` | Send/resend invoice email — open status or `/invoices/resend` |
+| `ah_invoice_set_status` | Mark paid/void/open/… — `PUT /invoices/:id` |
+| `ah_work_assign` | Add/remove ticket or task assignees |
+| `ah_work_set_status` | Move ticket/task board status |
+
+**Owner digest (read)**
+
+| Tool | Purpose |
+|------|---------|
+| `ah_dashboard_digest` | Morning briefing: open invoices, overdue work, new leads + dashboard |
+| `ah_member_resolve` | Name/email → DB memberId (`unique` / `ambiguous` / `none`) — never invent ids |
+| `ah_status_resolve` | Status label → DB statusId — required before `ah_work_set_status` |
+
+**Resolve rule:** If `ambiguous` or `none`, ask the user. Only assign/update with an id returned from these tools (or a user-confirmed match).
+
+**Lead example**
+
+```json
+{
+  "email": "lead@acme.com",
+  "firstName": "Ada",
+  "lastName": "Lovelace",
+  "status": "New",
+  "sendInvitationEmail": false
+}
+```
+
+**Client example**
+
+```json
+{
+  "email": "client@acme.com",
+  "firstName": "Ada",
+  "sendInvitationEmail": false
+}
+```
+
+**Client company example**
+
+```json
+{
+  "name": "Acme Inc",
+  "ownerId": "<existing-member-id>",
+  "city": "Dhaka"
+}
+```
+
+**Ticket example**
+
+```json
+{
+  "name": "Portal login broken",
+  "priority": "high",
+  "labels": [],
+  "client": "<client-member-id>",
+  "visibility": "client"
+}
+```
+
+**Invoice example**
+
+```json
+{
+  "currency": "usd",
+  "client": "<client-member-id>",
+  "amount": 500,
+  "additionalFields": [{ "name": "Design", "quantity": 1, "value": 500 }]
+}
+```
+
+Order create is intentionally omitted (multipart / service-package heavy). Use `ah_order_update` for existing orders.
+
+### Read tools (highlights)
+
+- **Health:** `ah_ping`, `ah_health`
+- **Context packs:** `ah_proposal_context`, `ah_project_context`, `ah_ticket_context`, `ah_task_context`, `ah_invoice_context`, `ah_chat_context`, `ah_webhook_context`
+- **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.
+
+### Resources & prompts
+
+Resources: `ah://full-context`, `ah://glossary`, `ah://models`, `ah://fields`, `ah://workflows`, `ah://workflows-platform`, `ah://usage`, …
+
+Prompts: `agency_handy_orientation`, `investigate_ticket`, `investigate_project`, `investigate_proposal`, `investigate_task`
+
+---
+
+## Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AGENCY_BACKEND_URL` | yes | API origin, e.g. `https://api.agencyhandy.com` (no `/api/v1` suffix) |
+| `AGENCY_BACKEND_API_KEY` | yes | Member API JWT from Workspace Config → API Key |
+| `AGENCY_COMPANY_ID` | no | Override; normally taken from the JWT `company` claim |
+| `AGENCY_WORKSPACE_ID` | no | Optional workspace hint for tools that accept it |
+| `AGENCY_BACKEND_TIMEOUT_MS` | no | Default `45000` |
+| `AGENCY_MCP_MAX_RPM` | no | Tool rate limit per process (default `120`) |
+| `AGENCY_MCP_STRICT_API_KEY` | no | `1` to require JWT `exp`; on by default when `NODE_ENV=production` |
+| `NODE_ENV` | no | Set `production` for hosts |
+
+Copy `.env.example` → `.env` for local development.
+
+---
+
+## Develop
+
+```bash
+git clone https://github.com/AgencyHandy/agency-backend-mcp.git
+cd agency-backend-mcp
+npm ci
+cp .env.example .env   # fill URL + API key
+npm start              # stdio MCP server
+npm test               # offline smoke / production gate
+npm run test:live      # strict live calls (backend must be reachable)
+```
+
+### CI
+
+GitHub Actions runs offline smoke on Node 20 (`.github/workflows/ci.yml`).
+
+### Publish to npm
+
+```bash
+npm ci
+npm test
+npm publish --access public
+```
+
+See [PRODUCTION.md](./PRODUCTION.md) for the operator checklist.
+
+---
+
+## Security
+
+- The API key is a **full workspace credential** — treat it like a password
+- Never commit `.env` or paste keys into public chats
+- Rotate keys in Agency Handy if leaked
+- MCP is **stdio / local-trust**; do not expose it on a public network without extra auth
+- Allowed writes are limited to lead / client / client-company create
+
+---
+
+## License
+
+UNLICENSED — Agency Handy proprietary.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agencyhandy-mcp",
+  "version": "1.4.0",
+  "description": "Official Agency Handy MCP server — DB-backed resolve + owner ops (no invented ids)",
+  "type": "module",
+  "main": "src/server.js",
+  "bin": {
+    "agencyhandy-mcp": "src/server.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "PRODUCTION.md",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js",
+    "test": "node scripts/smoke.mjs",
+    "test:live": "SMOKE_LIVE=1 node scripts/smoke.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "agencyhandy",
+    "mcp",
+    "claude",
+    "cursor",
+    "model-context-protocol"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.3",
+    "axios": "^1.9.0",
+    "dotenv": "^16.5.0",
+    "zod": "^3.24.4"
+  }
+}