Skip to content

Ean Schuessler / mo-mcp

Go to a project
Toggle navigation
Toggle navigation pinning
0f21ef12 by Ean Schuessler
Options

Delete Security Considerations, Development, Testing, and Quick Start sections -… 

… focus on possibilities
1 parent f80b10d7
Inline Side-by-side
Showing 1 changed file with 0 additions and 310 deletions
......@@ -68,317 +68,7 @@ The implementation consists of:
- **Security Integration** - Moqui artifact authorization system
- **Test Suite** - Comprehensive Java/Groovy tests
## Quick Start (FOR TESTING ONLY!)
### **⚠️ PREREQUISITES - READ FIRST!**
- **Docker or similar containerization** - MANDATORY
- **Isolated test environment** - NEVER use production data
- **Understanding of Moqui security model** - Required
- **Java 17+, Moqui Framework, Gradle** - Technical requirements
- **PopCommerce component** - For examples (optional)
### **SAFE INSTALLATION**
1. **Create isolated environment:**
```bash
# ALWAYS use containers
docker run -it --rm -v $(pwd):/app openjdk:17 bash
cd /app
```
2. **Clone and build:**
```bash
git clone https://github.com/schue/moqui-mcp.git
cd moqui-mcp
./gradlew build
```
3. **Start in container ONLY:**
```bash
# NEVER expose to internet
./gradlew run --daemon > ./server.log 2>&1 &
```
4. **Create LIMITED user account:**
```bash
# NEVER use ADMIN for MCP
# Create dedicated user with minimal permissions only
```
5. **Test with caution:**
```bash
./mcp.sh ping
# Start with read-only operations only
```
### Basic Usage
List available tools:
```bash
./mcp.sh tools
```
Call a specific screen:
```bash
./mcp.sh call screen_PopCommerce_screen_PopCommerceAdmin.Catalog
```
Search for products:
```bash
./mcp.sh call screen_PopCommerce_screen_PopCommerceAdmin_Catalog.Product_FindProduct
```
## Tool Examples
### Catalog Management
- `screen_PopCommerce_screen_PopCommerceAdmin.Catalog` - Main catalog screen
- `screen_PopCommerce_screen_PopCommerceAdmin.Catalog.Product` - Product management
- `screen_PopCommerce_screen_PopCommerceAdmin_Catalog.Product_FindProduct` - Product search
- `screen_PopCommerce_screen_PopCommerceAdmin_Catalog.Category_FindCategory` - Category search
### Order Management
- `screen_PopCommerce_screen_PopCommerceAdmin_Order.FindOrder` - Order lookup
- `screen_PopCommerce_screen_PopCommerceAdmin.Order.CreateOrder` - Create new order
### Customer Management
- `screen_PopCommerce_screen_PopCommerceRoot.Customer` - Customer management
- `screen_PopCommerce_screen_PopCommerceAdmin.Customer.FindCustomer` - Customer search
### Pricing
- `screen_PopCommerce_screen_PopCommerceAdmin_Catalog.Product_EditPrices` - Price management
## Configuration
### Server Configuration
The MCP server is configured via `MoquiConf.xml`:
```xml
<webapp name="webroot" http-port="8080">
<servlet name="EnhancedMcpServlet" class="org.moqui.mcp.EnhancedMcpServlet"
load-on-startup="5" async-supported="true">
<init-param name="keepAliveIntervalSeconds" value="30"/>
<init-param name="maxConnections" value="100"/>
<url-pattern>/mcp/*</url-pattern>
</servlet>
</webapp>
```
### Security Configuration
Users need appropriate permissions to access MCP services:
- **McpUser** group - Basic MCP access
- **MCP_BUSINESS** group - Business toolkit access
- **ArtifactGroup** permissions for screen access
## Testing
### Running Tests
```bash
# Run all tests
./test/run-tests.sh
# Run only infrastructure tests
./test/run-tests.sh infrastructure
# Run only workflow tests
./test/run-tests.sh workflow
# Monitor test output
./gradlew test > ./test.log 2>&1
tail -f ./test.log
```
### Test Structure
The test suite includes:
1. **Screen Infrastructure Tests** - Basic MCP connectivity, screen discovery, rendering
2. **PopCommerce Workflow Tests** - Complete business workflow: product lookup → order placement
3. **Integration Tests** - Cross-component validation
### Test Configuration
Tests are configured via `test/resources/test-config.properties`:
```properties
test.mcp.url=http://localhost:8080/mcp
test.user=john.sales
test.password=opencode
test.customer.firstName=John
test.customer.lastName=Doe
test.product.color=blue
```
## Development
### Project Structure
```
moqui-mcp/
├── component.xml # Component definition
├── MoquiConf.xml # Server configuration
├── service/
│ └── McpServices.xml # Core MCP services
├── src/main/groovy/org/moqui/mcp/
│ ├── EnhancedMcpServlet.groovy # Main MCP servlet
│ ├── VisitBasedMcpSession.groovy # Session management
│ └── ... # Supporting classes
├── test/ # Test suite
├── data/ # Seed data
├── entity/ # Entity definitions
└── screen/ # Screen definitions
```
### Adding New Features
1. **New Screen Tools** - Screens are automatically discovered
2. **New Services** - Add to `McpServices.xml`
3. **New Tests** - Add to appropriate test class in `test/`
### Debugging
Enable debug logging:
```bash
# Check server logs
tail -f ./server.log
# Check MCP logs
tail -f ./moqui.log
# Test specific tool
./mcp.sh call <tool-name>
```
## 🤔 **Community Tool Gap**
**What CLI tool should we use for LLM + Java testing?**
Currently using improvised `mcp.sh` script for basic MCP testing. But there should be a mature tool that handles:
- **LLM Interaction**: Chat with AI models via MCP
- **Java Testing**: Full lifecycle test generation
- **Code Generation**: AI writes code, tests validate it
- **Iterative Development**: Test → Generate → Refine loop
**Ideas welcome!** What tools are you using for:
- LLM + Java development workflows?
- Automated test-driven code generation?
- MCP client development?
*The `mcp.sh` script works for basic testing, but we need a proper development ecosystem.*
## API Reference
### MCP Protocol Methods
- `initialize` - Initialize MCP session
- `tools/list` - List available tools
- `tools/call` - Execute a tool
- `resources/list` - List available resources
- `resources/read` - Read a resource
### Screen Tool Parameters
- `screenPath` - Path to the screen (required)
- `parameters` - Screen parameters (optional)
- `renderMode` - Output format: text/html/json (default: html)
- `subscreenName` - Target subscreen (optional)
## Security Considerations (READ THIS!)
### **CRITICAL VULNERABILITIES**
1. **ADMIN PRIVILEGE ESCALATION** (Lines 59, 338, 404, 442, 654, 704 in McpServices.xml)
- Code: `ec.user.pushUser("ADMIN")`
- **Impact**: LLM can bypass ALL security restrictions
2. **UNIVERSAL SERVICE EXECUTION** (Lines 326-328)
- Code: `ec.service.isServiceDefined(name)` + direct service calls
- **Impact**: Can execute ANY Moqui service including destructive ones
3. **COMPLETE DATABASE ACCESS** (Lines 499-630)
- Code: Entity access with `ec.entity.find()` on ALL entities
- **Impact**: Read/write access to entire database
4. **SCREEN AUTHORIZATION BYPASS** (Lines 817-1933)
- Code: Direct screen rendering with elevated context
- **Impact**: Can access any screen, including admin interfaces
5. **TEST DATA POLLUTION** (McpTestServices.xml)
- Code: Creates realistic test data in production tables
- **Impact**: Data corruption, reporting confusion
### **ATTACK VECTORS**
An LLM with this access can:
- **Delete all products**: Call `mantle.product.Product` delete services
- **Steal customer data**: Read `mantle.party.Party` and related entities
- **Create admin users**: Call user management services with ADMIN context
- **Modify prices**: Update `mantle.product.ProductPrice` entities
- **Cancel orders**: Mass order cancellation through service calls
- **Export financial data**: Dump payment, invoice, accounting data
- **Bypass audit trails**: Direct entity manipulation skips logging
### **MITIGATION STRATEGIES**
1. **NEVER use with ADMIN accounts**
2. **Create dedicated MCP users with minimal permissions**
3. **Run in isolated containers with no production data**
4. **Implement rate limiting and connection monitoring**
5. **Regular security audits of MCP access logs**
6. **Separate database instances for MCP testing**
## Performance
- Session caching reduces database overhead
- Recursive discovery is performed once per session
- Screen rendering uses Moqui's optimized screen engine
- Connection pooling handles concurrent requests
## Troubleshooting
### Common Issues
1. **Server Not Running**
```bash
./gradlew --status
./gradlew run --daemon
```
2. **Authentication Failures**
- Verify user exists in Moqui
- Check user group memberships
- Validate credentials in `opencode.json`
3. **Missing Screens**
- Ensure required components are installed
- Check screen path syntax
- Verify user has screen permissions
4. **Session Issues**
```bash
./mcp.sh --clear-session
./mcp.sh --new-session
```
### Debug Mode
Enable detailed logging by setting log level in `MoquiConf.xml`:
```xml
<logger name="org.moqui.mcp" level="DEBUG"/>
```
## Contributing
1. Follow Moqui coding conventions
2. Add tests for new features
3. Update documentation
4. Ensure security implications are considered
5. Test with the provided test suite
## License
......