OneTech MCP Server

# OneTech MCP Server - Complete Getting Started Guide **For Users New to MCP Servers and This Tool** This guide assumes you have **zero** knowledge of MCP servers and walks you through everything step-by-step. --- ## 📋 What You'll Need (Prerequisites) Before starting, make sure you have: 1. **Mendix Studio Pro** installed on your computer - Any version 11.x or higher - Located at: `C:\Program Files\Mendix\` or similar 2. **Node.js** installed (version 18 or higher) - Download from: https://nodejs.org/ - Choose "LTS" (Long Term Support) version - During installation, check "Add to PATH" 3. **VS Code** with **GitHub Copilot** extension - Download VS Code: https://code.visualstudio.com/ - Install GitHub Copilot extension from Extensions marketplace - OR use **Claude Desktop** app instead 4. **A Mendix project file (.mpr)** - Example: `D:\Projects\OneTech.mpr` - You need the full path to this file --- ## 🎯 What This Tool Does **OneTech MCP Server** lets AI assistants (like GitHub Copilot or Claude) extract documentation from your Mendix projects. **Example:** ``` You type: "Extract RequestHub module from my OneTech project" AI uses this tool → Runs Mendix commands → Creates 4 JSON files with: - Domain model (entities, attributes) - Pages (layouts, widgets) - Microflows (logic flows) - Enumerations (dropdown values) ``` --- ## 📥 Step 1: Install the OneTech MCP Server ### Option A: Quick Install (Recommended for Most Users) 1. Open **PowerShell** or **Command Prompt** - Press `Windows Key + R` - Type `powershell` - Press `Enter` 2. Copy this command and paste it: ```bash npm install -g @jordnlvr/onetech-mcp-server ``` 3. Press `Enter` and wait for installation to complete - You'll see: "added 17 packages" (or similar) - Takes about 30 seconds 4. Verify installation: ```bash onetech-mcp-server --version ``` - Should show: `0.1.0` ### Option B: No Install (Use NPX) If you don't want to install globally, you can use NPX (runs without installing): ```bash npx @jordnlvr/onetech-mcp-server ``` **When to use this:** If you only want to try it once, or prefer not to install globally. --- ## ⚙️ Step 2: Configure Your AI Assistant ### For VS Code + GitHub Copilot Users #### Step 2A: Open VS Code Settings 1. Open **VS Code** 2. Click the gear icon (⚙️) in the bottom-left corner 3. Click **"Settings"** 4. Click the **document icon** in the top-right (opens JSON file) - Or press: `Ctrl + Shift + P` → type "Open User Settings (JSON)" → press `Enter` #### Step 2B: Add MCP Server Configuration 1. You'll see a file that looks like this: ```json { "editor.fontSize": 14, "workbench.colorTheme": "Dark+" } ``` 2. **Copy this entire block:** ```json "github.copilot.chat.mcp.enabled": true, "github.copilot.chat.mcp.servers": { "onetech": { "command": "npx", "args": ["@jordnlvr/onetech-mcp-server"] } } ``` 3. **Paste it into your settings file** - Place it AFTER the last line, but BEFORE the closing `}` - Add a comma after the previous line if needed 4. **Your file should now look like this:** ```json { "editor.fontSize": 14, "workbench.colorTheme": "Dark+", "github.copilot.chat.mcp.enabled": true, "github.copilot.chat.mcp.servers": { "onetech": { "command": "npx", "args": ["@jordnlvr/onetech-mcp-server"] } } } ``` 5. **Save the file:** - Press `Ctrl + S` - Close the settings file 6. **Restart VS Code:** - Close VS Code completely - Open it again #### Step 2C: Verify Configuration 1. Open **GitHub Copilot Chat** - Click the chat icon in the left sidebar - Or press `Ctrl + Shift + I` 2. Type this test message: ``` Do you have access to the OneTech MCP server? ``` 3. Copilot should respond confirming it has access to the tool --- ### For Claude Desktop Users #### Step 2A: Locate Configuration File **On Windows:** 1. Press `Windows Key + R` 2. Type: `%APPDATA%\Claude` 3. Press `Enter` 4. Look for file: `claude_desktop_config.json` **On Mac:** 1. Open Finder 2. Press `Cmd + Shift + G` 3. Type: `~/Library/Application Support/Claude` 4. Press `Enter` 5. Look for file: `claude_desktop_config.json` #### Step 2B: Edit Configuration 1. **If file exists:** - Open it with Notepad (Windows) or TextEdit (Mac) 2. **If file doesn't exist:** - Create a new text file - Name it: `claude_desktop_config.json` 3. **Copy this entire text:** ```json { "mcpServers": { "onetech": { "command": "npx", "args": ["@jordnlvr/onetech-mcp-server"] } } } ``` 4. **Paste it into the file** (replace all existing content) 5. **Save the file:** - `Ctrl + S` (Windows) or `Cmd + S` (Mac) 6. **Restart Claude Desktop:** - Close the app completely - Open it again --- ## 🚀 Step 3: Use the Tool (Extract Your First Module) ### Step 3A: Gather Required Information You need three pieces of information: 1. **Path to your .mpr file** - Example: `D:\Projects\OneTech.mpr` - To find it: - Open File Explorer - Navigate to your Mendix project folder - Right-click the `.mpr` file - Click "Copy as path" - Remove the quotes if present 2. **Module name** (case-sensitive!) - Example: `RequestHub` - To find it: - Open your project in Mendix Studio Pro - Look at the Project Explorer - Module names are shown in the tree 3. **Output folder** (where to save JSON files) - Example: `D:\MendixDocs\RequestHub` - Create this folder first: - Open File Explorer - Navigate to `D:\` - Right-click → New → Folder - Name it: `MendixDocs` - Inside that, create: `RequestHub` ### Step 3B: Using in VS Code with GitHub Copilot 1. **Open GitHub Copilot Chat** - Click chat icon in left sidebar - Or press `Ctrl + Shift + I` 2. **Type this message** (replace with YOUR paths): ``` Extract the RequestHub module from D:\Projects\OneTech.mpr and save the files to D:\MendixDocs\RequestHub ``` 3. **Copilot will:** - Recognize the OneTech MCP Server tool - Call it with your parameters - Show you the results 4. **You'll see output like this:** ``` ✅ Successfully extracted 4 files from module 'RequestHub': - DomainModel.json (57.2KB) - Pages.json (42.1KB) - Microflows.json (0KB) - Enumerations.json (4.3KB) ``` 5. **Check your output folder:** - Open File Explorer - Navigate to `D:\MendixDocs\RequestHub` - You should see 4 JSON files ### Step 3C: Using in Claude Desktop 1. **Open Claude Desktop** 2. **Type this message** (replace with YOUR paths): ``` I need to extract a Mendix module. Here are the details: - MPR file: D:\Projects\OneTech.mpr - Module name: RequestHub - Output folder: D:\MendixDocs\RequestHub Please use the onetech_extract_module tool to extract this module. ``` 3. **Claude will:** - Use the OneTech MCP Server tool - Extract the module - Show you the results --- ## 📂 Step 4: Understanding the Output Files After extraction, you'll have 4 JSON files: ### 1. `{Module}-DomainModel.json` **Contains:** All entities, attributes, associations, and validation rules **Example content:** ```json { "units": [ { "name": "Customer", "attributes": [ { "name": "Name", "type": "String" }, { "name": "Email", "type": "String" } ] } ] } ``` **Use for:** Understanding database structure, documenting entities --- ### 2. `{Module}-Pages.json` **Contains:** All pages, layouts, widgets, and data sources **Example content:** ```json { "units": [ { "name": "CustomerOverview", "widgets": [{ "type": "DataGrid", "dataSource": "Customer" }] } ] } ``` **Use for:** Understanding UI structure, documenting pages --- ### 3. `{Module}-Microflows.json` **Contains:** All microflows with their logic flows and actions **Example content:** ```json { "units": [ { "name": "ACT_CreateCustomer", "parameters": [{ "name": "CustomerName", "type": "String" }] } ] } ``` **Use for:** Understanding business logic, documenting workflows **Note:** May be empty (`{"units":[]}`) if module has no microflows --- ### 4. `{Module}-Enumerations.json` **Contains:** All enumerations with their values **Example content:** ```json { "units": [ { "name": "CustomerType", "values": [{ "name": "Individual" }, { "name": "Business" }] } ] } ``` **Use for:** Understanding dropdown options, documenting enums --- ## 🔧 Troubleshooting ### Problem 1: "mx.exe not found" **Symptoms:** ``` Error: mx.exe not found or not accessible ``` **Solution:** 1. Find where Mendix is installed: - Usually: `C:\Program Files\Mendix\11.3.0.80734\modeler\mx.exe` - Or check your Mendix installation folder 2. When chatting with Copilot/Claude, specify the path: ``` Extract RequestHub from D:\Projects\OneTech.mpr using mx.exe at C:\Program Files\Mendix\11.3.0.80734\modeler\mx.exe ``` --- ### Problem 2: "Module not found" **Symptoms:** ``` Warning: Module 'requesthub' not found ``` **Solution:** - Module names are **case-sensitive** - Check exact spelling in Mendix Studio Pro - Examples: - ✅ Correct: `RequestHub` - ❌ Wrong: `requesthub`, `request-hub`, `Request Hub` --- ### Problem 3: ".mpr file not accessible" **Symptoms:** ``` Error: .mpr file not found or not accessible ``` **Solution:** 1. **Verify file exists:** - Open File Explorer - Navigate to the file - Make sure it's not open in Mendix Studio Pro 2. **Use absolute paths (full paths):** - ✅ Good: `D:\Projects\OneTech.mpr` - ❌ Bad: `.\OneTech.mpr` or `..\OneTech.mpr` 3. **Check file permissions:** - Right-click the file - Properties → Security - Make sure you have "Read" permission --- ### Problem 4: "Command not found" after npm install **Symptoms:** ``` 'onetech-mcp-server' is not recognized as an internal or external command ``` **Solution:** 1. **Close and reopen PowerShell/Command Prompt** - PATH needs to refresh 2. **Verify npm global path:** ```bash npm config get prefix ``` - Should show: `C:\Users\YourName\AppData\Roaming\npm` 3. **Add to PATH if needed:** - Windows Key → type "Environment Variables" - Edit system PATH - Add: `C:\Users\YourName\AppData\Roaming\npm` - Click OK, restart PowerShell 4. **Or use NPX instead:** ```bash npx @onetech/mcp-server ``` --- ### Problem 5: Copilot/Claude doesn't see the tool **Symptoms:** - Copilot responds: "I don't have access to that tool" - Or doesn't recognize the command **Solution:** **For VS Code:** 1. Verify settings file was saved correctly 2. Restart VS Code completely (close all windows) 3. Open Copilot Chat again 4. Try asking: "What MCP tools do you have access to?" **For Claude Desktop:** 1. Verify `claude_desktop_config.json` is in correct location 2. Restart Claude Desktop app 3. Try asking: "What MCP servers are available?" --- ## 🎓 Advanced Usage Examples ### Example 1: Extract Multiple Modules ``` Extract these modules from D:\Projects\OneTech.mpr: - RequestHub - UserManagement - Administration Save each to D:\MendixDocs\[ModuleName] ``` Copilot will extract each module separately. --- ### Example 2: Generate Documentation from JSON ``` I extracted the RequestHub module and got these JSON files: - DomainModel.json - Pages.json - Microflows.json - Enumerations.json Please create a markdown documentation file describing: 1. All entities and their attributes 2. All pages and their purpose 3. All microflows and what they do ``` Copilot will analyze the JSON and write documentation. --- ### Example 3: Compare Two Modules ``` Extract both RequestHub and UserManagement modules from OneTech.mpr. Then compare their domain models and tell me: - What entities are shared? - What associations exist between them? - Are there any naming inconsistencies? ``` --- ### Example 4: Find Specific Entity ``` Extract the RequestHub module and find all entities that have: - An attribute called "Email" - A CreatedDate attribute - An association to User entity Show me the results in a table. ``` --- ## 📊 What to Do with the JSON Files ### 1. Documentation Generation Use AI to convert JSON → Markdown/HTML/PDF documentation ### 2. Architecture Analysis - Identify entity relationships - Find orphaned entities (no associations) - Map data flows ### 3. Migration Planning - Compare old vs new module structure - Identify breaking changes - Plan data migration ### 4. Code Review - Validate naming conventions - Check for missing validations - Identify redundant microflows ### 5. Training Materials - Create entity diagrams - Document business logic - Generate onboarding guides --- ## 🔄 Updating the Tool When a new version is released: ```bash # If you used global install: npm update -g @jordnlvr/onetech-mcp-server # If you use NPX: # NPX automatically uses the latest version npx @jordnlvr/onetech-mcp-server ``` --- ## 📞 Getting Help ### Documentation - **README:** Basic usage and installation - **USAGE-GUIDE:** Advanced examples and troubleshooting - **This Guide:** Complete step-by-step instructions ### Community Support - **GitHub Issues:** Report bugs or problems - **GitHub Discussions:** Ask questions, share tips ### Check Version ```bash npm info @jordnlvr/onetech-mcp-server version ``` --- ## ✅ Quick Reference Card **Installation:** ```bash npm install -g @jordnlvr/onetech-mcp-server ``` **VS Code Config Location:** ``` Settings → Open User Settings (JSON) Add MCP server configuration Restart VS Code ``` **Basic Usage:** ``` "Extract [ModuleName] from [path-to-mpr] to [output-folder]" ``` **Output Files:** - `{Module}-DomainModel.json` - Database structure - `{Module}-Pages.json` - UI structure - `{Module}-Microflows.json` - Business logic - `{Module}-Enumerations.json` - Dropdown values **Troubleshooting:** - Use absolute paths (full paths) - Module names are case-sensitive - Restart VS Code/Claude after config changes - Close .mpr file in Studio Pro before extracting --- ## 🎯 Success Checklist After following this guide, you should be able to: - ✅ Install the OneTech MCP Server - ✅ Configure VS Code or Claude Desktop - ✅ Extract a module from your Mendix project - ✅ Find the 4 JSON output files - ✅ Use AI to analyze the JSON files - ✅ Troubleshoot common problems --- **Questions?** Re-read the section that's unclear, or ask your AI assistant: ``` "I'm having trouble with [specific step]. Can you help me?" ``` **Ready to start?** Go back to **Step 1: Install** and follow along! 🚀 --- **Version:** 0.1.0 **Last Updated:** October 25, 2025 **For:** Complete Beginners & New Users