Complete User Guide

Everything you need to know about using, updating, and sharing the mendix-expert MCP server.

📑 Table of Contents

Quick Reference
Installation
Daily Usage
Updating
Adding Knowledge
Sharing
Troubleshooting
Advanced Usage

🚀 Quick Reference

Commands You’ll Use Most

# Pull latest changes
cd D:\Users\kelly.seale\VSCode-Dream-Workspace\mendix-mcp-server
git pull

# Check server status
node src/index.js

# Validate knowledge base
node -e "const KM = require('./src/core/KnowledgeManager.js'); new KM('./knowledge').validateKnowledgeBase().then(r => console.log(r.summary));"

# Push your changes
git add -A
git commit -m "your message"
git push

MCP Resources (access via @mendix-expert)

Resource	What It Shows
`mendix://knowledge/overview`	All knowledge files and entry counts
`mendix://analytics`	Search hit rate, top terms, missed queries
`mendix://validation/report`	Errors and warnings in knowledge base
`mendix://maintenance`	Auto-maintenance schedule and status

📦 Installation

Fresh Install (New Machine)

# 1. Clone the repository
git clone https://github.com/jordnlvr/mendix-mcp-server.git
cd mendix-mcp-server

# 2. Install dependencies
npm install

# 3. Test it works
node src/index.js
# Should see: "Mendix Expert MCP Server running..."
# Press Ctrl+C to stop

Configure VS Code

Add to your VS Code settings.json (Ctrl+Shift+P → “Preferences: Open User Settings (JSON)”):

"chat.mcp.servers": {
  "mendix-expert": {
    "type": "stdio",
    "command": "node",
    "args": ["C:/YOUR/PATH/TO/mendix-mcp-server/src/index.js"]
  }
}

⚠️ Replace the path with your actual installation path!

Configure Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "mendix-expert": {
      "command": "node",
      "args": ["C:/YOUR/PATH/TO/mendix-mcp-server/src/index.js"]
    }
  }
}

💻 Daily Usage

In VS Code Copilot Chat

Open Copilot Chat (Ctrl+Shift+I)
Type @mendix-expert to activate the MCP server
Ask questions:
- “How do I create a microflow with the SDK?”
- “What’s the best practice for domain model design?”
- “Analyze my project at D:/Projects/MyApp.mpr”

Example Queries

@mendix-expert How do I iterate over a list in a microflow using the SDK?

@mendix-expert What are the naming conventions for microflows?

@mendix-expert Show me the analytics - what queries are people searching?

@mendix-expert Check if my knowledge base has any validation errors

Keyboard Shortcuts (VS Code)

Shortcut	Action
`Ctrl+Shift+I`	Open Copilot Chat
`@mendix-expert`	Activate MCP server
`Ctrl+Enter`	Submit query

🔄 Updating

Pull Latest from GitHub

cd D:\Users\kelly.seale\VSCode-Dream-Workspace\mendix-mcp-server

# Get latest changes
git pull

# If there are dependency updates
npm install

Update After Making Changes

# 1. See what changed
git status

# 2. Stage your changes
git add -A

# 3. Commit with descriptive message
git commit -m "knowledge: Add microflow error handling entries"

# 4. Push to GitHub
git push

Creating a New Release

# Use the release script
.\release.ps1 -Version "2.2.0" -Message "Added new SDK patterns"

This automatically:

Updates version in package.json and config
Validates the knowledge base
Creates a git tag
Pushes to GitHub
You then create the Release on GitHub

📚 Adding Knowledge

Quick Add (Single Entry)

Open the appropriate file in knowledge/:
- best-practices.json - Naming, architecture, patterns
- model-sdk.json - Model manipulation, elements
- platform-sdk.json - Working copies, commits
- troubleshooting.json - Errors and solutions
- studio-pro.json - Studio Pro features
Add your entry to the entries array:

{
  "id": "microflow-error-handling",
  "title": "Microflow Error Handling Best Practices",
  "category": "microflows",
  "content": "When handling errors in microflows, always use...",
  "keywords": ["error", "exception", "try-catch", "microflow"],
  "source": "experience",
  "lastUpdated": "2025-12-07"
}

Validate:

node -e "const KM = require('./src/core/KnowledgeManager.js'); new KM('./knowledge').validateKnowledgeBase().then(r => console.log(r.summary));"

Commit and push:

git add -A
git commit -m "knowledge: Add microflow error handling entry"
git push

Using the MCP Tool

You can also add knowledge via the MCP server:

@mendix-expert add to knowledge base:
- Category: best-practices
- Title: "Microflow Naming Conventions"
- Content: "Always prefix microflows with ACT_ for actions, DS_ for data sources..."
- Keywords: naming, microflow, conventions
- Source: experience

Give someone your GitHub URL:

https://github.com/jordnlvr/mendix-mcp-server

They can clone and use it immediately:

git clone https://github.com/jordnlvr/mendix-mcp-server.git
cd mendix-mcp-server
npm install

Make It Public (if private)

Go to https://github.com/jordnlvr/mendix-mcp-server/settings
Scroll to “Danger Zone”
Click “Change visibility” → Public

Collaborate

Add collaborators: Settings → Collaborators → Add people
They can then push directly, or:
They fork → make changes → submit Pull Request

Export knowledge files:

# Copy knowledge folder
Copy-Item -Path "knowledge" -Destination "C:\Shared\mendix-knowledge" -Recurse

🔧 Troubleshooting

“Server not responding”

# Test if server starts
cd D:\Users\kelly.seale\VSCode-Dream-Workspace\mendix-mcp-server
node src/index.js

# Check for errors
# If it hangs, press Ctrl+C and check the error

“Command not found: node”

Node.js isn’t in your PATH:

# Check if Node is installed
node --version

# If not, install from https://nodejs.org/

“MCP server not showing in Copilot”

Check VS Code settings have the correct path
Restart VS Code completely
Try toggling MCP servers off/on in Copilot settings

“Search returns no results”

# Check knowledge base is valid
node -e "const KM = require('./src/core/KnowledgeManager.js'); new KM('./knowledge').validateKnowledgeBase().then(r => console.log(r.summary));"

# Check index stats
node -e "const SE = require('./src/core/SearchEngine.js'); const e = new SE(); e.initialize('./knowledge'); console.log(e.getStats());"

“Git push rejected”

# Pull first, then push
git pull --rebase
git push

🎯 Advanced Usage

Check Knowledge Gaps

See what people search for but don’t find:

node -e "
const SE = require('./src/core/SearchEngine.js');
const e = new SE();
e.initialize('./knowledge');
console.log('Knowledge Gaps:', e.getKnowledgeGaps());
"

Analyze Your Mendix Project

@mendix-expert analyze project at D:\kelly.seale\CodeBase\SmartHub-main\SmartHub.mpr

@mendix-expert analyze module RequestHub in my project

Run Maintenance Manually

node -e "
const MS = require('./src/utils/MaintenanceScheduler.js');
const KM = require('./src/core/KnowledgeManager.js');
const SE = require('./src/core/SearchEngine.js');

const km = new KM('./knowledge');
const se = new SE();
se.initialize('./knowledge');

const scheduler = new MS(km, se, './data');
scheduler.runTask('validation').then(r => console.log(r));
"

View Analytics Dashboard

node -e "
const SE = require('./src/core/SearchEngine.js');
const e = new SE();
e.initialize('./knowledge');
const a = e.getAnalytics();
console.log('=== Analytics Dashboard ===');
console.log('Hit Rate:', (a.hitRate * 100).toFixed(1) + '%');
console.log('Avg Response:', a.avgResponseTime.toFixed(2) + 'ms');
console.log('Total Queries:', a.totalQueries);
console.log('Top Terms:', a.topTerms.slice(0, 5));
console.log('Recent Misses:', a.recentMisses.slice(0, 5));
"

📍 File Locations

What	Where
MCP Server	`D:\Users\kelly.seale\VSCode-Dream-Workspace\mendix-mcp-server\`
Knowledge Files	`mendix-mcp-server\knowledge\*.json`
Configuration	`mendix-mcp-server\config\default.json`
VS Code Settings	`%APPDATA%\Code - Insiders\User\settings.json`
Claude Desktop Config	`%APPDATA%\Claude\claude_desktop_config.json`
GitHub Repo	https://github.com/jordnlvr/mendix-mcp-server

🆘 Getting Help

Check this guide first - Most answers are here
GitHub Issues - https://github.com/jordnlvr/mendix-mcp-server/issues
README - Quick reference and setup
CONTRIBUTING.md - How to contribute

Last updated: December 7, 2025