@procurementexpress.com/mcp 1.0.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/skills/bump-version/SKILL.md +77 -0
- package/.claude/skills/commit/SKILL.md +73 -0
- package/.claude/skills/npm-publish/SKILL.md +65 -0
- package/.claude/skills/pex-approval-flows/SKILL.md +122 -0
- package/.claude/skills/pex-approval-flows/references/conditions.md +90 -0
- package/.claude/skills/pex-auth/SKILL.md +80 -0
- package/.claude/skills/pex-budgets/SKILL.md +73 -0
- package/.claude/skills/pex-companies/SKILL.md +113 -0
- package/.claude/skills/pex-departments/SKILL.md +61 -0
- package/.claude/skills/pex-invoices/SKILL.md +125 -0
- package/.claude/skills/pex-invoices/references/line-items.md +55 -0
- package/.claude/skills/pex-payments/SKILL.md +79 -0
- package/.claude/skills/pex-purchase-orders/SKILL.md +167 -0
- package/.claude/skills/pex-purchase-orders/references/line-items.md +53 -0
- package/.claude/skills/pex-purchase-orders/references/workflows.md +74 -0
- package/.claude/skills/pex-settings/SKILL.md +128 -0
- package/.claude/skills/pex-suppliers/SKILL.md +113 -0
- package/README.md +118 -25
- package/dist/api-client.d.ts +1 -0
- package/dist/api-client.js +3 -0
- package/dist/tools/approval-flows.js +130 -25
- package/dist/tools/budgets.js +30 -20
- package/dist/tools/comments.js +4 -4
- package/dist/tools/companies.js +57 -7
- package/dist/tools/departments.js +6 -6
- package/dist/tools/invoices.js +100 -31
- package/dist/tools/payments.js +45 -13
- package/dist/tools/products.js +10 -5
- package/dist/tools/purchase-orders.js +178 -35
- package/dist/tools/supplementary.js +57 -14
- package/dist/tools/suppliers.js +38 -19
- package/dist/tools/tax-rates.js +15 -9
- package/dist/tools/users.js +8 -5
- package/dist/tools/webhooks.js +59 -9
- package/package.json +5 -4
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# PO Workflows
|
|
2
|
+
|
|
3
|
+
## Create and Submit a PO
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
1. get_current_user → get creator_id
|
|
7
|
+
2. list_departments → pick department_id
|
|
8
|
+
3. list_suppliers or get_top_suppliers → pick supplier_id
|
|
9
|
+
4. list_budgets (filter by department_id) → pick budget_id for line items
|
|
10
|
+
5. list_currencies → confirm currency_id (optional)
|
|
11
|
+
6. create_purchase_order with commit="Send", creator_id, supplier_id, line_items
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Create a Draft PO
|
|
15
|
+
|
|
16
|
+
Same as above but use `commit="Draft"`. Submit later with `update_purchase_order` using `commit="Send"`.
|
|
17
|
+
|
|
18
|
+
## Approve a PO
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
1. get_purchase_order → find approver_requests[]
|
|
22
|
+
2. Find request where approver matches current user
|
|
23
|
+
3. approve_purchase_order with id and token=request.accept_token
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Reject a PO
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
1. get_purchase_order → find approver_requests[]
|
|
30
|
+
2. reject_purchase_order with id and token=request.reject_token
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Track Delivery
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
1. get_purchase_order → see purchase_order_items with received_quantity
|
|
37
|
+
2. receive_purchase_order_items → record partial delivery
|
|
38
|
+
- items: [{ id: itemId, quantity: receivedQty }]
|
|
39
|
+
- delivered_on: delivery date
|
|
40
|
+
3. Repeat step 2 for additional deliveries
|
|
41
|
+
4. complete_purchase_order_delivery → mark as fully delivered
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Forward PO to Supplier
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
1. list_send_to_supplier_templates → get email template
|
|
48
|
+
2. get_supplier → get supplier email
|
|
49
|
+
3. forward_purchase_order → send with emails, note from template
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Generate PDF
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
1. generate_purchase_order_pdf → returns { pdf_link: "..." }
|
|
56
|
+
2. Share the pdf_link with the user
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Review Pending Approvals
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
1. get_pending_request_count → see how many POs need approval
|
|
63
|
+
2. list_purchase_orders with requests=true → get POs pending approval
|
|
64
|
+
3. For each PO: approve or reject using tokens
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Create PO on Behalf of Another User
|
|
68
|
+
|
|
69
|
+
Requires companyadmin role. The `on_behalf_of` user must be an active employee.
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
1. list_employees → find user ID
|
|
73
|
+
2. create_purchase_order with on_behalf_of=userId, creator_id=your own ID
|
|
74
|
+
```
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pex:settings
|
|
3
|
+
description: >
|
|
4
|
+
ProcurementExpress settings, reference data, and integrations. Covers tax rates, webhooks,
|
|
5
|
+
currencies, chart of accounts (GL codes), and QuickBooks (QBO) customers/classes. Use when
|
|
6
|
+
managing tax rates, setting up webhooks for PO events, querying currencies, looking up
|
|
7
|
+
chart of accounts or GL codes, or working with QuickBooks data. Routes to MCP tools:
|
|
8
|
+
list_tax_rates, get_tax_rate, create_tax_rate, update_tax_rate, list_webhooks, get_webhook,
|
|
9
|
+
create_webhook, update_webhook, delete_webhook, list_currencies, list_all_currencies,
|
|
10
|
+
list_chart_of_accounts, get_chart_of_account, list_qbo_customers, get_qbo_customer,
|
|
11
|
+
list_qbo_classes, get_qbo_class. Triggers on: tax rate, VAT, webhook, delete webhook,
|
|
12
|
+
currency, chart of accounts, GL code, QuickBooks, QBO customer, QBO class,
|
|
13
|
+
accounting integration.
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# ProcurementExpress Settings & Reference Data
|
|
17
|
+
|
|
18
|
+
## Prerequisites
|
|
19
|
+
|
|
20
|
+
Authenticate (pex-auth) and set active company (pex-companies) first.
|
|
21
|
+
|
|
22
|
+
## Tax Rate Tools
|
|
23
|
+
|
|
24
|
+
### list_tax_rates
|
|
25
|
+
List tax rates for the current company.
|
|
26
|
+
- **Params:** `archived` (optional, boolean, default: false)
|
|
27
|
+
- **Returns:** `TaxRate[]` — each has: id, name, value, archived, company_id, tax_type, tax_rate_items[]
|
|
28
|
+
|
|
29
|
+
### get_tax_rate
|
|
30
|
+
- **Params:** `id` (required, integer)
|
|
31
|
+
- **Returns:** `TaxRate`
|
|
32
|
+
|
|
33
|
+
### create_tax_rate
|
|
34
|
+
- **Params:** `name` (required, string, e.g. "VAT 20%"), `value` (required, number, e.g. 20)
|
|
35
|
+
- **Returns:** `TaxRate`
|
|
36
|
+
|
|
37
|
+
### update_tax_rate
|
|
38
|
+
- **Params:** `id` (required) + `name`, `value`, `archived` (all optional)
|
|
39
|
+
- **Returns:** `TaxRate`
|
|
40
|
+
|
|
41
|
+
## Currency Tools
|
|
42
|
+
|
|
43
|
+
### list_currencies
|
|
44
|
+
List currencies enabled for the current company. Company default currency is listed first.
|
|
45
|
+
- **Params:** None
|
|
46
|
+
- **Returns:** `Currency[]` — each has: id, iso_code, iso_numeric, name, symbol
|
|
47
|
+
|
|
48
|
+
### list_all_currencies
|
|
49
|
+
List ALL available currencies globally (sorted by popularity if company is set).
|
|
50
|
+
- **Params:** None
|
|
51
|
+
- **Returns:** `Currency[]`
|
|
52
|
+
|
|
53
|
+
## Webhook Tools
|
|
54
|
+
|
|
55
|
+
Webhooks fire on PO lifecycle events. Each webhook sends an HTTP POST to the configured URL.
|
|
56
|
+
|
|
57
|
+
### list_webhooks
|
|
58
|
+
- **Params:** `archived` (optional, boolean, default: false)
|
|
59
|
+
- **Returns:** `Webhook[]`
|
|
60
|
+
|
|
61
|
+
### get_webhook
|
|
62
|
+
- **Params:** `id` (required, integer)
|
|
63
|
+
- **Returns:** `Webhook` — includes: id, name, url, event_type[], tested, response_code, webhook_attributes[]
|
|
64
|
+
|
|
65
|
+
### create_webhook
|
|
66
|
+
- **Params:**
|
|
67
|
+
- `name` (required, string)
|
|
68
|
+
- `url` (required, string) — handler URL
|
|
69
|
+
- `event_type` (required, string array) — one or more of:
|
|
70
|
+
- `"new_po"`, `"po_approved"`, `"po_delivered"`, `"po_paid"`, `"po_cancelled"`, `"po_update"`
|
|
71
|
+
- `authentication_header` (optional, string) — custom auth header value
|
|
72
|
+
- `json_wrapper` (optional, string) — root key for JSON payload
|
|
73
|
+
- `send_as_text` (optional, boolean) — send as text instead of JSON
|
|
74
|
+
- `basic_auth_uname` (optional, string) — basic auth username
|
|
75
|
+
- `basic_auth_pword` (optional, string) — basic auth password
|
|
76
|
+
- `webhook_attributes` (optional, array) — custom key-value pairs sent with each webhook:
|
|
77
|
+
- `attrib_type` (required), `key` (required), `value` (required)
|
|
78
|
+
- **Returns:** `Webhook`
|
|
79
|
+
|
|
80
|
+
### update_webhook
|
|
81
|
+
- **Params:** `id` (required) + any create_webhook params + `archived` (optional, boolean)
|
|
82
|
+
- For webhook_attributes updates: include `id` to update existing, `_destroy: true` to remove
|
|
83
|
+
- **Returns:** `Webhook`
|
|
84
|
+
|
|
85
|
+
### delete_webhook
|
|
86
|
+
Permanently delete a webhook.
|
|
87
|
+
- **Params:** `id` (required, integer)
|
|
88
|
+
- **Returns:** Deletion confirmation
|
|
89
|
+
|
|
90
|
+
## Chart of Accounts Tools (GL Codes)
|
|
91
|
+
|
|
92
|
+
Used for accounting classification on PO/invoice line items.
|
|
93
|
+
|
|
94
|
+
### list_chart_of_accounts
|
|
95
|
+
- **Params:** `search` (optional), `page` (optional, integer), `per_page` (optional, integer)
|
|
96
|
+
- **Returns:** `{ chart_of_accounts: ChartOfAccount[], meta: PaginationMeta }`
|
|
97
|
+
|
|
98
|
+
### get_chart_of_account
|
|
99
|
+
- **Params:** `id` (required, integer)
|
|
100
|
+
- **Returns:** `ChartOfAccount` — id, name, classification, account_type, currency_code, account_number, display_name, archived
|
|
101
|
+
|
|
102
|
+
## QuickBooks Tools
|
|
103
|
+
|
|
104
|
+
### list_qbo_customers
|
|
105
|
+
- **Params:** `search` (optional), `page` (optional), `per_page` (optional)
|
|
106
|
+
- **Returns:** `{ qbo_customers: QboCustomer[], meta: PaginationMeta }`
|
|
107
|
+
|
|
108
|
+
### get_qbo_customer
|
|
109
|
+
- **Params:** `id` (required, integer)
|
|
110
|
+
- **Returns:** `QboCustomer` — id, fully_qualified_name, archived
|
|
111
|
+
|
|
112
|
+
### list_qbo_classes
|
|
113
|
+
- **Params:** `search` (optional), `page` (optional), `per_page` (optional)
|
|
114
|
+
- **Returns:** `{ quickbooks_classes: QboClass[], meta: PaginationMeta }`
|
|
115
|
+
|
|
116
|
+
### get_qbo_class
|
|
117
|
+
- **Params:** `id` (required, integer)
|
|
118
|
+
- **Returns:** `QboClass` — id, fully_qualified_name, archived
|
|
119
|
+
|
|
120
|
+
## Where Reference Data Is Used
|
|
121
|
+
|
|
122
|
+
| Data | Used In |
|
|
123
|
+
|------|---------|
|
|
124
|
+
| Tax rates | PO line items (`tax_rate_id`), invoice line items, products |
|
|
125
|
+
| Currencies | Budgets, POs, invoices, payments, suppliers |
|
|
126
|
+
| Chart of accounts | PO line items, invoice line items, budgets |
|
|
127
|
+
| QBO customers | PO line items, invoice line items |
|
|
128
|
+
| QBO classes | PO line items, invoice line items, budgets |
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pex:suppliers
|
|
3
|
+
description: >
|
|
4
|
+
ProcurementExpress supplier and product management. Use when listing, viewing, creating, or
|
|
5
|
+
updating suppliers (vendors) and their products (catalog items). Routes to MCP tools:
|
|
6
|
+
list_suppliers, get_top_suppliers, get_supplier, create_supplier, update_supplier,
|
|
7
|
+
list_products, get_product, create_product, update_product. Triggers on: supplier, vendor,
|
|
8
|
+
product, catalog, SKU, top suppliers, supplier search, product list.
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# ProcurementExpress Suppliers & Products
|
|
12
|
+
|
|
13
|
+
## Prerequisites
|
|
14
|
+
|
|
15
|
+
Authenticate (pex-auth) and set active company (pex-companies) first.
|
|
16
|
+
|
|
17
|
+
## Supplier Tools
|
|
18
|
+
|
|
19
|
+
### list_suppliers
|
|
20
|
+
List suppliers with optional pagination, search, and filters.
|
|
21
|
+
- **Params:**
|
|
22
|
+
- `page` (optional, integer) — enables pagination (20 per page). Without page, returns ALL suppliers
|
|
23
|
+
- `search` (optional, string) — search by supplier name
|
|
24
|
+
- `department_id` (optional, integer) — filter by department (also includes suppliers with no department)
|
|
25
|
+
- `archived` (optional, boolean, default: false)
|
|
26
|
+
- `show_mappings` (optional, boolean) — include third-party ID mappings
|
|
27
|
+
- **Returns:** `Supplier[]` (no pagination) or `{ suppliers: Supplier[], meta: PaginationMeta }` (with pagination)
|
|
28
|
+
|
|
29
|
+
### get_top_suppliers
|
|
30
|
+
Get the user's most frequently used suppliers.
|
|
31
|
+
- **Params:**
|
|
32
|
+
- `top` (optional, integer, default: 5) — number of suppliers to return
|
|
33
|
+
- `archived` (optional, boolean)
|
|
34
|
+
- **Returns:** `Supplier[]`
|
|
35
|
+
|
|
36
|
+
### get_supplier
|
|
37
|
+
Get a specific supplier by ID.
|
|
38
|
+
- **Params:** `id` (required, integer)
|
|
39
|
+
- **Returns:** `Supplier`
|
|
40
|
+
|
|
41
|
+
### create_supplier
|
|
42
|
+
Create a new supplier. Name must be unique within the company.
|
|
43
|
+
- **Params:**
|
|
44
|
+
- `name` (required, string, must be unique)
|
|
45
|
+
- `email` (optional, string)
|
|
46
|
+
- `address` (optional, string)
|
|
47
|
+
- `notes` (optional, string)
|
|
48
|
+
- `payment_details` (optional, string) — bank/payment info
|
|
49
|
+
- `phone_number` (optional, string)
|
|
50
|
+
- `tax_number` (optional, string)
|
|
51
|
+
- `contact_person` (optional, string)
|
|
52
|
+
- `uei` (optional, string) — Unique Entity Identifier for SAM.gov
|
|
53
|
+
- `cage_code` (optional, string) — CAGE code for government contracting
|
|
54
|
+
- `department_ids` (optional, integer array) — restrict supplier to specific departments
|
|
55
|
+
- **Note:** If company has supplier approval enabled, creates a pending approval request instead
|
|
56
|
+
- **Returns:** `Supplier`
|
|
57
|
+
|
|
58
|
+
### update_supplier
|
|
59
|
+
Update an existing supplier.
|
|
60
|
+
- **Params:** `id` (required) + any create_supplier params + `archived` (optional, boolean)
|
|
61
|
+
- **Returns:** `Supplier`
|
|
62
|
+
|
|
63
|
+
## Product Tools
|
|
64
|
+
|
|
65
|
+
Products are catalog items associated with a supplier. When creating PO line items, use `product_id` to auto-fill description, SKU, and unit price.
|
|
66
|
+
|
|
67
|
+
### list_products
|
|
68
|
+
List products with optional pagination and filters.
|
|
69
|
+
- **Params:**
|
|
70
|
+
- `page` (optional, integer) — enables pagination
|
|
71
|
+
- `per_page` (optional, integer, default: 20)
|
|
72
|
+
- `supplier_id` (optional, integer) — filter by supplier
|
|
73
|
+
- `archived` (optional, boolean, default: false)
|
|
74
|
+
- **Returns:** `Product[]` (no pagination) or `{ products: Product[], meta: PaginationMeta }` (with pagination)
|
|
75
|
+
|
|
76
|
+
### get_product
|
|
77
|
+
Get a specific product by ID.
|
|
78
|
+
- **Params:** `id` (required, integer)
|
|
79
|
+
- **Returns:** `Product`
|
|
80
|
+
|
|
81
|
+
### create_product
|
|
82
|
+
Create a new product associated with a supplier.
|
|
83
|
+
- **Params:**
|
|
84
|
+
- `description` (required, string)
|
|
85
|
+
- `supplier_id` (required, integer) — must belong to an existing supplier
|
|
86
|
+
- `sku` (optional, string)
|
|
87
|
+
- `unit_price` (optional, number)
|
|
88
|
+
- **Returns:** `Product`
|
|
89
|
+
|
|
90
|
+
### update_product
|
|
91
|
+
Update an existing product.
|
|
92
|
+
- **Params:** `id` (required) + `description`, `sku`, `unit_price`, `supplier_id` (all optional)
|
|
93
|
+
- **Returns:** `Product`
|
|
94
|
+
|
|
95
|
+
## Supplier Response Fields
|
|
96
|
+
|
|
97
|
+
- `id`, `name`, `company_id`, `archived`
|
|
98
|
+
- `email`, `phone_number`, `address`, `contact_person`
|
|
99
|
+
- `notes`, `payment_details`, `tax_number`
|
|
100
|
+
- `payment_terms`, `currency_id`
|
|
101
|
+
- `department_ids[]` — restricted departments
|
|
102
|
+
- `external_vendor_id`, `third_party_id_mappings`
|
|
103
|
+
- `created_at`, `updated_at`
|
|
104
|
+
|
|
105
|
+
## Product Response Fields
|
|
106
|
+
|
|
107
|
+
- `id`, `supplier_id`, `sku`, `description`, `unit_price`
|
|
108
|
+
- `currency_id`, `archived`, `tax_rate_id`
|
|
109
|
+
- `created_at`, `updated_at`
|
|
110
|
+
|
|
111
|
+
## PaginationMeta Fields
|
|
112
|
+
|
|
113
|
+
- `current_page`, `next_page`, `prev_page`, `total_pages`, `total_count`
|
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that p
|
|
|
4
4
|
|
|
5
5
|
## Features
|
|
6
6
|
|
|
7
|
-
- **
|
|
7
|
+
- **88 tools** covering the full ProcurementExpress API surface
|
|
8
8
|
- **Dual API version support** — V1 (token-based) and V3 (OAuth2) authentication
|
|
9
9
|
- **Version-agnostic tool layer** — all tools work identically across API versions
|
|
10
10
|
- **Type-safe** — comprehensive TypeScript interfaces for all API entities
|
|
@@ -128,17 +128,22 @@ Set `PROCUREMENTEXPRESS_API_VERSION=v3`. Requires `PROCUREMENTEXPRESS_CLIENT_ID`
|
|
|
128
128
|
| `list_currencies` | List enabled currencies for the current company |
|
|
129
129
|
| `list_all_currencies` | List all available currencies globally |
|
|
130
130
|
|
|
131
|
-
### Companies (
|
|
131
|
+
### Companies (12 tools)
|
|
132
132
|
|
|
133
133
|
| Tool | Description |
|
|
134
134
|
|------|-------------|
|
|
135
135
|
| `list_companies` | List all companies the current user belongs to |
|
|
136
|
-
| `get_company` | Get company details including settings and currencies |
|
|
136
|
+
| `get_company` | Get company details by ID including settings and currencies |
|
|
137
|
+
| `get_company_details` | Get details for the currently active company |
|
|
137
138
|
| `set_active_company` | Set active company ID for subsequent API calls |
|
|
138
139
|
| `list_approvers` | List approvers filtered by department |
|
|
139
140
|
| `list_all_approvers` | List all approvers regardless of routing |
|
|
140
|
-
| `list_employees` | List all employees with roles |
|
|
141
|
+
| `list_employees` | List all active employees with roles |
|
|
141
142
|
| `invite_user` | Invite a user (roles: companyadmin, approver, finance, teammember) |
|
|
143
|
+
| `get_invite_limit` | Get remaining invite slots for the company |
|
|
144
|
+
| `list_pending_invites` | List pending user invitations |
|
|
145
|
+
| `cancel_invite` | Cancel a pending user invitation |
|
|
146
|
+
| `resend_invite` | Resend a pending user invitation email |
|
|
142
147
|
|
|
143
148
|
### Budgets (4 tools)
|
|
144
149
|
|
|
@@ -158,11 +163,12 @@ Set `PROCUREMENTEXPRESS_API_VERSION=v3`. Requires `PROCUREMENTEXPRESS_CLIENT_ID`
|
|
|
158
163
|
| `create_department` | Create a new department |
|
|
159
164
|
| `update_department` | Update a department |
|
|
160
165
|
|
|
161
|
-
### Suppliers (
|
|
166
|
+
### Suppliers (5 tools)
|
|
162
167
|
|
|
163
168
|
| Tool | Description |
|
|
164
169
|
|------|-------------|
|
|
165
170
|
| `list_suppliers` | List suppliers with pagination and filters |
|
|
171
|
+
| `get_top_suppliers` | Get top suppliers by spend |
|
|
166
172
|
| `get_supplier` | Get a specific supplier |
|
|
167
173
|
| `create_supplier` | Create a supplier (name must be unique) |
|
|
168
174
|
| `update_supplier` | Update a supplier |
|
|
@@ -176,26 +182,31 @@ Set `PROCUREMENTEXPRESS_API_VERSION=v3`. Requires `PROCUREMENTEXPRESS_CLIENT_ID`
|
|
|
176
182
|
| `create_product` | Create a new product |
|
|
177
183
|
| `update_product` | Update a product |
|
|
178
184
|
|
|
179
|
-
### Purchase Orders (
|
|
185
|
+
### Purchase Orders (15 tools)
|
|
180
186
|
|
|
181
187
|
| Tool | Description |
|
|
182
188
|
|------|-------------|
|
|
183
|
-
| `list_purchase_orders` | List POs with pagination and
|
|
189
|
+
| `list_purchase_orders` | List POs with pagination, search, and filters |
|
|
184
190
|
| `get_purchase_order` | Get PO details with line items, comments, approvals |
|
|
185
191
|
| `create_purchase_order` | Create a PO (commit='Send' to submit, 'Draft' to save) |
|
|
192
|
+
| `update_purchase_order` | Update an existing PO |
|
|
186
193
|
| `approve_purchase_order` | Approve using the accept token from approver request |
|
|
187
194
|
| `reject_purchase_order` | Reject using the reject token from approver request |
|
|
188
195
|
| `override_and_approve_purchase_order` | Finance override approval (no token required) |
|
|
189
196
|
| `cancel_purchase_order` | Cancel a purchase order |
|
|
190
|
-
| `archive_purchase_order` |
|
|
197
|
+
| `archive_purchase_order` | Toggle archive status of a purchase order |
|
|
198
|
+
| `delete_purchase_order` | Permanently delete a purchase order |
|
|
199
|
+
| `generate_purchase_order_pdf` | Generate a PDF and return a download link |
|
|
191
200
|
| `get_pending_request_count` | Get count of pending approval requests |
|
|
192
|
-
| `receive_purchase_order_items` | Mark items as received |
|
|
201
|
+
| `receive_purchase_order_items` | Mark line items as received (partial or full delivery) |
|
|
202
|
+
| `cancel_receiving_items` | Cancel all received deliveries for a PO |
|
|
203
|
+
| `complete_purchase_order_delivery` | Mark a PO as fully delivered |
|
|
193
204
|
|
|
194
|
-
### Invoices (
|
|
205
|
+
### Invoices (11 tools)
|
|
195
206
|
|
|
196
207
|
| Tool | Description |
|
|
197
208
|
|------|-------------|
|
|
198
|
-
| `list_invoices` | List invoices with pagination and filters
|
|
209
|
+
| `list_invoices` | List invoices with pagination and filters |
|
|
199
210
|
| `get_invoice` | Get invoice details |
|
|
200
211
|
| `create_invoice` | Create a new invoice |
|
|
201
212
|
| `update_invoice` | Update an existing invoice |
|
|
@@ -205,22 +216,31 @@ Set `PROCUREMENTEXPRESS_API_VERSION=v3`. Requires `PROCUREMENTEXPRESS_CLIENT_ID`
|
|
|
205
216
|
| `cancel_invoice` | Cancel an invoice |
|
|
206
217
|
| `archive_invoice` | Archive an invoice |
|
|
207
218
|
| `dearchive_invoice` | Restore an archived invoice |
|
|
219
|
+
| `rerun_invoice_approval_flow` | Rerun approval flow for a specific invoice |
|
|
208
220
|
|
|
209
|
-
### Approval Flows (
|
|
221
|
+
### Approval Flows (13 tools)
|
|
210
222
|
|
|
211
223
|
| Tool | Description |
|
|
212
224
|
|------|-------------|
|
|
213
225
|
| `list_approval_flows` | List approval flows with search and pagination |
|
|
214
226
|
| `get_approval_flow` | Get flow details with steps, approvers, conditions |
|
|
215
227
|
| `create_approval_flow` | Create a flow (document_type: 0=PO, 1=invoice) |
|
|
216
|
-
| `
|
|
217
|
-
| `
|
|
228
|
+
| `update_approval_flow` | Update an existing approval flow |
|
|
229
|
+
| `delete_approval_flow` | Delete an approval flow permanently |
|
|
230
|
+
| `archive_approval_flow` | Archive an approval flow (soft delete) |
|
|
231
|
+
| `publish_approval_flow` | Publish an approval flow to make it active |
|
|
232
|
+
| `unpublish_approval_flow` | Unpublish an approval flow to deactivate it |
|
|
218
233
|
| `list_approval_flow_runs` | List runs with status and date filters |
|
|
234
|
+
| `get_approval_flow_entity` | Get details about an entity that went through a flow |
|
|
235
|
+
| `list_approval_flow_versions` | List all version history of an approval flow |
|
|
236
|
+
| `get_approval_flow_version_details` | Get full details of a specific version |
|
|
237
|
+
| `rerun_approval_flows` | Rerun approval flows for specific POs and/or invoices |
|
|
219
238
|
|
|
220
|
-
### Payments (
|
|
239
|
+
### Payments (3 tools)
|
|
221
240
|
|
|
222
241
|
| Tool | Description |
|
|
223
242
|
|------|-------------|
|
|
243
|
+
| `get_payment` | Get a specific payment by ID |
|
|
224
244
|
| `create_payment` | Create a payment (types: bank_transfer, card, check, cash, etc.) |
|
|
225
245
|
| `create_po_payment` | Create item-level payments for a purchase order |
|
|
226
246
|
|
|
@@ -233,7 +253,7 @@ Set `PROCUREMENTEXPRESS_API_VERSION=v3`. Requires `PROCUREMENTEXPRESS_CLIENT_ID`
|
|
|
233
253
|
| `create_tax_rate` | Create a new tax rate |
|
|
234
254
|
| `update_tax_rate` | Update a tax rate |
|
|
235
255
|
|
|
236
|
-
### Webhooks (
|
|
256
|
+
### Webhooks (5 tools)
|
|
237
257
|
|
|
238
258
|
| Tool | Description |
|
|
239
259
|
|------|-------------|
|
|
@@ -241,6 +261,7 @@ Set `PROCUREMENTEXPRESS_API_VERSION=v3`. Requires `PROCUREMENTEXPRESS_CLIENT_ID`
|
|
|
241
261
|
| `get_webhook` | Get a specific webhook |
|
|
242
262
|
| `create_webhook` | Create a webhook (events: new_po, po_approved, po_delivered, po_paid, po_cancelled, po_update) |
|
|
243
263
|
| `update_webhook` | Update a webhook |
|
|
264
|
+
| `delete_webhook` | Delete a webhook |
|
|
244
265
|
|
|
245
266
|
### Comments (2 tools)
|
|
246
267
|
|
|
@@ -249,16 +270,60 @@ Set `PROCUREMENTEXPRESS_API_VERSION=v3`. Requires `PROCUREMENTEXPRESS_CLIENT_ID`
|
|
|
249
270
|
| `add_purchase_order_comment` | Add a comment to a purchase order |
|
|
250
271
|
| `add_invoice_comment` | Add a comment to an invoice |
|
|
251
272
|
|
|
252
|
-
### Supplementary (
|
|
273
|
+
### Supplementary (8 tools)
|
|
253
274
|
|
|
254
275
|
| Tool | Description |
|
|
255
276
|
|------|-------------|
|
|
256
|
-
| `list_chart_of_accounts` | List chart of accounts with search |
|
|
277
|
+
| `list_chart_of_accounts` | List chart of accounts (GL codes) with search |
|
|
278
|
+
| `get_chart_of_account` | Get a specific chart of account |
|
|
257
279
|
| `list_qbo_customers` | List QuickBooks customers with search |
|
|
280
|
+
| `get_qbo_customer` | Get a specific QuickBooks customer |
|
|
258
281
|
| `list_qbo_classes` | List QuickBooks classes with search |
|
|
282
|
+
| `get_qbo_class` | Get a specific QuickBooks class |
|
|
259
283
|
| `list_send_to_supplier_templates` | List email templates for sending POs |
|
|
260
284
|
| `forward_purchase_order` | Email a PO to supplier(s) |
|
|
261
285
|
|
|
286
|
+
## AI Agent Skills
|
|
287
|
+
|
|
288
|
+
The server ships with 10 module-specific [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code) in `.claude/skills/` that route AI agents to the correct MCP tool calls without reading entire source files. Skills use the `pex:` namespace:
|
|
289
|
+
|
|
290
|
+
| Skill | Tools | Description |
|
|
291
|
+
|-------|-------|-------------|
|
|
292
|
+
| `pex:auth` | 5 | Authentication (V1/V3), token management, user profile |
|
|
293
|
+
| `pex:companies` | 12 | Company details, employees, invitations, approvers |
|
|
294
|
+
| `pex:budgets` | 4 | Budget CRUD with custom field support |
|
|
295
|
+
| `pex:departments` | 4 | Department CRUD |
|
|
296
|
+
| `pex:suppliers` | 9 | Supplier and product management |
|
|
297
|
+
| `pex:purchase-orders` | 18 | PO lifecycle, delivery, PDF, forwarding, comments |
|
|
298
|
+
| `pex:invoices` | 12 | Invoice lifecycle, approval, comments |
|
|
299
|
+
| `pex:payments` | 3 | Payment creation and retrieval |
|
|
300
|
+
| `pex:approval-flows` | 13 | Approval flow configuration, runs, versions |
|
|
301
|
+
| `pex:settings` | 17 | Tax rates, webhooks, currencies, chart of accounts, QBO |
|
|
302
|
+
|
|
303
|
+
Skills with complex schemas include `references/` subdirectories for progressive disclosure (e.g., line item schemas, approval conditions, workflows).
|
|
304
|
+
|
|
305
|
+
### Installing Skills in Your Project
|
|
306
|
+
|
|
307
|
+
To use these skills in your own project alongside the MCP server, copy the `.claude/skills/pex-*` directories into your project:
|
|
308
|
+
|
|
309
|
+
```bash
|
|
310
|
+
# From your project root
|
|
311
|
+
mkdir -p .claude/skills
|
|
312
|
+
|
|
313
|
+
# Copy all PEX skills from the package
|
|
314
|
+
cp -r node_modules/@procurementexpress.com/mcp/.claude/skills/pex-* .claude/skills/
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
Or cherry-pick only the skills you need:
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
# Example: only purchase orders and invoices
|
|
321
|
+
cp -r node_modules/@procurementexpress.com/mcp/.claude/skills/pex-purchase-orders .claude/skills/
|
|
322
|
+
cp -r node_modules/@procurementexpress.com/mcp/.claude/skills/pex-invoices .claude/skills/
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
Once installed, Claude Code will automatically discover the skills and use them to route to the correct MCP tool calls (e.g., `/pex:purchase-orders`, `/pex:invoices`).
|
|
326
|
+
|
|
262
327
|
## Project Structure
|
|
263
328
|
|
|
264
329
|
```
|
|
@@ -269,24 +334,24 @@ src/
|
|
|
269
334
|
tool-helpers.ts # Shared response helpers and error handling wrapper
|
|
270
335
|
types.ts # TypeScript interfaces for all API entities
|
|
271
336
|
tools/
|
|
272
|
-
approval-flows.ts # Approval flow CRUD
|
|
337
|
+
approval-flows.ts # Approval flow CRUD, publish/unpublish, runs, versions
|
|
273
338
|
budgets.ts # Budget CRUD
|
|
274
339
|
comments.ts # PO and invoice comments
|
|
275
340
|
companies.ts # Company details, employees, approvers, invitations
|
|
276
341
|
departments.ts # Department CRUD
|
|
277
|
-
invoices.ts # Invoice CRUD, approve/reject/cancel/archive
|
|
278
|
-
payments.ts # Payment creation (standalone and PO-linked)
|
|
342
|
+
invoices.ts # Invoice CRUD, approve/reject/cancel/archive, rerun approval
|
|
343
|
+
payments.ts # Payment creation (standalone and PO-linked) and get
|
|
279
344
|
products.ts # Product CRUD
|
|
280
|
-
purchase-orders.ts # PO CRUD, approve/reject/cancel/archive,
|
|
345
|
+
purchase-orders.ts # PO CRUD, approve/reject/cancel/archive/delete, delivery, PDF
|
|
281
346
|
supplementary.ts # Chart of accounts, QBO integration, email forwarding
|
|
282
|
-
suppliers.ts # Supplier CRUD
|
|
347
|
+
suppliers.ts # Supplier CRUD + top suppliers
|
|
283
348
|
tax-rates.ts # Tax rate CRUD
|
|
284
349
|
users.ts # Current user profile and currency listing
|
|
285
|
-
webhooks.ts # Webhook CRUD
|
|
350
|
+
webhooks.ts # Webhook CRUD + delete
|
|
286
351
|
tests/
|
|
287
352
|
e2e/
|
|
288
353
|
setup.ts # MockApiServer with version-agnostic route registration
|
|
289
|
-
*.test.ts # E2E tests for each tool group
|
|
354
|
+
*.test.ts # E2E tests for each tool group
|
|
290
355
|
```
|
|
291
356
|
|
|
292
357
|
## Development
|
|
@@ -360,6 +425,34 @@ registerMyTools(server, apiClient);
|
|
|
360
425
|
- Use `jsonResponse()` for data and `textResponse()` for messages
|
|
361
426
|
- All imports must use `.js` extension (ES modules)
|
|
362
427
|
|
|
428
|
+
## Releasing a New Version
|
|
429
|
+
|
|
430
|
+
To publish a new version to npm:
|
|
431
|
+
|
|
432
|
+
1. Ensure your working tree is clean and all tests pass:
|
|
433
|
+
```bash
|
|
434
|
+
npm test
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
2. Bump the version, create a git tag, and publish:
|
|
438
|
+
```bash
|
|
439
|
+
# Choose one: patch (bug fixes), minor (new features), major (breaking changes)
|
|
440
|
+
npm version patch -m "v%s" # or minor / major
|
|
441
|
+
|
|
442
|
+
# Push the commit and tag
|
|
443
|
+
git push && git push --tags
|
|
444
|
+
|
|
445
|
+
# Publish to npm (auto-builds via prepublishOnly)
|
|
446
|
+
npm publish
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
3. Verify the published version:
|
|
450
|
+
```bash
|
|
451
|
+
npm view @procurementexpress.com/mcp version
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
The package is published as [`@procurementexpress.com/mcp`](https://www.npmjs.com/package/@procurementexpress.com/mcp) on npm.
|
|
455
|
+
|
|
363
456
|
## Environment Variables Reference
|
|
364
457
|
|
|
365
458
|
| Variable | Required | Default | Description |
|
package/dist/api-client.d.ts
CHANGED
|
@@ -27,5 +27,6 @@ export declare class ApiClient {
|
|
|
27
27
|
get<T>(path: string, extraHeaders?: Record<string, string>): Promise<T>;
|
|
28
28
|
post<T>(path: string, body?: Record<string, unknown>, extraHeaders?: Record<string, string>): Promise<T>;
|
|
29
29
|
put<T>(path: string, body?: Record<string, unknown>, extraHeaders?: Record<string, string>): Promise<T>;
|
|
30
|
+
patch<T>(path: string, body?: Record<string, unknown>, extraHeaders?: Record<string, string>): Promise<T>;
|
|
30
31
|
delete<T>(path: string, extraHeaders?: Record<string, string>): Promise<T>;
|
|
31
32
|
}
|
package/dist/api-client.js
CHANGED
|
@@ -102,6 +102,9 @@ export class ApiClient {
|
|
|
102
102
|
async put(path, body, extraHeaders) {
|
|
103
103
|
return this.request("PUT", path, body, extraHeaders);
|
|
104
104
|
}
|
|
105
|
+
async patch(path, body, extraHeaders) {
|
|
106
|
+
return this.request("PATCH", path, body, extraHeaders);
|
|
107
|
+
}
|
|
105
108
|
async delete(path, extraHeaders) {
|
|
106
109
|
return this.request("DELETE", path, undefined, extraHeaders);
|
|
107
110
|
}
|