USAGE-GUIDE.md•6.62 kB
# How to Use OneTech MCP Server
## Installation
### Method 1: Global Install (Recommended)
```bash
npm install -g @jordnlvr/onetech-mcp-server
```
### Method 2: Use with NPX (No Install)
```bash
npx @jordnlvr/onetech-mcp-server
```
### Method 3: Local Development
```bash
git clone https://github.com/[your-username]/onetech-mcp-server
cd onetech-mcp-server
npm install
npm run build
npm link
```
---
## Configuration
### VS Code + GitHub Copilot
**Option A: User Settings (Global)**
1. Open VS Code Command Palette (`Ctrl+Shift+P`)
2. Type: "Preferences: Open User Settings (JSON)"
3. Add this configuration:
```json
{
"github.copilot.chat.mcp.enabled": true,
"github.copilot.chat.mcp.servers": {
"onetech": {
"command": "npx",
"args": ["@jordnlvr/onetech-mcp-server"]
}
}
}
```
**Option B: Workspace Settings (Project-Specific)**
1. Create `.vscode/settings.json` in your project
2. Add the same configuration as above
**With Global Install:**
```json
{
"github.copilot.chat.mcp.enabled": true,
"github.copilot.chat.mcp.servers": {
"onetech": {
"command": "onetech-mcp-server"
}
}
}
```
### Claude Desktop
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"onetech": {
"command": "npx",
"args": ["@jordnlvr/onetech-mcp-server"]
}
}
}
```
---
## Usage Examples
### With GitHub Copilot in VS Code
**Example 1: Extract a Module**
```
You: Extract the RequestHub module from D:\Projects\OneTech.mpr and save to D:\Output
Copilot: [Uses onetech_extract_module tool]
Result:
✅ Successfully extracted 4 files from module 'RequestHub':
- DomainModel.json (57.2KB)
- Pages.json (42.1KB)
- Microflows.json (0KB)
- Enumerations.json (4.3KB)
```
**Example 2: Document a Module**
```
You: Document the domain model from MainModule in my OneTech app at D:\Projects\OneTech.mpr
Copilot: [Uses onetech_extract_module, then analyzes the JSON]
Result: Creates comprehensive documentation of entities, attributes, and associations
```
**Example 3: Compare Modules**
```
You: Extract both RequestHub and UserManagement modules, then compare their domain models
Copilot: [Extracts both modules, analyzes differences]
Result: Detailed comparison of entities and relationships between modules
```
---
## Tool Reference
### onetech_extract_module
Extracts domain model, pages, microflows, and enumerations from a Mendix module.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------------------------------------------------------- |
| `mprPath` | string | Yes | Absolute path to the .mpr file (e.g., `D:\Projects\OneTech.mpr`) |
| `moduleName` | string | Yes | Name of the module to extract (e.g., `RequestHub`) |
| `outputPath` | string | Yes | Absolute path to output directory for JSON files |
| `mxPath` | string | No | Custom path to mx.exe (default: `D:\Program Files\Mendix\11.3.0.80734\modeler\mx.exe`) |
**Returns:**
```typescript
{
success: boolean,
files: Array<{
name: string, // e.g., "DomainModel.json"
size: number // File size in bytes
}>,
message: string // Success or error message
}
```
**Output Files:**
1. **{module}-DomainModel.json** - Entities, attributes, associations, validation rules
2. **{module}-Pages.json** - Page layouts, widgets, data sources
3. **{module}-Microflows.json** - Logic flows, actions, parameters
4. **{module}-Enumerations.json** - Enumeration types and values
---
## Troubleshooting
### "mx.exe not found"
**Solution:** Specify custom mx.exe path:
```
You: Extract RequestHub from D:\Projects\OneTech.mpr using mx.exe at D:\Mendix\12.0\modeler\mx.exe
```
### ".mpr file not accessible"
**Solution:** Check file path and permissions:
```bash
# Verify file exists
Test-Path "D:\Projects\OneTech.mpr"
# Check read permissions
Get-Acl "D:\Projects\OneTech.mpr" | Format-List
```
### "Module not found"
**Solution:** Verify module name (case-sensitive):
```
Correct: RequestHub
Wrong: requesthub, request-hub, Request Hub
```
### Empty Microflows Output
This is **normal** if the module has no microflows. The tool will return a valid but empty JSON file.
---
## Best Practices
### 1. Use Absolute Paths
```
✅ Good: D:\Projects\OneTech.mpr
❌ Bad: .\OneTech.mpr
❌ Bad: ..\Projects\OneTech.mpr
```
### 2. Create Dedicated Output Directory
```bash
mkdir D:\MendixDocs\RequestHub
# Then extract to this directory
```
### 3. Extract Multiple Modules
```
You: Extract RequestHub, UserManagement, and Administration modules from OneTech.mpr
```
Copilot will call the tool 3 times and organize results.
### 4. Version Control the Output
```bash
cd D:\MendixDocs
git init
git add .
git commit -m "Initial module extraction"
```
Track changes to your Mendix architecture over time.
---
## Advanced Usage
### Custom mx.exe Path
```
You: Extract using mx.exe at D:\Custom\Path\mx.exe
```
### Batch Processing
```
You: Extract all modules from OneTech.mpr: RequestHub, UserManagement, Administration, EmailConnector, AuditTrail
```
### Integration with Documentation
```
You: Extract RequestHub, then generate markdown documentation from the domain model
```
### CI/CD Integration
```yaml
# GitHub Actions example
- name: Extract Mendix Modules
run: |
npx @jordnlvr/onetech-mcp-server extract --mpr ./OneTech.mpr --module RequestHub --output ./docs
```
---
## Performance
- **DomainModel:** ~25 seconds
- **Pages:** ~12 seconds
- **Microflows:** ~12 seconds
- **Enumerations:** ~12 seconds
**Total:** ~60 seconds for complete module extraction
**Optimization:** Files are extracted sequentially. Future versions may support parallel extraction.
---
## Privacy & Security
✅ **100% Local** - All processing on your machine
✅ **No Cloud** - Your .mpr files never leave your computer
✅ **No Tracking** - No telemetry or analytics
✅ **Open Source** - Audit the code yourself
---
## Support
**Found a bug?** [Open an issue on GitHub](https://github.com/onetech/mcp-server/issues)
**Feature request?** [Start a discussion](https://github.com/onetech/mcp-server/discussions)
**Need help?** Check the [FAQ](https://github.com/onetech/mcp-server/wiki/FAQ)
---
**Version:** 0.1.0
**Updated:** October 25, 2025