Skip to content

Ean Schuessler / mo-mcp

Go to a project
Toggle navigation
Toggle navigation pinning
9aefba5e by Ean Schuessler
Options

Add workflow indexing and improve documentation 

- Index business process workflows from BUSINESS_PROCESSES wiki space
- Add workflow support to search and help tools
- Improve documentation with better organized help content
- Add type attributes to seed data files
- Enhance error handling for workflow loading
1 parent d6d8f38c
Inline Side-by-side
Showing 5 changed files with 543 additions and 18 deletions
<?xml version="1.0" encoding="UTF-8"?>
<!--
This software is in the public domain under CC0 1.0 Universal plus a
Grant of Patent License.
To the extent possible under law, the author(s) have dedicated all
copyright and related and neighboring rights to this software to the
public domain worldwide. This software is distributed without any warranty.
You should have received a copy of the CC0 Public Domain Dedication
along with this software. If not, see
<http://creativecommons.org/publicdomain/zero/1.0/>.
-->
<entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd" type="seed">
<!-- Business Processes Wiki Space -->
<moqui.resource.wiki.WikiSpace wikiSpaceId="BUSINESS_PROCESSES"
description="Business Process Workflows - Step-by-step guides for common business operations"
restrictView="N"
restrictUpdate="Y"
rootPageLocation="dbresource://WikiSpace/BUSINESS_PROCESSES.md"/>
<!-- WikiSpace Root Page -->
<moqui.resource.DbResource
resourceId="WIKI_BUSINESS_PROCESSES"
parentResourceId="WIKI_SPACE_ROOT"
filename="BUSINESS_PROCESSES.md"
isFile="Y"/>
<moqui.resource.DbResourceFile
resourceId="WIKI_BUSINESS_PROCESSES"
mimeType="text/markdown"
versionName="v1">
<fileData><![CDATA[# Business Process Workflows
Step-by-step guides for common Moqui ERP operations.
Each workflow includes:
- Exact MCP tool calls with complete parameters
- Expected responses and how to interpret them
- Common pitfalls and troubleshooting
## Available Workflows
- **[Add Product Variant](Product-Variant-Creation)**: Create new product variants with proper features, pricing, and associations
## How to Use These Guides
These workflows are designed to be **executable by LLMs**. Each step provides:
1. **Exact Tool Call**: The complete `moqui_browse_screens` or `moqui_get_screen_details` call
2. **Parameters**: All required and optional parameters with example values
3. **Expected Result**: What the response looks like and how to extract needed data
4. **Next Step**: How to use the result in the next operation
Copy the tool calls exactly as shown, replacing example values with your specific data.
## Key Concepts
- **productId vs pseudoId**: Always use internal `productId` (returned from create operations), NOT user-visible `pseudoId`
- **Action vs Service**: Use screen `action` parameters, not direct service calls
- **Feature Application**: Use `applyProductFeatures` for existing features, `createProductFeature` only for new features
- **Variant Associations**: Link variants to virtual parent using `PatVariant` association type
## Getting Help
- Use `moqui_get_screen_details` to see available fields and dropdown options
- Use `moqui_get_help` with `wiki:service:EntityName` for service documentation
- Check `validationErrors` in action responses for failure reasons]]></fileData>
</moqui.resource.DbResourceFile>
<!-- Root Wiki Page -->
<moqui.resource.wiki.WikiPage
wikiPageId="BUSINESS_PROCESSES/root"
wikiSpaceId="BUSINESS_PROCESSES"
pagePath="root"
publishedVersionName="v1"
restrictView="N">
</moqui.resource.wiki.WikiPage>
<moqui.resource.wiki.WikiPageHistory
wikiPageId="BUSINESS_PROCESSES/root"
historySeqId="1"
versionName="v1"
userId="EX_JOHN_DOE"
changeDateTime="2026-01-23 00:00:00.000"/>
<!-- ========================================== -->
<!-- Product Variant Creation Workflow -->
<!-- ========================================== -->
<!-- Product Variant Creation Page -->
<moqui.resource.DbResource
resourceId="WIKI_BP_PRODUCT_VARIANT"
parentResourceId="WIKI_BUSINESS_PROCESSES"
filename="Product-Variant-Creation.md"
isFile="Y"/>
<moqui.resource.DbResourceFile
resourceId="WIKI_BP_PRODUCT_VARIANT"
mimeType="text/markdown"
versionName="v1">
<fileData><![CDATA[# Add Product Variant
Complete workflow for creating a new product variant with features, pricing, and association to parent.
## Prerequisites
- A virtual parent product exists (e.g., `DEMO_VAR`)
- Parent has selectable features defined (e.g., Color, Size options)
- You know the feature IDs to apply (e.g., `ColorPurple`, `SizeSmall`)
## Overview
This workflow creates a new variant product by:
1. Finding the parent product
2. Cloning parent to create the variant (or creating a new product)
3. Applying distinguishing features to identify this variant
4. Setting pricing (Current and List prices)
5. Linking variant to virtual parent
## Step 1: Find Parent Product
Locate the virtual parent product to clone from.
```bash
moqui_browse_screens(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/FindProduct",
parameters={productId: "DEMO_VAR"}
)
```
**Expected Result:**
- Product list showing `DEMO_VAR` with its pseudoId
- Note the internal `productId` from the response (or use pseudoId for search)
- Click product link to navigate to EditProduct screen
**Next Step:** Use the parent product ID for cloning.
## Step 2: Clone Product to Create Variant
Clone the parent product to create a new variant. This copies features and prices.
```bash
moqui_browse_screens(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/FindProduct",
action="cloneProduct",
parameters={
productId: "DEMO_VAR",
newProductId: "DEMO_VAR_PUR_SM",
newProductName: "Demo with Variants Purple Small",
copyFeatures: "Y",
copyPrices: "Y",
copyCategories: "Y",
copyAssocs: "N",
copyContent: "N",
copyInventory: "N",
copyFacilities: "N",
copyProductStore: "N"
}
)
```
**Parameters:**
- `productId`: Parent product to clone (use pseudoId or internal ID)
- `newProductId`: New product's pseudoId (user-visible identifier)
- `newProductName`: Display name for the variant
- `copyFeatures`: "Y" to copy features from parent
- `copyPrices`: "Y" to copy pricing from parent
**Expected Result:**
- Response with `status: "executed"`
- `actionResult.result.productId` contains the **internal product ID** of the new variant
- Save this `productId` for all subsequent operations
**Next Step:** Find the new variant product to get its internal `productId`.
## Step 3: Find New Variant Product
Search for the newly created variant to get its internal `productId`.
```bash
moqui_browse_screens(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/FindProduct",
parameters={productId: "DEMO_VAR_PUR_SM"}
)
```
**Expected Result:**
- Product list shows `DEMO_VAR_PUR_SM`
- Click product link to navigate to EditProduct
- The response includes the `productId` field - **use this internal ID for all next steps**
**Next Step:** Apply distinguishing features to the variant.
## Step 4: Apply Distinguishing Features
Apply features that make this variant unique (e.g., Purple color, Small size).
```bash
moqui_browse_screens(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/EditProduct",
action="applyProductFeatures",
parameters={
productId: "100000",
productFeatureIdList: ["ColorPurple", "SizeSmall"],
applTypeEnumId: "PfatDistinguishing",
fromDate: "2026-01-23"
}
)
```
**Parameters:**
- `productId`: **Internal product ID** from Step 3 (NOT the pseudoId!)
- `productFeatureIdList`: Array of feature IDs to apply
- Must be existing features (use `moqui_get_screen_details` to list available options)
- Example: `["ColorPurple", "SizeSmall"]`
- `applTypeEnumId`: "PfatDistinguishing" for variants (NOT "PfatSelectable")
- `fromDate`: Optional, defaults to current date
**Expected Result:**
- Response with `status: "executed"`
- ProductFeatures grid shows the applied features
**Available Feature Types:**
- Colors: `ColorRed`, `ColorBlue`, `ColorGreen`, `ColorPurple`, `ColorBlack`, `ColorWhite`
- Sizes: `SizeSmall`, `SizeMedium`, `SizeLarge`, `SizeXL`
**Next Step:** Set pricing for the variant.
## Step 5: Add Current Price
Set the selling price for the variant.
```bash
moqui_browse_screens(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/EditPrices",
action="createProductPrice",
parameters={
productId: "100000",
priceTypeEnumId: "PptCurrent",
pricePurposeEnumId: "PppSales",
price: "26.99",
priceUomId: "USD",
minQuantity: "1",
fromDate: "2026-01-23"
}
)
```
**Parameters:**
- `productId`: **Internal product ID** from Step 3
- `priceTypeEnumId`: "PptCurrent" for selling price
- `pricePurposeEnumId`: "PppSales" for sales transactions
- `price`: Decimal amount (e.g., "26.99")
- `priceUomId`: Currency code (default: "USD")
- `minQuantity`: Minimum quantity for this price (1 for standard pricing)
**Expected Result:**
- Response with `status: "executed"`
- ProductPrice record created
**Next Step:** Add list price for MSRP display.
## Step 6: Add List Price
Set the list price (MSRP) for the variant.
```bash
moqui_browse_screens(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/EditPrices",
action="createProductPrice",
parameters={
productId: "100000",
priceTypeEnumId: "PptList",
pricePurposeEnumId: "PppSales",
price: "31.99",
priceUomId: "USD",
minQuantity: "1",
fromDate: "2026-01-23"
}
)
```
**Parameters:**
- `priceTypeEnumId`: "PptList" for list price
- All other parameters same as Step 5
**Expected Result:**
- Response with `status: "executed"`
- Variant now has both Current and List prices
**Next Step:** Link variant to virtual parent.
## Step 7: Link Variant to Parent
Create an association between the variant and the virtual parent product.
```bash
moqui_browse_screens(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/EditAssocs",
action="createProductAssoc",
parameters={
productId: "DEMO_VAR",
toProductId: "100000",
productAssocTypeEnumId: "PatVariant",
fromDate: "2026-01-23"
}
)
```
**Parameters:**
- `productId`: Parent product pseudoId or internal ID (the virtual product)
- `toProductId`: **Internal product ID** of the variant (from Step 3)
- `productAssocTypeEnumId`: "PatVariant" for variant relationship
- `fromDate`: Optional, defaults to current date
**Expected Result:**
- Response with `status: "executed"`
- ProductAssoc record created linking parent to variant
**Next Step:** Verify the complete setup.
## Step 8: Verify Setup
Verify that the variant is properly configured.
```bash
moqui_browse_screens(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/EditProduct",
parameters={productId: "100000"}
)
```
**Check:**
1. **Features tab**: Shows `ColorPurple` and `SizeSmall` with `PfatDistinguishing` type
2. **Prices tab**: Shows both Current ($26.99) and List ($31.99) prices
3. **Assocs tab**: Shows association to `DEMO_VAR` with type `PatVariant`
**Expected Result:**
- All features, prices, and associations are visible
- Variant is ready for use in catalog
## Quick Reference: Common Variant Patterns
### Purple Small (Example)
- PseudoId: `DEMO_VAR_PUR_SM`
- Features: `["ColorPurple", "SizeSmall"]`
- Current: $26.99, List: $31.99
### Purple Medium
- PseudoId: `DEMO_VAR_PUR_MD`
- Features: `["ColorPurple", "SizeMedium"]`
- Current: $28.99, List: $33.99
### Purple Large
- PseudoId: `DEMO_VAR_PUR_LG`
- Features: `["ColorPurple", "SizeLarge"]`
- Current: $30.99, List: $35.99
### Purple XL
- PseudoId: `DEMO_VAR_PUR_XL`
- Features: `["ColorPurple", "SizeXL"]`
- Current: $32.99, List: $37.99
## Troubleshooting
### Error: "Product already has feature"
The feature is already applied. Check existing features and remove or use different features.
### Error: "No product found with ID"
You're using `pseudoId` instead of internal `productId`. Always use the internal `productId` returned from create operations.
### Error: "Invalid productFeatureId"
The feature ID doesn't exist. Use `moqui_get_screen_details` on EditProduct to see available features:
```bash
moqui_get_screen_details(
path="PopCommerce/PopCommerceAdmin/Catalog/Product/EditProduct",
fieldName="productFeatureIdList"
)
```
### Variant not showing on parent
Check that:
1. `PatVariant` association exists (Step 7)
2. Parent has `PfatSelectable` features for the same feature type
3. Variant has `PfatDistinguishing` features, not `PfatSelectable`
### Missing pricing
Prices are optional. If not set, the variant will use parent's default pricing or no pricing.]]></fileData>
</moqui.resource.DbResourceFile>
<moqui.resource.wiki.WikiPage
wikiPageId="BP/ProductVariant"
wikiSpaceId="BUSINESS_PROCESSES"
pagePath="Product-Variant-Creation"
publishedVersionName="v1"
restrictView="N">
</moqui.resource.wiki.WikiPage>
<moqui.resource.wiki.WikiPageHistory
wikiPageId="BP/ProductVariant"
historySeqId="1"
versionName="v1"
userId="EX_JOHN_DOE"
changeDateTime="2026-01-23 00:00:00.000"/>
</entity-facade-xml>
......@@ -12,7 +12,7 @@
<http://creativecommons.org/publicdomain/zero/1.0/>.
-->
<entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd">
xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd" type="seed">
<!-- MCP Prompts Wiki Space -->
<moqui.resource.wiki.WikiSpace wikiSpaceId="MCP_PROMPTS"
......
......@@ -12,7 +12,7 @@
<http://creativecommons.org/publicdomain/zero/1.0/>.
-->
<entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd">
xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd" type="seed">
<!-- MCP Screen Documentation Wiki Space -->
<moqui.resource.wiki.WikiSpace wikiSpaceId="MCP_SCREEN_DOCS"
......@@ -114,15 +114,55 @@ Use the following discovery tools to explore available functionality:
versionName="v1">
<fileData><![CDATA[# Moqui MCP Server
This server provides access to Moqui ERP through MCP. Typically you will be searching for a product by name or by a feature like size or color.
If it is a feature based query it is probably best to use the FindFeature screen to locate the feature and then use FindProduct to search for products with that feature.
This server provides access to Moqui ERP through MCP. Use the following tools to discover functionality and get help with common tasks.
## Getting Started
## Help & Discovery Tools
Use the following discovery tools to explore available functionality:
- `moqui_browse_screens`: Browse Moqui screen hierarchy
- `moqui_search_screens`: Search for screens by name to find their paths
- `moqui_get_screen_details`: Get input parameters for specific screens
Use these tools to find information:
- **`moqui_search_screens`**: Search for screens and workflows by name
- Example: `moqui_search_screens(query="variant")` finds the Product Variant Creation workflow
- Returns both screens and business process workflows
- **`moqui_browse_screens`**: Browse Moqui screen hierarchy
- Use empty path for root: `moqui_browse_screens(path="")`
- Navigate deep: `moqui_browse_screens(path="PopCommerce/Catalog/Product/FindProduct")`
- Execute actions: `moqui_browse_screens(path="...", action="createProduct", parameters={...})`
- **`moqui_get_screen_details`**: Get dropdown options and field details
- Use before submitting forms to understand available options
- Example: `moqui_get_screen_details(path="PopCommerce/Party/EditParty", fieldName="countryGeoId")`
- **`moqui_get_help`**: Get extended documentation
- Screen help: `moqui_get_help(uri="wiki:screen:EditProduct")`
- Service help: `moqui_get_help(uri="wiki:service:Product")`
- **Workflow help**: `moqui_get_help(uri="wiki:workflow:Product-Variant-Creation")`
## Business Process Workflows
Complex multi-step operations are documented as workflows. Use `moqui_search_screens` to find them:
**Example: Creating a Product Variant**
1. Search for variant workflow:
```
moqui_search_screens(query="variant")
```
Returns: `{"path": "wiki:workflow:Product-Variant-Creation", ...}`
2. Get workflow documentation:
```
moqui_get_help(uri="wiki:workflow:Product-Variant-Creation")
```
Returns: Complete 8-step guide with exact tool calls and parameters
3. Execute each step using the provided tool calls:
- Clone parent product
- Apply distinguishing features (e.g., ColorPurple, SizeSmall)
- Set pricing (Current and List prices)
- Link variant to virtual parent
The workflow documentation includes exact tool calls, expected responses, and troubleshooting guidance.
## Common Screen Paths
......@@ -148,15 +188,16 @@ Use the following discovery tools to explore available functionality:
### System & Developer Tools
- `/tools/Tools`: Developer tools, entity data editing, and service references
- `/tools/System`: System administration, cache management, and security settings
## Tips for LLM Clients
- All screens support parameterized queries for filtering results
- Use `moqui_render_screen` with screen path to execute screens
- Screen paths use forward slash notation (e.g., `/PopCommerce/PopCommerceAdmin/Catalog/Product`)
- Check `moqui_get_screen_details` for required parameters before rendering
- Use `renderMode: "mcp"` for structured JSON output or `"text"` for human-readable format]]></fileData>
- **Actions are NOT services** - Use screen actions, not direct service calls
- **Use exact parameter names** - Tool calls in workflows use precise field names
- **Extract IDs from responses** - Create operations return internal IDs (not pseudoIds) for use in subsequent steps
- **Check dropdown options** - Use `moqui_get_screen_details` to see valid values before submitting
- **Use `renderMode: "compact"`** for efficient structured output
- **Check validation errors** - Action responses include `validationErrors` with field-specific messages
- **Read `help` fields** - Actions include `help` URIs (e.g., `wiki:service:ProductAssoc`) for detailed documentation]]></fileData>
</moqui.resource.DbResourceFile>
<!-- PopCommerce Root Screen Documentation -->
......
......@@ -11,7 +11,7 @@
<https://creativecommons.org/publicdomain/zero/1.0/>. -->
<entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd">
xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd" type="seed-initial">
<!-- MCP User Groups -->
<moqui.security.UserGroup userGroupId="McpUser" description="MCP Server Users"/>
......
......@@ -2838,6 +2838,66 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
walkScreenTree(webrootSd, "", 0)
}
// Index workflows from BUSINESS_PROCESSES wiki space
try {
ec.artifactExecution.disableAuthz()
def workflowPageList = ec.entity.find("moqui.resource.wiki.WikiPage")
.condition("wikiSpaceId", "BUSINESS_PROCESSES")
.list()
for (def wp in workflowPageList) {
// Skip root page
if (wp.pagePath == "root") continue
def title = wp.pagePath
def description = ""
try {
def dbResource = ec.entity.find("moqui.resource.DbResource")
.condition("parentResourceId", "WIKI_BUSINESS_PROCESSES")
.condition("filename", wp.pagePath + ".md")
.one()
if (dbResource) {
def dbResourceFile = ec.entity.find("moqui.resource.DbResourceFile")
.condition("resourceId", dbResource.resourceId)
.one()
if (dbResourceFile && dbResourceFile.fileData) {
def content = new String(dbResourceFile.fileData.getBytes(1L, dbResourceFile.fileData.length() as int), "UTF-8")
// Extract title from first heading
def titleMatch = content =~ /^#\s+(.+)$/
if (titleMatch.find()) {
title = titleMatch.group(1)
}
// Extract first paragraph as description
def lines = content.split('\n')
for (line in lines) {
line = line.trim()
if (line && !line.startsWith('#')) {
description = line.take(200)
break
}
}
}
}
} catch (Exception e) {
ec.logger.debug("SearchScreens: Error loading workflow ${wp.pagePath}: ${e.message}")
}
screenIndex << [
path: "wiki:workflow:${wp.pagePath}",
name: title,
description: description,
type: "workflow"
]
}
ec.logger.info("SearchScreens: Indexed ${workflowPageList.size()} workflows")
} catch (Exception e) {
ec.logger.warn("SearchScreens: Error indexing workflows: ${e.message}")
}
// Cache the index
mcpCache.put(cacheKey, screenIndex)
ec.logger.info("SearchScreens: Built index with ${screenIndex.size()} screens")
......@@ -2875,8 +2935,11 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
}
// Prefer shallower screens (more likely to be entry points)
// Workflows have no depth penalty
if (score > 0) {
if (screen.type != "workflow") {
score -= (screen.depth ?: 0) * 2
}
scored << [screen: screen, score: score]
}
}
......@@ -2896,7 +2959,7 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
// Add hint if no matches
def hint = null
if (matches.isEmpty()) {
hint = "No screens found matching '${query}'. Try broader terms like 'product', 'order', 'party', or use moqui_browse_screens to explore."
hint = "No screens or workflows found matching '${query}'. Try broader terms like 'product', 'order', 'party', or use moqui_browse_screens to explore."
} else if (matches.size() >= 15) {
hint = "Showing top 15 results. Refine your search for more specific matches."
}
......@@ -3084,6 +3147,10 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
wikiSpaceId = "MCP_SERVICE_DOCS"
pagePath = pageName
break
case "workflow":
wikiSpaceId = "BUSINESS_PROCESSES"
pagePath = pageName
break
default:
wikiSpaceId = "MCP_SCREEN_DOCS"
pagePath = pageName
......@@ -3107,7 +3174,17 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
if (wikiPage) {
// Use direct DbResource/DbResourceFile lookup (like BrowseScreens does)
def parentResourceId = (wikiType == "service") ? "WIKI_MCP_SERVICE_DOCS" : "WIKI_MCP_SCREEN_DOCS"
def parentResourceId
switch (wikiType) {
case "workflow":
parentResourceId = "WIKI_BUSINESS_PROCESSES"
break
case "service":
parentResourceId = "WIKI_MCP_SERVICE_DOCS"
break
default:
parentResourceId = "WIKI_MCP_SCREEN_DOCS"
}
def dbResource = ec.entity.find("moqui.resource.DbResource")
.condition("parentResourceId", parentResourceId)
......