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
Expand all
Inline Side-by-side
Showing 5 changed files with 139 additions and 21 deletions
...@@ -12,7 +12,7 @@ ...@@ -12,7 +12,7 @@
12 <http://creativecommons.org/publicdomain/zero/1.0/>. 12 <http://creativecommons.org/publicdomain/zero/1.0/>.
13 --> 13 -->
14 <entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 14 <entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
15 xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd"> 15 xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd" type="seed">
16 16
17 <!-- MCP Prompts Wiki Space --> 17 <!-- MCP Prompts Wiki Space -->
18 <moqui.resource.wiki.WikiSpace wikiSpaceId="MCP_PROMPTS" 18 <moqui.resource.wiki.WikiSpace wikiSpaceId="MCP_PROMPTS"
......
...@@ -12,7 +12,7 @@ ...@@ -12,7 +12,7 @@
12 <http://creativecommons.org/publicdomain/zero/1.0/>. 12 <http://creativecommons.org/publicdomain/zero/1.0/>.
13 --> 13 -->
14 <entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 14 <entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
15 xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd"> 15 xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd" type="seed">
16 16
17 <!-- MCP Screen Documentation Wiki Space --> 17 <!-- MCP Screen Documentation Wiki Space -->
18 <moqui.resource.wiki.WikiSpace wikiSpaceId="MCP_SCREEN_DOCS" 18 <moqui.resource.wiki.WikiSpace wikiSpaceId="MCP_SCREEN_DOCS"
...@@ -112,17 +112,57 @@ Use the following discovery tools to explore available functionality: ...@@ -112,17 +112,57 @@ Use the following discovery tools to explore available functionality:
112 resourceId="WIKI_MCP_DOCS_ROOT" 112 resourceId="WIKI_MCP_DOCS_ROOT"
113 mimeType="text/markdown" 113 mimeType="text/markdown"
114 versionName="v1"> 114 versionName="v1">
115 <fileData><![CDATA[# Moqui MCP Server 115 <fileData><![CDATA[# Moqui MCP Server
116 116
117 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. 117 This server provides access to Moqui ERP through MCP. Use the following tools to discover functionality and get help with common tasks.
118 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.
119 118
120 ## Getting Started 119 ## Help & Discovery Tools
121 120
122 Use the following discovery tools to explore available functionality: 121 Use these tools to find information:
123 - `moqui_browse_screens`: Browse Moqui screen hierarchy 122
124 - `moqui_search_screens`: Search for screens by name to find their paths 123 - **`moqui_search_screens`**: Search for screens and workflows by name
125 - `moqui_get_screen_details`: Get input parameters for specific screens 124 - Example: `moqui_search_screens(query="variant")` finds the Product Variant Creation workflow
125 - Returns both screens and business process workflows
126
127 - **`moqui_browse_screens`**: Browse Moqui screen hierarchy
128 - Use empty path for root: `moqui_browse_screens(path="")`
129 - Navigate deep: `moqui_browse_screens(path="PopCommerce/Catalog/Product/FindProduct")`
130 - Execute actions: `moqui_browse_screens(path="...", action="createProduct", parameters={...})`
131
132 - **`moqui_get_screen_details`**: Get dropdown options and field details
133 - Use before submitting forms to understand available options
134 - Example: `moqui_get_screen_details(path="PopCommerce/Party/EditParty", fieldName="countryGeoId")`
135
136 - **`moqui_get_help`**: Get extended documentation
137 - Screen help: `moqui_get_help(uri="wiki:screen:EditProduct")`
138 - Service help: `moqui_get_help(uri="wiki:service:Product")`
139 - **Workflow help**: `moqui_get_help(uri="wiki:workflow:Product-Variant-Creation")`
140
141 ## Business Process Workflows
142
143 Complex multi-step operations are documented as workflows. Use `moqui_search_screens` to find them:
144
145 **Example: Creating a Product Variant**
146
147 1. Search for variant workflow:
148 ```
149 moqui_search_screens(query="variant")
150 ```
151 Returns: `{"path": "wiki:workflow:Product-Variant-Creation", ...}`
152
153 2. Get workflow documentation:
154 ```
155 moqui_get_help(uri="wiki:workflow:Product-Variant-Creation")
156 ```
157 Returns: Complete 8-step guide with exact tool calls and parameters
158
159 3. Execute each step using the provided tool calls:
160 - Clone parent product
161 - Apply distinguishing features (e.g., ColorPurple, SizeSmall)
162 - Set pricing (Current and List prices)
163 - Link variant to virtual parent
164
165 The workflow documentation includes exact tool calls, expected responses, and troubleshooting guidance.
126 166
127 ## Common Screen Paths 167 ## Common Screen Paths
128 168
...@@ -148,15 +188,16 @@ Use the following discovery tools to explore available functionality: ...@@ -148,15 +188,16 @@ Use the following discovery tools to explore available functionality:
148 188
149 ### System & Developer Tools 189 ### System & Developer Tools
150 - `/tools/Tools`: Developer tools, entity data editing, and service references 190 - `/tools/Tools`: Developer tools, entity data editing, and service references
151 - `/tools/System`: System administration, cache management, and security settings
152 191
153 ## Tips for LLM Clients 192 ## Tips for LLM Clients
154 193
155 - All screens support parameterized queries for filtering results 194 - **Actions are NOT services** - Use screen actions, not direct service calls
156 - Use `moqui_render_screen` with screen path to execute screens 195 - **Use exact parameter names** - Tool calls in workflows use precise field names
157 - Screen paths use forward slash notation (e.g., `/PopCommerce/PopCommerceAdmin/Catalog/Product`) 196 - **Extract IDs from responses** - Create operations return internal IDs (not pseudoIds) for use in subsequent steps
158 - Check `moqui_get_screen_details` for required parameters before rendering 197 - **Check dropdown options** - Use `moqui_get_screen_details` to see valid values before submitting
159 - Use `renderMode: "mcp"` for structured JSON output or `"text"` for human-readable format]]></fileData> 198 - **Use `renderMode: "compact"`** for efficient structured output
199 - **Check validation errors** - Action responses include `validationErrors` with field-specific messages
200 - **Read `help` fields** - Actions include `help` URIs (e.g., `wiki:service:ProductAssoc`) for detailed documentation]]></fileData>
160 </moqui.resource.DbResourceFile> 201 </moqui.resource.DbResourceFile>
161 202
162 <!-- PopCommerce Root Screen Documentation --> 203 <!-- PopCommerce Root Screen Documentation -->
......
...@@ -11,7 +11,7 @@ ...@@ -11,7 +11,7 @@
11 <https://creativecommons.org/publicdomain/zero/1.0/>. --> 11 <https://creativecommons.org/publicdomain/zero/1.0/>. -->
12 12
13 <entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 13 <entity-facade-xml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
14 xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd"> 14 xsi:noNamespaceSchemaLocation="http://moqui.org/xsd/entity-facade-3.xsd" type="seed-initial">
15 15
16 <!-- MCP User Groups --> 16 <!-- MCP User Groups -->
17 <moqui.security.UserGroup userGroupId="McpUser" description="MCP Server Users"/> 17 <moqui.security.UserGroup userGroupId="McpUser" description="MCP Server Users"/>
......
...@@ -2837,7 +2837,67 @@ def wikiInstructions = getWikiInstructions(inputScreenPath) ...@@ -2837,7 +2837,67 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
2837 if (webrootSd) { 2837 if (webrootSd) {
2838 walkScreenTree(webrootSd, "", 0) 2838 walkScreenTree(webrootSd, "", 0)
2839 } 2839 }
2840 2840
2841 // Index workflows from BUSINESS_PROCESSES wiki space
2842 try {
2843 ec.artifactExecution.disableAuthz()
2844 def workflowPageList = ec.entity.find("moqui.resource.wiki.WikiPage")
2845 .condition("wikiSpaceId", "BUSINESS_PROCESSES")
2846 .list()
2847
2848 for (def wp in workflowPageList) {
2849 // Skip root page
2850 if (wp.pagePath == "root") continue
2851 def title = wp.pagePath
2852 def description = ""
2853
2854 try {
2855 def dbResource = ec.entity.find("moqui.resource.DbResource")
2856 .condition("parentResourceId", "WIKI_BUSINESS_PROCESSES")
2857 .condition("filename", wp.pagePath + ".md")
2858 .one()
2859
2860 if (dbResource) {
2861 def dbResourceFile = ec.entity.find("moqui.resource.DbResourceFile")
2862 .condition("resourceId", dbResource.resourceId)
2863 .one()
2864
2865 if (dbResourceFile && dbResourceFile.fileData) {
2866 def content = new String(dbResourceFile.fileData.getBytes(1L, dbResourceFile.fileData.length() as int), "UTF-8")
2867
2868 // Extract title from first heading
2869 def titleMatch = content =~ /^#\s+(.+)$/
2870 if (titleMatch.find()) {
2871 title = titleMatch.group(1)
2872 }
2873
2874 // Extract first paragraph as description
2875 def lines = content.split('\n')
2876 for (line in lines) {
2877 line = line.trim()
2878 if (line && !line.startsWith('#')) {
2879 description = line.take(200)
2880 break
2881 }
2882 }
2883 }
2884 }
2885 } catch (Exception e) {
2886 ec.logger.debug("SearchScreens: Error loading workflow ${wp.pagePath}: ${e.message}")
2887 }
2888
2889 screenIndex << [
2890 path: "wiki:workflow:${wp.pagePath}",
2891 name: title,
2892 description: description,
2893 type: "workflow"
2894 ]
2895 }
2896 ec.logger.info("SearchScreens: Indexed ${workflowPageList.size()} workflows")
2897 } catch (Exception e) {
2898 ec.logger.warn("SearchScreens: Error indexing workflows: ${e.message}")
2899 }
2900
2841 // Cache the index 2901 // Cache the index
2842 mcpCache.put(cacheKey, screenIndex) 2902 mcpCache.put(cacheKey, screenIndex)
2843 ec.logger.info("SearchScreens: Built index with ${screenIndex.size()} screens") 2903 ec.logger.info("SearchScreens: Built index with ${screenIndex.size()} screens")
...@@ -2875,8 +2935,11 @@ def wikiInstructions = getWikiInstructions(inputScreenPath) ...@@ -2875,8 +2935,11 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
2875 } 2935 }
2876 2936
2877 // Prefer shallower screens (more likely to be entry points) 2937 // Prefer shallower screens (more likely to be entry points)
2938 // Workflows have no depth penalty
2878 if (score > 0) { 2939 if (score > 0) {
2879 score -= (screen.depth ?: 0) * 2 2940 if (screen.type != "workflow") {
2941 score -= (screen.depth ?: 0) * 2
2942 }
2880 scored << [screen: screen, score: score] 2943 scored << [screen: screen, score: score]
2881 } 2944 }
2882 } 2945 }
...@@ -2896,7 +2959,7 @@ def wikiInstructions = getWikiInstructions(inputScreenPath) ...@@ -2896,7 +2959,7 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
2896 // Add hint if no matches 2959 // Add hint if no matches
2897 def hint = null 2960 def hint = null
2898 if (matches.isEmpty()) { 2961 if (matches.isEmpty()) {
2899 hint = "No screens found matching '${query}'. Try broader terms like 'product', 'order', 'party', or use moqui_browse_screens to explore." 2962 hint = "No screens or workflows found matching '${query}'. Try broader terms like 'product', 'order', 'party', or use moqui_browse_screens to explore."
2900 } else if (matches.size() >= 15) { 2963 } else if (matches.size() >= 15) {
2901 hint = "Showing top 15 results. Refine your search for more specific matches." 2964 hint = "Showing top 15 results. Refine your search for more specific matches."
2902 } 2965 }
...@@ -3084,6 +3147,10 @@ def wikiInstructions = getWikiInstructions(inputScreenPath) ...@@ -3084,6 +3147,10 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
3084 wikiSpaceId = "MCP_SERVICE_DOCS" 3147 wikiSpaceId = "MCP_SERVICE_DOCS"
3085 pagePath = pageName 3148 pagePath = pageName
3086 break 3149 break
3150 case "workflow":
3151 wikiSpaceId = "BUSINESS_PROCESSES"
3152 pagePath = pageName
3153 break
3087 default: 3154 default:
3088 wikiSpaceId = "MCP_SCREEN_DOCS" 3155 wikiSpaceId = "MCP_SCREEN_DOCS"
3089 pagePath = pageName 3156 pagePath = pageName
...@@ -3107,7 +3174,17 @@ def wikiInstructions = getWikiInstructions(inputScreenPath) ...@@ -3107,7 +3174,17 @@ def wikiInstructions = getWikiInstructions(inputScreenPath)
3107 3174
3108 if (wikiPage) { 3175 if (wikiPage) {
3109 // Use direct DbResource/DbResourceFile lookup (like BrowseScreens does) 3176 // Use direct DbResource/DbResourceFile lookup (like BrowseScreens does)
3110 def parentResourceId = (wikiType == "service") ? "WIKI_MCP_SERVICE_DOCS" : "WIKI_MCP_SCREEN_DOCS" 3177 def parentResourceId
3178 switch (wikiType) {
3179 case "workflow":
3180 parentResourceId = "WIKI_BUSINESS_PROCESSES"
3181 break
3182 case "service":
3183 parentResourceId = "WIKI_MCP_SERVICE_DOCS"
3184 break
3185 default:
3186 parentResourceId = "WIKI_MCP_SCREEN_DOCS"
3187 }
3111 3188
3112 def dbResource = ec.entity.find("moqui.resource.DbResource") 3189 def dbResource = ec.entity.find("moqui.resource.DbResource")
3113 .condition("parentResourceId", parentResourceId) 3190 .condition("parentResourceId", parentResourceId)
......