Author navigation over MCP/PED via generic ped_update_document path-ops (split nav out of the security 'no PED path' bundle)

[ako]

Summary

Navigation (profiles, home page, menu items) is not authorable over the MCP/PED backend today — UpdateNavigationProfile, GetNavigation, and ListNavigationDocuments all return errUnsupported (mdl/backend/mcp/unsupported_gen.go:517, 730, 1130), and capabilities.yaml lumps navigation in with security under one blanket row:

- key: security_integrations_nav
  feature: "Security (roles, access, demo users), Navigation, OData/REST, mappings, settings"
  available: false
  note: "no PED write path"

That bundling is wrong for navigation. Maia (which drives the same in-Studio-Pro MCP server PED exposes) does modify project navigation — so a write path exists. PED ships generic document tools (ped_find_document, ped_read_document, ped_update_document), and the Navigation document is a regular project document. It is almost certainly editable via ped_update_document JSON-pointer path-ops — the exact mechanism the entity-attribute-default feature already uses (domainmodel.go applyAttributeDefaults → /entities/N/attributes/M/value/defaultValue).

So this is a wiring gap in mxcli, not a PED limitation. (Security/roles/access genuinely lack a PED write path and should stay blocked pending a later Studio Pro release — keep them separate.)

Goal

Author navigation over --mcp to the same extent the local MDL engine does: create or replace navigation, home page, nested menus, menu items → page references.

Proposed approach

1. Probe (live 11.12 session): ped_find_document for the Navigation document; ped_read_document it; inspect the schema via ped_get_schema. Confirm the JSON shape of profiles → menuItemCollection → items.
2. Map types.NavigationProfileSpec onto ped_update_document path-ops (replace the profile's menu / home page), mirroring applyAttributeDefaults. Implement GetNavigation via ped_read_document so read-modify-write works.
3. Split capabilities.yaml: break navigation out of security_integrations_nav into its own navigation key; flip to available: true once wired. Leave security/integrations blocked.
4. Reject honestly for any navigation construct the path-op can't express, rather than dropping it.
5. Update docs/03-development/PED_MCP_CAPABILITIES.md.

Context

Surfaced while assessing MCP/PED parity for the ExpenseApproval project (11.12, authored by Maia): the menu Maia added (Expenses / My Tasks / Admin submenu) is the one model artifact, besides pages (blocked by #pg_patch_page) and theming (out of model scope), that mxcli's MCP backend currently can't reproduce — and unlike PED security, it should be reproducible.

[github-actions]

Issue Triage

Summary:
The issue requests adding the ability to author navigation (profiles, home page, menu items) via the MCP/PED backend in mxcli by using generic ped_update_document path‑ops, and to separate navigation from the bundled “security + navigation” capability entry.

Checklist for feature request

Required info	Present?	Details
Use case – why the feature is needed / problem it solves	✅	Described in the “Context” and “Goal”: navigation authored by Maia in Studio Pro cannot be reproduced via mxcli’s MCP backend, blocking full project reproduction.
Proposed syntax or behavior (if applicable)	✅	Outlined in the “Proposed approach”: probe the Navigation document, map NavigationProfileSpec to ped_update_document path‑ops, implement GetNavigation via ped_read_document, split capabilities.yaml, etc.
Mendix version relevance (if version‑specific)	✅	Mentions testing on Mendix 11.12 (ExpenseApproval project) and notes that the capability should work for that version and later.

Verdict:
All required information for a feature request is present. Thank you for the detailed proposal! 🙌

---

Automated triage via OpenRouter — workflow source

[github-actions]

Enhancement Implementation Guide

Implementation Guide: Author Navigation over MCP/PED via Generic Document Tools

1. Completeness Assessment

The issue provides sufficient detail for implementation:

• Mendix version: Explicitly mentions 11.12 (tested with ExpenseApproval project)
• Desired mechanism: Use ped_update_document JSON-pointer path-ops (mirroring applyAttributeDefaults pattern)
• Key concepts involved: Navigation profiles, home pages, menu collections, menu items → page references
• Missing details for investigation:
  • Exact BSON structure of Navigation document (to be investigated via probing)
  • Whether navigation document uses qualified names or storage names in BSON (critical for correctness)
  • Specific JSON paths for home page/menu items within the navigation document

Recommended clarification questions (if proceeding without investigation):

1. What is the qualified name/storage name of the Navigation document in the MPR?
2. Does the Navigation document contain multiple profiles (e.g., Responsive, Tablet) or is it a singleton?
3. Are menu items stored as direct children or nested within a menuItemCollection object?

2. Overlap Check

Existing capabilities that partially cover this:

• Generic document tools (ped_find_document, ped_read_document, ped_update_document) already exist in the MCP backend
• applyAttributeDefaults in domainmodel.go demonstrates the exact path-op pattern to replicate
• Local MDL engine already supports full navigation syntax (CREATE/REPLACE navigation, home pages, menus)
• ListNavigationDocuments is already implemented but returns errUnsupported - needs rewiring to use generic document list

No full overlap exists because:

• Current MCP backend returns errUnsupported for all navigation methods (UpdateNavigationProfile, GetNavigation, ListNavigationDocuments)
• Security/integrations remain blocked (genuine PED limitation) - navigation is separable

3. Proposed MDL Syntax

No new MDL syntax needed - navigation syntax is already implemented in the local engine. Verify existing syntax follows guidelines:

-- Valid existing syntax (from MDL Quick Reference)
create or replace navigation Responsive
  home page MyModule.Home_Web
  home page MyModule.AdminHome for MyModule.Administrator
  login page Administration.Login
  not found page MyModule.Custom404
  menu (
    menu item 'Home' page MyModule.Home_Web;
    menu 'Admin' (
      menu item 'Users' page Administration.Account_Overview;
    );
  );

Syntax validation against guidelines:

• ✅ Uses standard create/alter/drop pattern (create or replace navigation)
• ✅ Uses qualified names (Module.PageName)
• ✅ Property lists use (key: value, ...) format (home page, login page, menu blocks)
• ✅ Reads as English: "create or replace navigation Responsive home page MyModule.Home_Web"
• ✅ One example sufficient for LLM generation (shows nested menus, conditional home pages)
• ✅ Diff-friendly: Adding a menu item is one-line change inside menu block
• ✅ No keyword overloading (uses established navigation terms: home page, login page, menu)
• ✅ No implicit context (all references explicitly qualified)

4. Implementation Roadmap

Follow the full-stack pipeline focusing on MCP/PED backend implementation (no MDL syntax changes needed):

A. Backend Method Implementation (mdl/backend/mcp/)

1. Replace errUnsupported with real implementations in unsupported_gen.go:

   • GetNavigation → Implement via ped_read_document + BSON→NavigationProfileSpec conversion
   • UpdateNavigationProfile → Implement via ped_update_document with JSON path-ops (mirror applyAttributeDefaults)
   • ListNavigationDocuments → Implement via ped_find_document for Navigation document type

2. Key files to modify:

   • mdl/backend/mcp/unsupported_gen.go:
     • Remove navigation methods from unsupported list (lines 517, 730, 1130)
     • Add real implementations in mcpBackend struct
   • mdl/backend/mcp/mcp.go:
     • Add helper methods for navigation document BSON conversion
     • Implement JSON path-op generation for navigation updates

3. Pattern to follow (from domainmodel.go applyAttributeDefaults):

   // Example path-op structure for home page update
   ops := []map[string]interface{}{
     {
       "op":    "replace",
       "path":  "/homePage/Web", // JSON pointer to home page field
       "value": bson.M{          // BSON value for page reference
         "$type": "pageregistrations$PageReference",
         "PageID": pageID,       // Resolved from qualified name
       },
     },
   }

B. Capabilities Update

1. Split capabilities.yaml:
   • Replace security_integrations_nav with:

     - key: navigation
       feature: "Navigation (profiles, home page, menu items)"
       available: true   // Set to false initially, flip to true after implementation
       note: "MCP/PED write path via generic document tools"

   • Keep security_integrations_nav renamed to security_integrations (security/integrations/OData/mappings/settings) with available: false

C. Documentation Update

1. Update docs/03-development/PED_MCP_CAPABILITIES.md:
   • Add navigation to supported features table
   • Document any limitations (e.g., "complex menu animations not supported via path-ops")

5. BSON Investigation

Critical steps to understand Navigation document structure:

1. Create reference project in Studio Pro:

   • Create navigation profile with:
     • Home page (web/tablet)
     • Login page
     • Nested menu structure (2+ levels)
     • Menu items pointing to pages

2. Dump BSON using mxcli:

   # Find Navigation document ID
   mxcli -p test.mpr -c "select Id, QualifiedName from CATALOG.Documents where QualifiedName = 'Navigation'"
   
   # Dump raw BSON
   mxcli bson dump -p test.mpr --type document --object "Navigation" --pretty

3. Key structures to verify:

   • Storage name in $type field (expect navigation$NavigationDocument or similar)
   • Location of profiles (likely /profileCollection array)
   • Structure of a single profile:
     • homePage (web/tablet) fields
     • loginPage reference
     • menuItemCollection → nested menu items
   • How menu items store:
     • Caption (string)
     • Page reference (BSON object with $type and PageID)
     • Submenu indicator

4. Verify with mx tool:

   # Alternative BSON inspection
   mx get -p test.mpr --type navigation --object Navigation --format json

Expected BSON patterns (based on similar documents):

• Page references use pageregistrations$PageReference type with PageID binary ID
• Collections use arrays of objects with $type and ID fields
• String values stored directly (no indirection)

6. Testing Strategy

Progressive validation approach:

A. Unit Tests (MCP backend)

1. Test BSON conversion helpers:
   • Test navigationProfileSpecToBSON() with various menu structures
   • Test BSONToNavigationProfileSpec() roundtrip
2. Test path-op generation:
   • Verify home page update generates correct /homePage/Web path-op
   • Verify nested menu item insertion uses correct array indexing

B. Integration Tests (mxcli end-to-end)

1. Add doctest to mdl-examples/doctype-tests/:

   # Add to 09-navigation-examples.mdl
   create or replace navigation TestNav
     home page Module.Home_Web
     login page Module.Login
     menu (
       menu item 'Dashboard' page Module.Dashboard;
       menu 'Settings' (
         menu item 'Profile' page Module.Profile;
         menu item 'Logout' page Module.Logout;
       );
     );
   

2. Test flow:

   # 1. Create navigation via MDL over MCP
   mxcli --mcp localhost:8080 -p test.mpr -c "exec navigation_test.mdl"
   
   # 2. Verify via describe
   mxcli --mcp localhost:8080 -p test.mpr -c "describe navigation TestNav"
   
   # 3. Verify in Studio Pro (open project, check navigation structure)

C. Backend Contract Tests

1. Verify MCP method implementations:
   • Mock ped_read_document to return known Navigation BSON
   • Assert GetNavigation returns expected profile spec
   • Mock ped_update_document to capture path-ops
   • Assert UpdateNavigationProfile generates correct ops for home page change

D. Version Compatibility

1. Add to sdk/versions/mendix-11.yaml:

   navigation:
     min_version: "10.18.0"  # Navigation introduced in 10.18

2. Add executor pre-check:

   func (b *mcpBackend) GetNavigation(ctx context.Context, req *GetNavigationRequest) (*GetNavigationResponse, error) {
     if !ctx.FeatureEnabled("navigation") {
       return nil, mdlerrors.NewFeatureNotAvailable("navigation")
     }
     // ... implementation
   }

7. Gotchas & Risks

Critical pitfalls to avoid:

1. Storage name vs qualified name:

   • Risk: Using qualified name (Module.Page) in BSON instead of storage name (pageregistrations$PageReference)
   • Mitigation: Always resolve qualified name → element ID → BSON reference via modelsdk lookup (like applyAttributeDefaults does for attributes)

2. Missing BSON defaults:

   • Risk: Omitting required fields in Navigation document (e.g., isDefault flag on profiles)
   • Mitigation:
     • Study reference BSON from Studio Pro to identify required fields
     • Apply same pattern as applyAttributeDefaults: preserve existing fields, only update targeted paths
     • Use ped_read_document first to get current state before updating

3. JSON pointer complexity:

   • Risk: Incorrect path syntax for nested menus (e.g., /menuItemCollection/0/items/1/caption)
   • Mitigation:
     • Implement path builder helper (like buildJSONPointer("menuItemCollection", index, "items", subIndex, "caption"))
     • Validate paths against known-good BSON structure from investigation

4. Partial update hazards:

   • Risk: Overwriting entire menu collection when updating single item
   • Mitigation: Use replace ops targeting specific array indices (not wholesale collection replacement)

5. Capabilities.yaml split:

   • Risk: Forgetting to update dependent documentation/tooling
   • Mitigation:
     • Update docs/03-development/PED_MCP_CAPABILITIES.md explicitly
     • Run make sync-commands to propagate to embedded skills
     • Verify mxcli dev:review checks capability flags

CE error codes to watch for:

• CE0463: If widget templates mismatch (less likely for navigation)
• CE0002: "Unknown type" if using wrong BSON $type (verify storage name!)
• CE0663: "Invalid document" if missing required Navigation document fields
• CE0425: "Invalid property" if JSON path points to non-existent field

Final validation:

Always test roundtrip:

1. Create navigation via Studio Pro
2. Read via mxcli MCP
3. Modify via mxcli MCP
4. Verify in Studio Pro opens without errors
5. Confirm menu behavior matches expectations at runtime

This implementation closes the wiring gap by leveraging existing generic document tools - no new MDL syntax or backend abstractions required, just correct application of the established path-op pattern to navigation's BSON structure.

---

Automated guide via OpenRouter — workflow source