@procurementexpress.com/mcp 1.0.0 → 2.0.0

package/.claude/skills/bump-version/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: bump-version
+description: Bump the npm package version, commit, and create a PR for merging before publishing. Use when the user asks to "bump version", "bump the version", "prepare a release", "version bump", "/bump-version", or when `/npm-publish` is invoked but the version hasn't been bumped yet. This skill ensures the version is incremented, committed, and merged to main via PR before publishing.
+---
+
+# Bump Version
+
+Bump the package version in package.json, commit the change, create a pull request, and guide the user to merge before publishing.
+
+## Workflow
+
+### 1. Pre-flight checks
+
+Run in parallel:
+- `git status` — working tree must be clean
+- `git branch --show-current` — note the current branch
+
+If the working tree is dirty, stop and tell the user to commit or stash changes first.
+
+### 2. Determine version bump
+
+Read the current version from package.json and ask the user which bump type:
+
+| Type | When to use |
+|------|-------------|
+| `patch` (1.0.0 → 1.0.1) | Bug fixes, documentation changes |
+| `minor` (1.0.0 → 1.1.0) | New tools, features, backwards-compatible changes |
+| `major` (1.0.0 → 2.0.0) | Breaking changes to existing tools |
+
+Show the current version and what the new version will be.
+
+### 3. Create a release branch and bump
+
+```bash
+# Create and switch to release branch
+git checkout -b release/v<new-version>
+
+# Bump version in package.json (no git tag yet — tag after merge)
+npm version <patch|minor|major> --no-git-tag-version
+```
+
+### 4. Commit the change
+
+Stage the version bump and use the `/commit` skill:
+
+```bash
+git add package.json package-lock.json
+```
+
+Then invoke `/commit` — the commit message should follow the pattern: `Bump version to <new-version>`
+
+### 5. Push and create PR
+
+```bash
+# Push the release branch
+git push -u origin release/v<new-version>
+
+# Create PR targeting main
+gh pr create --base main --title "Release v<new-version>" --body "Bump package version to <new-version> for npm publish."
+```
+
+If `gh` CLI is not available, provide the GitHub URL for manual PR creation.
+
+### 6. Guide user to merge and publish
+
+Tell the user:
+
+> PR created. Please review and merge the PR to `main`, then run `/npm-publish` to publish the new version to npm.
+
+Do NOT proceed with publishing — the user must merge the PR first.
+
+## Rules
+
+- Never create a git tag during bump — `/npm-publish` handles tagging after merge.
+- Always use `--no-git-tag-version` with `npm version` to avoid premature tags.
+- Always create a PR targeting `main` — never push directly to main.
+- If already on a feature branch, create the release branch from it and target main.

package/.claude/skills/commit/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: commit
+description: Create git commits from staged changes. Use when the user asks to commit, make a commit, git commit, save changes, or any variation of committing code. Triggers on requests like "commit this", "commit my changes", "/commit", or "make a commit".
+---
+
+# Commit
+
+Create a git commit from staged changes with a generated message, confirmed by the user before execution.
+
+## Workflow
+
+1. **Check staged changes**
+
+```bash
+git diff --cached
+```
+
+If nothing is staged, inform the user and stop. Do NOT look at or consider untracked files.
+
+2. **Update memory (if notable changes exist)**
+
+Before generating the commit message, analyze the staged diff for notable changes worth remembering across sessions. Update the project's `MEMORY.md` file if any of the following are present:
+
+- **New files/modules** — new components, services, utilities, or architectural additions
+- **New dependencies** — packages added to package.json, Gemfile, requirements.txt, etc.
+- **API changes** — new or modified endpoints, routes, or external integrations
+- **Configuration changes** — new env vars, config files, build settings
+- **Architectural patterns** — new design patterns, conventions, or structural decisions
+- **Key learnings** — gotchas, workarounds, or constraints discovered during implementation
+
+**How to update:**
+
+- Read the existing `MEMORY.md` from the project's auto memory directory (path shown in system prompt as "persistent auto memory directory")
+- Append or update entries concisely — use bullet points, keep each entry to 1-2 lines
+- Organize by topic (e.g., "## Architecture", "## Dependencies", "## APIs")
+- Remove outdated entries if the staged changes supersede them
+- Keep total file under 200 lines (lines after 200 are truncated in system prompt)
+- Do NOT add entries for trivial changes (typo fixes, formatting, minor refactors)
+
+If no notable changes are detected, skip this step silently.
+
+3. **Generate commit message**
+
+Analyze only the staged diff to produce a concise commit message (1-2 sentences) that describes the "why" not the "what". Use imperative mood (e.g., "Add", "Fix", "Update").
+
+4. **Confirm with user**
+
+Present the generated message and ask the user to confirm before committing. If memory was updated, briefly mention what was recorded. Example:
+
+> Memory updated: added new `git-worktree` skill to Architecture section.
+>
+> Proposed commit message:
+>
+> `Add git-worktree skill for parallel development`
+>
+> Proceed with this commit?
+
+Wait for explicit user approval. If the user provides an alternative message, use that instead.
+
+5. **Commit**
+
+```bash
+git commit -m "<confirmed message>"
+```
+
+## Rules
+
+- Never include `Co-Authored-By` lines.
+- Never include `Generated by` or `Generated with` lines.
+- Never consider untracked files — only use `git diff --cached` for context.
+- Never stage files automatically — only commit what is already staged.
+- Always confirm the message with the user before running `git commit`.
+- Use a HEREDOC when the message contains special characters or newlines.

package/.claude/skills/npm-publish/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: npm-publish
+description: Bump package version, create a git tag, and publish to npm. Use when the user asks to "publish", "release", "bump version", "npm publish", "create a release", "tag and publish", "/npm-publish", "new version", or any variation of releasing/publishing the package to npm.
+---
+
+# npm Publish
+
+Bump the version in package.json, create a git tag, and publish `@procurementexpress.com/mcp` to npm.
+
+## Workflow
+
+### 1. Pre-flight checks
+
+Run these in parallel:
+- `git status` — working tree must be clean (no uncommitted changes)
+- `git branch --show-current` — must be on `main` branch
+- `npm whoami` — must be logged in to npm
+- `npm test` — all tests must pass
+
+If any check fails, stop and tell the user what to fix.
+
+**Version check:** Compare the current version in package.json against the latest published version:
+
+```bash
+npm view @procurementexpress.com/mcp version
+```
+
+If the versions match (not yet bumped), stop and tell the user to run `/bump-version` first to bump the version, commit, and merge a PR to `main` before publishing.
+
+### 2. Determine version bump
+
+Ask the user which bump type they want:
+
+| Type | When to use |
+|------|-------------|
+| `patch` (1.0.0 → 1.0.1) | Bug fixes, documentation changes |
+| `minor` (1.0.0 → 1.1.0) | New tools, features, backwards-compatible changes |
+| `major` (1.0.0 → 2.0.0) | Breaking changes to existing tools |
+
+Show the current version from package.json and what the new version will be.
+
+### 3. Bump, tag, and publish
+
+Run these commands sequentially:
+
+```bash
+# Bump version in package.json and create git tag
+npm version <patch|minor|major> -m "v%s"
+
+# Push the commit and tag to remote
+git push && git push --tags
+
+# Publish to npm (prepublishOnly will auto-build)
+npm publish
+```
+
+### 4. Verify
+
+After publishing, confirm success:
+
+```bash
+npm view @procurementexpress.com/mcp version
+```
+
+Report the published version and the npm package URL: https://www.npmjs.com/package/@procurementexpress.com/mcp

package/.claude/skills/pex-approval-flows/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: pex:approval-flows
+description: >
+  ProcurementExpress approval flow configuration. Use when creating, updating, publishing,
+  or managing approval flows and their steps, conditions, and runs. Approval flows automate
+  the routing of POs and invoices to the right approvers based on configurable conditions.
+  Routes to MCP tools: list_approval_flows, get_approval_flow, create_approval_flow,
+  update_approval_flow, delete_approval_flow, archive_approval_flow, publish_approval_flow,
+  unpublish_approval_flow, list_approval_flow_runs, get_approval_flow_entity,
+  list_approval_flow_versions, get_approval_flow_version_details, rerun_approval_flows.
+  Triggers on: approval flow, approval workflow, approval steps, approval conditions,
+  approval routing, publish flow, flow runs, flow version, flow history, rerun approval.
+---
+
+# ProcurementExpress Approval Flows
+
+## Prerequisites
+
+Authenticate (pex-auth) and set active company (pex-companies) first.
+The company must have `approval_flow_enabled` in company settings.
+
+## Tools Reference
+
+### list_approval_flows
+List active approval flows with search and pagination.
+- **Params:**
+  - `search` (optional) — search by flow name
+  - `page` (optional, integer), `per_page` (optional, integer — 10, 20, 50, 100)
+  - `sort` (optional, e.g. "name", "created_at"), `direction` (optional, "asc"/"desc")
+- **Returns:** `{ approval_flows: ApprovalFlow[], meta: PaginationMeta }`
+
+### get_approval_flow
+Get flow details including steps, approvers, and conditions.
+- **Params:** `id` (required, integer)
+- **Returns:** `ApprovalFlow`
+
+### create_approval_flow
+Create a flow with steps, approvers, and conditions. See [references/conditions.md](references/conditions.md).
+- **Params:**
+  - `name` (required, string)
+  - `document_type` (required, integer) — `0` = purchase order, `1` = invoice
+  - `self_approval_allowed` (optional, boolean) — allow PO creator to self-approve
+  - `steps` (required, array) — approval steps executed in step_no order:
+    - `step_no` (required, integer) — execution order
+    - `all_should_approve` (required, boolean) — true=all approvers, false=any one
+    - `approver_user_ids` (required, integer array) — approver user IDs
+    - `conditions` (optional, array) — step-level conditions (see [references/conditions.md](references/conditions.md))
+  - `conditions` (optional, array) — flow-level conditions that determine which documents match
+- **Returns:** `ApprovalFlow`
+
+### update_approval_flow
+Update a flow. Include `id` on steps/conditions to update existing, omit for new, `_destroy: true` to remove.
+- **Params:** `id` (required) + any create params
+- **Returns:** `ApprovalFlow`
+
+### delete_approval_flow
+Permanently delete a flow.
+- **Params:** `id` (required, integer)
+
+### archive_approval_flow
+Soft-delete (can be restored).
+- **Params:** `id` (required, integer)
+
+### publish_approval_flow
+Make a flow active. New POs/invoices will use this flow.
+- **Params:** `id` (required, integer)
+
+### unpublish_approval_flow
+Deactivate a flow. Existing runs continue but new documents won't use it.
+- **Params:** `id` (required, integer)
+
+### list_approval_flow_runs
+List documents that went through this flow with status and date filters.
+- **Params:**
+  - `id` (required, integer) — flow ID
+  - `status` (optional) — `"in_progress"`, `"completed"`, `"rejected"`
+  - `keyword` (optional) — search keyword
+  - `date_range` (optional) — `"24h"`, `"7d"`, `"30d"`, `"60d"`, `"custom"`
+  - `date_from`, `date_to` (optional) — for custom range
+  - `page`, `per_page` (optional)
+- **Returns:** Paginated flow run results
+
+## ApprovalFlow Response Fields
+
+- `id`, `name`, `document_type` (0=PO, 1=invoice), `self_approval_allowed`
+- `company_id`, `version_no`, `archived`, `status`
+- Counts: `in_progress_count`, `completed_count`, `rejected_count`, `total_runs_count`
+- `approval_steps[]` — each has: id, step_no, all_should_approve, approval_step_approvers[]
+  - Each approver: id, user_id, user_name, user_email
+- `approval_conditions[]` — flow-level conditions
+- `created_at`, `updated_at`
+
+## Version & Entity Tools
+
+### get_approval_flow_entity
+Get details about a specific PO or invoice that went through a flow.
+- **Params:** `id` (required, integer — flow ID), `entity_id` (required, integer — PO or invoice ID)
+- **Returns:** Entity details with approval status
+
+### list_approval_flow_versions
+List all version history of an approval flow.
+- **Params:** `id` (required, integer — flow ID)
+- **Returns:** Version history array
+
+### get_approval_flow_version_details
+Get full details of a specific flow version.
+- **Params:** `id` (required, integer — flow ID), `version_id` (required, integer)
+- **Returns:** Version details with steps and conditions
+
+### rerun_approval_flows
+Batch rerun approval flows for multiple POs and/or invoices. Use when flow rules have changed.
+- **Params:**
+  - `order_ids` (optional, integer array) — PO IDs to rerun flows for
+  - `invoice_ids` (optional, integer array) — invoice IDs to rerun flows for
+- At least one of `order_ids` or `invoice_ids` should be provided
+
+## Flow-Level vs Step-Level Conditions
+
+- **Flow-level conditions** determine WHICH documents match this flow (e.g., "only POs from Engineering department")
+- **Step-level conditions** determine WHICH steps activate for a matching document (e.g., "step 2 only if amount > $10,000")
+
+Both use the same condition schema. See [references/conditions.md](references/conditions.md).

package/.claude/skills/pex-approval-flows/references/conditions.md

@@ -0,0 +1,90 @@
+# Approval Flow Conditions
+
+## Condition Schema
+
+Each condition in the `conditions` array accepts:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | integer | For updates | Existing condition ID |
+| `property` | string | Yes | What to evaluate (see Properties below) |
+| `operator` | string | Yes | How to compare (see Operators below) |
+| `value` | string | Yes | Value to compare against |
+| `custom_field_id` | integer | Only for custom fields | Custom field ID |
+| `_destroy` | boolean | No | Set true to remove (updates only) |
+
+## Properties
+
+| Property | Description | Value Format |
+|----------|-------------|-------------|
+| `budget` | Budget ID | Single budget ID |
+| `department` | Department ID | Single department ID |
+| `supplier` | Supplier ID | Single supplier ID |
+| `requester` | Requester user ID | Single user ID |
+| `gross_amount` | Gross total amount | Numeric string |
+| `net_amount` | Net total amount | Numeric string |
+| `custom_field_<id>` | Custom field value | Depends on field type |
+
+## Operators
+
+| Operator | Use With |
+|----------|----------|
+| `equals` | All properties |
+| `not_equals` | All properties |
+| `greater_than` | Amount properties |
+| `less_than` | Amount properties |
+| `is_any_of` | ID properties (comma-separated IDs) |
+| `is_none_of` | ID properties (comma-separated IDs) |
+| `exists` | Custom field properties (check if value exists) |
+| `not_exists` | Custom field properties (check if value is empty) |
+| `contains` | Text/ID properties (comma-separated IDs or substring) |
+| `not_contains` | Text/ID properties (comma-separated IDs or substring) |
+
+Operators are passed as string values (e.g. `"equals"`, `"greater_than"`).
+
+## Examples
+
+**Flow matches POs from Engineering department (ID: 5):**
+```json
+{ "property": "department", "operator": "0", "value": "5" }
+```
+
+**Step activates when gross amount > $10,000:**
+```json
+{ "property": "gross_amount", "operator": "2", "value": "10000" }
+```
+
+**Flow matches POs from suppliers 1, 2, or 3:**
+```json
+{ "property": "supplier", "operator": "4", "value": "1,2,3" }
+```
+
+**Condition on custom field (ID: 42) equals "urgent":**
+```json
+{ "property": "custom_field_42", "operator": "0", "value": "urgent", "custom_field_id": 42 }
+```
+
+## Approval Step Schema
+
+Each step in the `steps` array:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | integer | For updates | Existing step ID |
+| `step_no` | integer | Yes | Execution order (1, 2, 3...) |
+| `all_should_approve` | boolean | Yes | true = all approvers must approve, false = any one suffices |
+| `approver_user_ids` | integer[] | Yes | User IDs of approvers for this step |
+| `conditions` | array | No | Step-level conditions (same schema as above) |
+| `_destroy` | boolean | No | Remove step (updates only) |
+
+## Workflow: Create a Multi-Step Approval Flow
+
+```
+1. list_employees (pex-companies) → get approver user IDs
+2. list_departments (pex-departments) → get department IDs for conditions
+3. create_approval_flow with:
+   - name, document_type (0=PO or 1=invoice)
+   - steps with step_no ordering and approver assignments
+   - conditions for flow-level matching
+4. publish_approval_flow → make it active
+```

package/.claude/skills/pex-auth/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: pex:auth
+description: >
+  ProcurementExpress authentication and user profile management. Use when authenticating
+  to the ProcurementExpress API (V1 static token or V3 OAuth2 login), validating or revoking
+  tokens, or managing the current user's profile. Routes to MCP tools: authenticate,
+  validate_token, revoke_token, get_current_user, update_current_user. Triggers on: login,
+  sign in, authenticate, token, session, user profile, my account, change password.
+---
+
+# ProcurementExpress Authentication
+
+## Prerequisites
+
+Authentication is ALWAYS required before any other ProcurementExpress MCP tool call.
+After authenticating, call `set_active_company` (pex-companies skill) to set the working company.
+
+## Authentication Modes
+
+The API version is set via `PROCUREMENTEXPRESS_API_VERSION` env var (`v1` or `v3`, default: `v1`).
+
+### V1 Authentication (Static Token)
+
+Call `authenticate` with:
+- `authentication_token` (optional if `PROCUREMENTEXPRESS_AUTH_TOKEN` env var is set)
+- `company_id` (optional if `PROCUREMENTEXPRESS_COMPANY_ID` env var is set)
+
+V1 tokens never expire. If both env vars are set, calling `authenticate` with no args works.
+
+### V3 Authentication (OAuth2)
+
+Call `authenticate` with:
+- `email` (required) — user's email address
+- `password` (required) — user's password
+
+Returns an access token with expiry time. V3 requires `PROCUREMENTEXPRESS_CLIENT_ID` and
+`PROCUREMENTEXPRESS_CLIENT_SECRET` env vars for the OAuth2 client credentials.
+
+**Note:** OTP/2FA is not currently supported by the MCP server. If the user's account has
+2FA enabled, V1 authentication with a static token should be used instead.
+
+## Tools Reference
+
+### authenticate
+Authenticate to the ProcurementExpress API.
+- **V1 params:** `authentication_token` (optional), `company_id` (optional)
+- **V3 params:** `email` (required), `password` (required)
+- **Returns:** Confirmation message (V1) or token with expiry info (V3)
+
+### validate_token
+Check if the current authentication token is valid.
+- **Params:** None
+- **Returns:** V1 returns `User` object, V3 returns `TokenInfo` (resource_owner_id, scopes, expires_in_seconds)
+
+### revoke_token
+End the current session.
+- **Params:** None
+- **V1:** Clears token locally (no server call)
+- **V3:** Revokes token on server via OAuth2 revocation endpoint, then clears locally
+
+### get_current_user
+Get the authenticated user's profile including company memberships and roles.
+- **Params:** None
+- **Returns:** `User` object with fields: id, email, name, phone_number, setup_incomplete, employer_id, approval_limit, companies[]
+- Each company in `companies[]` has: id, name, roles[], is_locked, in_trial, trial_expired, remaining_trial_days
+
+### update_current_user
+Update the authenticated user's profile.
+- **Params (all optional):** `email`, `name`, `first_name`, `last_name`, `phone_number`, `password`, `password_confirmation`
+- When changing password, both `password` and `password_confirmation` are required
+- **Returns:** Updated `User` object
+
+## Typical Workflow
+
+```
+1. authenticate → get session
+2. get_current_user → see available companies
+3. set_active_company (pex-companies) → pick a company
+4. Start using other ProcurementExpress tools
+```

package/.claude/skills/pex-budgets/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: pex:budgets
+description: >
+  ProcurementExpress budget management. Use when listing, viewing, creating, or updating
+  budgets (cost centers). Routes to MCP tools: list_budgets, get_budget, create_budget,
+  update_budget. Triggers on: budget, cost center, spending limit, budget allocation,
+  remaining budget, budget approvers.
+---
+
+# ProcurementExpress Budgets
+
+## Prerequisites
+
+Authenticate (pex-auth) and set active company (pex-companies) first.
+
+## Tools Reference
+
+### list_budgets
+List budgets for the current company.
+- **Params:**
+  - `department_id` (optional, integer) — filter by department
+  - `archived` (optional, boolean, default: false)
+  - `show_mappings` (optional, boolean) — include third-party ID mappings
+- **Returns:** `Budget[]`
+
+### get_budget
+Get a specific budget with remaining amount and associations.
+- **Params:** `id` (required, integer)
+- **Returns:** `Budget`
+
+### create_budget
+Create a new budget.
+- **Params:**
+  - `name` (required, string)
+  - `amount` (required, number)
+  - `currency_id` (optional, integer) — defaults to company currency
+  - `creator_id` (optional, integer)
+  - `cost_code` (optional, string)
+  - `cost_type` (optional, string)
+  - `start_date` (optional, string) — must match company `date_format` setting
+  - `end_date` (optional, string) — must match company `date_format` setting
+  - `allow_anyone_to_approve_a_po` (optional, boolean)
+  - `chart_of_account_id` (optional, integer) — GL code
+  - `qbo_class` (optional, string) — QuickBooks class
+  - `approver_ids` (optional, integer array)
+  - `department_ids` (optional, integer array)
+  - `custom_field_values_attributes` (optional, array) — budget-level custom field values:
+    - `id` (optional, integer — for updates), `value` (required, string), `custom_field_id` (required, integer)
+    - Get available custom fields from `get_company_details` (pex-companies) → `custom_fields[]`
+- **Returns:** `Budget`
+
+### update_budget
+Update an existing budget. Same params as create except `id` is required, all others optional.
+- **Params:** `id` (required) + any create_budget params
+- **Returns:** `Budget`
+
+## Budget Response Fields
+
+- `id`, `name`, `amount`, `currency_id`, `cost_code`, `cost_type`, `archived`
+- `base_amount`, `base_rate` — converted to company base currency
+- `remaining_amount` — budget minus approved/paid POs
+- `summary` — spending summary
+- `approved_this_month` — amount approved in current month
+- `allow_anyone_to_approve_a_po` — bypass approver restrictions
+- `start_date`, `end_date` — budget period
+- `creator_id`, `approver_ids[]`, `department_ids[]`
+- `chart_of_account_id`, `chart_of_account_name`
+- `third_party_id_mappings` — external system IDs
+- `created_at`, `updated_at`
+
+## Date Format
+
+All date fields must match the company's `date_format` setting. Get it via `get_company_details` (pex-companies skill) from `company_setting.date_format`.