Ean Schuessler / mo-mcp

XML mode renders nearly empty screen hierarchy (just path structure, no content
or data), which isn't useful for MCP clients.

Remaining render modes:
- compact: structured actionable summary (default)
- aria: accessibility tree for field discovery
- text: plain text rendering
- html: full HTML rendering

Ean Schuessler committed 2026-01-21 14:50:44 -0600

These modes render Vue.js wrapper templates for web frontends, not actual
screen content. They only show outer container HTML with subscreen placeholders,
which isn't useful for MCP clients.

Remaining render modes:
- compact: structured actionable summary (default)
- aria: accessibility tree for field discovery
- text: plain text rendering
- html: full HTML rendering
- xml: XML rendering

Ean Schuessler committed 2026-01-21 14:48:21 -0600

The mcp render mode exposed too much internal detail (service names, full
metadata) which confused smaller models into trying to call services directly.

Changes:
- Remove 'mcp' from renderMode descriptions in tool definitions
- Map renderMode='mcp' to 'compact' if explicitly requested
- Update AGENTS.md to remove mcp mode documentation
- Internal rendering still uses mcp mode, just not exposed to users

Users should use:
- compact (default): actionable summary
- aria: accessibility tree for field discovery
- text/html: rendered output

Ean Schuessler committed 2026-01-21 14:46:19 -0600

Adds clear instructions in root wiki doc explaining:
- How to execute actions (use action parameter, NOT service calls)
- How to get dropdown options (use moqui_get_screen_details)
- How to get action documentation (use moqui_get_help with help URI)
- Updated screen paths to use apps/PopcAdmin format
- Added global navigation paths (Messages, Tasks, Calendar)

This helps models understand how to use the system after we removed
service names and dropdown examples from responses.

Ean Schuessler committed 2026-01-21 13:08:09 -0600

ARIA and compact modes now cleaner for smaller models:

- Remove service names from actions (confuses models into trying to call services)
- Rename 'describedby' to 'help' for clarity (points to moqui_get_help tool)
- Remove wiki:screen references (not useful, wiki content already in response)
- Fix grid row refs to use specific IDs (productFeatureId, toProductId) instead
  of repeating generic productId for all rows
- Filter navigation links: remove cross-app links, remove action URLs with
  encoded timestamps (fromDate/thruDate parameters)
- Remove dropdown options counts and random examples - just indicate type,
  use moqui_get_screen_details for actual options

This significantly reduces context volume and eliminates patterns that
caused smaller models to hallucinate service calls.

Ean Schuessler committed 2026-01-21 13:03:58 -0600

ARIA mode was truncating grid rows to 3, links to 10, and actions to 15.
This caused models to miss important data (e.g., only seeing 3 of 8 features
or 3 of 16 variant associations).

Now ARIA mode shows complete data like text mode does.

Ean Schuessler committed 2026-01-21 11:45:29 -0600

Adds globalNav array to every browse_screens response with links to:
- My Notifications (apps/my/User/Notifications)
- My Messages (apps/my/User/Messages/FindMessage)
- My Calendar (apps/my/User/Calendar/MyCalendar)
- My Tasks (apps/my/User/Task/MyTasks)

These mirror the MyAccountNav component in the web UI and are always
available regardless of which app the user is currently browsing.

Also adds a hint in uiNarrative.notes about globalNav and search.

Ean Schuessler committed 2026-01-20 23:51:44 -0600

The username parameter was being injected into screen render params, which
conflicted with FindCustomer's 'username' search field. This caused the
screen to filter results to only show customers with username matching
the current user (john.sales*), returning 0 results.

User context is already available via ec.user for authorization purposes,
so injecting these params was redundant and harmful.

Ean Schuessler committed 2026-01-20 23:24:08 -0600

Critical fix: Errors now correctly captured and reported
- Capture errors immediately after render() in CustomScreenTestImpl
- Added saveMessagesToSession() to WebFacadeStub for framework compatibility
- Actions that fail validation now report status:'error' instead of false success

Documentation fix: Clarify two different feature services
- applyProductFeatures: Apply EXISTING features to products (most common)
- createProductFeature: Create NEW feature definitions (rare)
- Updated EditProduct and ProductFeature wiki docs with correct examples

Ean Schuessler committed 2026-01-20 22:52:24 -0600

serverInfo now includes:
- hostname and ipAddress for server identification
- javaVersion and javaVendor for environment info
- serverStartTime (epoch ms) for uptime calculation
- moquiVersion, runtimePath for deployment verification
- currentUser/currentUserId for auth confirmation

Follows MCP standard - info returned via initialize response

Ean Schuessler committed 2026-01-20 22:01:33 -0600

Critical fixes:
- Set resolvedScreenDef after successful literal path resolution (was falling back to webroot)
- Traverse default subscreens when looking up transitions (matching action discovery logic)
- Build full path including subscreens for framework transition execution

New features:
- moqui_batch_operations tool for multi-step workflows
- Enhanced validation error handling with field-level details
- ARIA mode now includes value, ref, description, describedby attributes

Documentation:
- Added render modes table and examples to AGENTS.md
- Updated README with MARIA format explanation
- Added MCP_SERVICE_DOCS wiki space with service parameter docs

Ean Schuessler committed 2026-01-20 20:20:48 -0600

When looking up wiki docs for a screen, now walks up the path hierarchy
to find the most specific match. For example, for path
'Catalog/Product/EditProduct/Assocs', it tries:

1. Catalog/Product/EditProduct/Assocs (most specific)
2. Catalog/Product/EditProduct (inherits if no specific doc)
3. Catalog/Product
4. Catalog

This allows parent screen docs to apply to all child tabs/subscreens
unless overridden with more specific documentation.

Updated both getWikiInstructions (used by execute#ScreenAsMcpTool) and
loadWikiContent (used by moqui_browse_screens) to use this approach.

Ean Schuessler committed 2026-01-19 21:26:21 -0600

Clarifies that User/Messages is a container and FindMessage should be
used for full functionality (actions, transitions).

Ean Schuessler committed 2026-01-19 20:56:33 -0600

Shows screen-transition actions like editMessage, messageThread in a
'transitions' array. Filters out internal actions (formSelectColumns,
formSaveFind, screenDoc, actions).

Ean Schuessler committed 2026-01-19 20:49:59 -0600

- Updated PartyMessages wiki docs to emphasize partyId is required
- Added missingRequired and error fields to compact format when
  required parameters are missing
- This helps LLMs understand why a screen shows no forms/grids

Ean Schuessler committed 2026-01-19 20:44:31 -0600

Added MCP screen documentation for:
- FindParty: Quick actions for creating people, orgs, accounts, employees
- EditParty: Party detail management, roles, classifications, user accounts
- PartyMessages/FindMessage: Internal messaging between parties
- FindProduct: Product search and creation, variant workflow overview
- EditProduct: Features, associations, complete variant setup guide

Each doc includes example action calls with parameters.

Ean Schuessler committed 2026-01-19 20:31:46 -0600

- Add compact render mode (now default): LLM-optimized ~75% smaller output
  - Shows forms with fields, grids with sample rows, actions with services
  - Truncates dropdown options with fetch hints

- Add ARIA render mode: W3C accessibility tree format
  - Maps Moqui fields to ARIA roles (textbox, combobox, checkbox, etc.)

- Fix action execution to use framework transitions
  - Actions now append to screen path for proper transition handling
  - Framework handles inheritance, pre/post actions, response handling

- Fix CSRF bypass for MCP requests
  - Set moqui.request.authenticated=true in MockHttpServletRequest attributes

Ean Schuessler committed 2026-01-19 20:29:33 -0600

- Remove remaining isTerse references from UiNarrativeBuilder
- Truncate dropdown options to 10 in browse_screens with fetchHint
- get_screen_details returns full options via mcpFullOptions flag
- Extract wiki summary as top-level field in responses
- Add extractSummary helper for first non-header paragraph

Ean Schuessler committed 2026-01-19 19:32:33 -0600

- Fix sri.getFieldOptions() call to pass drop-down node instead of parent field node
- Remove terse parameter from all services and serialization
- Increase safety limits by 10x: lists 10K items, strings 1MB, unknown types 10K chars
- Add form-list field metadata extraction in FTL macros
- Simplify McpFieldOptionsService to use CustomScreenTestImpl approach
- Clean up redundant _fixed.groovy file

Ean Schuessler committed 2026-01-19 15:46:51 -0600

- Extract service name and in-map from transition XML
- Capture depends-on parameter attribute for field name mapping
- Parse in-map parameter mapping for proper service calls
- Support server-search autocomplete with term parameter
- Fallback to ScreenAsMcpTool for entity-find transitions
- Enhanced response format detection and error handling

This implements TODO 1-3 from AGENTS.md:
- TODO 1: Capture Depends-on Parameter Attribute
- TODO 2: Extract Transition Service Name
- TODO 3: Parse in-map Parameter Mapping

Files modified:
- DefaultScreenMacros.mcp.ftl: Extract transition metadata during screen render
- McpFieldOptionsService.groovy: Use extracted metadata for intelligent autocomplete

Ean Schuessler committed 2026-01-15 11:57:20 -0600

Ean Schuessler committed 2026-01-13 18:36:41 -0600

Error Handling:
- Check ec.message.hasError() before and after transaction flush
- Return "status": "error" with error messages instead of false success
- Prevents silent failures when constraint violations occur (e.g., invalid Party IDs)

Dropdown Metadata:
- Capture static dropdown options from sri.getFieldOptions()
- Capture dynamic-options config (transition, serverSearch, minLength, parameterMap)
- Enables model to understand searchable dropdowns vs static lists

This improves the model's ability to:
1. See clear error messages when operations fail
2. Understand dropdown behavior (server search vs static)
3. Take corrective action based on error feedback

Ean Schuessler committed 2026-01-13 18:29:36 -0600

Fix path references in data files to use forward slash notation:
- /PopCommerce/PopCommerceAdmin.Catalog.Product → /PopCommerce/PopCommerceAdmin/Catalog/Product
- /PopCommerce/PopCommerceAdmin.Order.FindOrder → /PopCommerce/PopCommerceAdmin/Order/FindOrder
- /PopCommerce/PopCommerceRoot.Customer → /PopCommerce/PopCommerceRoot/Customer

Also updates:
- AGENTS.md: Remove completed path delimiter test items
- Fix wiki page path references (SimpleScreens.Root → SimpleScreens/Root)

Aligns with slash-based path system adopted in earlier refactor.

Ean Schuessler committed 2026-01-13 15:10:30 -0600

Ean Schuessler committed 2026-01-13 13:32:19 -0600

- EnhancedMcpServlet: Reuse existing ExecutionContext from MoquiAuthFilter instead of creating duplicate
- EnhancedMcpServlet: Removed manual EC destruction - auth filter handles cleanup
- McpServices: Skip EntityFind objects in serialization (they're query definitions, not data)
- McpServices: Make patchScreenRenderForNullFieldNode static for call from static context
- McpServices: Remove renderedContent for renderMode 'mcp' to avoid JSON duplication/truncation
- AGENTS.md: Document rebuild.sh script usage
- mcp.sh: Use hidden session file (.mcp_session_USER)
- rebuild.sh: Fix shell syntax error and add startup wait logic

Ean Schuessler committed 2026-01-13 13:28:59 -0600

Move verbose per-request logging (request body, session management,
SSE connections, method processing) from INFO to DEBUG level.
Keep INFO for significant events like new Visit creation.

Ean Schuessler committed 2026-01-13 00:43:23 -0600

- Terse mode: 50 items/5000 chars (from 30/2000)
- Non-terse mode: 1000 items/50000 chars (from 250/5000)
- Prioritizes operational data completeness over token savings
- Prevents "ghost errors" from arbitrary data dropping

Ean Schuessler committed 2026-01-13 00:14:20 -0600

- Add field types: radio, display, link, file-upload, hidden
- Add link types: action, delete, external, button
- Add action types: service-action, form-action, screen-transition, delete-action
- Enhance parameter metadata with type, required, defaultValue
- Classify actions automatically by service/name patterns
- Update narrative builder to describe action/link types
- Defensive parameter extraction with reflection fallbacks

Ean Schuessler committed 2026-01-12 23:49:56 -0600

- Safe navigation of formNode and fieldNode attributes using ?parent
- Fallback to empty string for null field values in display/text macros
- Use getActiveScreenDef() for screen name resolution in formListWidget
- Prevents NullPointerException in EditPrices and other list screens.

Ean Schuessler committed 2026-01-12 23:39:23 -0600

- Resolve NonHashException in macros by avoiding .add() on sequences.
- Fix 'Maps with null keys' JSON error by ensuring string keys.
- Stabilize form macros with null-safe checks.
- Update McpServices and CustomScreenTestImpl for better semantic data handling.

Ean Schuessler committed 2026-01-12 23:30:44 -0600

Extract core MCP logic into modular services (ResolveScreenPath, RenderScreenNarrative, ExecuteScreenAction) and update screen path conventions to use slash notation (e.g., /PopCommerce/Product) instead of dot notation. This aligns MCP navigation with browser URLs and improves path resolution reliability.

- Split McpServices.xml into specialized services for better maintainability
- Update DefaultScreenMacros.mcp.ftl to generate slash-based links
- Update prompts and documentation to reflect new path convention
- Enhance CustomScreenTestImpl to support slash path parsing
- Add AGENTS.md documenting self-guided narrative screens architecture

Ean Schuessler committed 2026-01-12 22:49:06 -0600

- Create UiNarrativeBuilder class for structured, story-like UI descriptions
  - screen: 50-80 words describing current state
  - actions: 80-120 words with exact tool invocation examples
  - navigation: 30-40 words for navigating to related screens
  - notes: 30-50 words for truncation, permissions, constraints

- Enhance mcp.ftl macros to capture semantic metadata
  - form-single: Track field names, types, validation rules
  - form-list: Capture totalItems, displayedItems, truncated flags
  - Store metadata in mcpSemanticData for narrative generation

- Deprecate DefaultScreenMacros.json.ftl
  - Update MoquiConf.xml to map both mcp and json to mcp.ftl
  - Remove redundant 218-line template with no semantic capture

- Integrate uiNarrative into BrowseScreens service
  - Generate narrative using UiNarrativeBuilder
  - Include uiNarrative in result map
  - Provide screenDef for context

- Remove redundant semantic state extraction
  - Delete fallback logic that extracted forms/lists from screen definition
  - Rely exclusively on mcpSemanticData captured by macros

- Improve smart truncation in serializeMoquiObject
  - terse mode: 10 items, 200 char strings
  - non-terse mode: 50 items, no string truncation (fixed bug)
  - Add _hasMore flag to truncated data metadata

- Fix CustomScreenTestImpl postRenderContext capture
  - Capture context before pop to preserve mcpSemanticData

Ean Schuessler committed 2026-01-09 21:12:43 -0600

Ean Schuessler committed 2026-01-09 16:57:09 -0600

Ean Schuessler committed 2026-01-05 13:57:13 -0600

Ean Schuessler committed 2026-01-02 18:57:48 -0600

Ean Schuessler committed 2026-01-02 18:45:53 -0600

- Remove McpScreenDoc entity and mapping layer
- Use screen paths directly as WikiPage.pagePath
- Fix historySeqId from string "01" to numeric "1"
- Fix DbResourceFile fileData to use CDATA for complex content
- Add wiki descriptions to BrowseScreens subscreens
- Update BrowseScreens to query WikiPage directly by screenPath
- Remove duplicate/corrupt data entries from McpScreenDocsData.xml

Ean Schuessler committed 2026-01-02 18:30:38 -0600

- Update build.gradle: jakarta.servlet-api:6.1.0
- Update EnhancedMcpServlet.groovy: Jakarta imports and servlet attributes
- Update WebFacadeStub.groovy: Complete Jakarta migration
  - New Servlet 6.0 methods (getRequestId, getProtocolRequestId, getServletConnection)
  - Removed deprecated methods (getSessionContext, getRealPath, etc.)
  - New sendRedirect(String, int, boolean) overload
- Update TestHealthServlet.java: Jakarta servlet imports

Aligns with upstream framework migration to Jakarta EE.

Ean Schuessler committed 2026-01-02 14:02:15 -0600

- Load McpPromptsData.xml seed data for prompt templates
- Add data load to component.xml

Ean Schuessler committed 2025-12-31 12:46:34 -0600

- Fix inputSchema properties to use quoted string keys for proper JSON Schema format
- Remove debug logging added for Accept header troubleshooting
- Remove unnecessary tools/list workaround in mcp#ToolsCall service
- The properties field in inputSchema must be a record/object, not an array
- All 6 tool schemas now properly defined with string keys: "path", "action", "renderMode", "parameters", "query", "name", "arguments"

Ean Schuessler committed 2025-12-31 12:46:11 -0600