Delete Security Considerations, Development, Testing, and Quick Start sections -…
… focus on possibilities
Showing
1 changed file
with
0 additions
and
310 deletions
| ... | @@ -68,317 +68,7 @@ The implementation consists of: | ... | @@ -68,317 +68,7 @@ The implementation consists of: |
| 68 | - **Security Integration** - Moqui artifact authorization system | 68 | - **Security Integration** - Moqui artifact authorization system |
| 69 | - **Test Suite** - Comprehensive Java/Groovy tests | 69 | - **Test Suite** - Comprehensive Java/Groovy tests |
| 70 | 70 | ||
| 71 | ## Quick Start (FOR TESTING ONLY!) | ||
| 72 | |||
| 73 | ### **⚠️ PREREQUISITES - READ FIRST!** | ||
| 74 | |||
| 75 | - **Docker or similar containerization** - MANDATORY | ||
| 76 | - **Isolated test environment** - NEVER use production data | ||
| 77 | - **Understanding of Moqui security model** - Required | ||
| 78 | - **Java 17+, Moqui Framework, Gradle** - Technical requirements | ||
| 79 | - **PopCommerce component** - For examples (optional) | ||
| 80 | 71 | ||
| 81 | ### **SAFE INSTALLATION** | ||
| 82 | |||
| 83 | 1. **Create isolated environment:** | ||
| 84 | ```bash | ||
| 85 | # ALWAYS use containers | ||
| 86 | docker run -it --rm -v $(pwd):/app openjdk:17 bash | ||
| 87 | cd /app | ||
| 88 | ``` | ||
| 89 | |||
| 90 | 2. **Clone and build:** | ||
| 91 | ```bash | ||
| 92 | git clone https://github.com/schue/moqui-mcp.git | ||
| 93 | cd moqui-mcp | ||
| 94 | ./gradlew build | ||
| 95 | ``` | ||
| 96 | |||
| 97 | 3. **Start in container ONLY:** | ||
| 98 | ```bash | ||
| 99 | # NEVER expose to internet | ||
| 100 | ./gradlew run --daemon > ./server.log 2>&1 & | ||
| 101 | ``` | ||
| 102 | |||
| 103 | 4. **Create LIMITED user account:** | ||
| 104 | ```bash | ||
| 105 | # NEVER use ADMIN for MCP | ||
| 106 | # Create dedicated user with minimal permissions only | ||
| 107 | ``` | ||
| 108 | |||
| 109 | 5. **Test with caution:** | ||
| 110 | ```bash | ||
| 111 | ./mcp.sh ping | ||
| 112 | # Start with read-only operations only | ||
| 113 | ``` | ||
| 114 | |||
| 115 | ### Basic Usage | ||
| 116 | |||
| 117 | List available tools: | ||
| 118 | ```bash | ||
| 119 | ./mcp.sh tools | ||
| 120 | ``` | ||
| 121 | |||
| 122 | Call a specific screen: | ||
| 123 | ```bash | ||
| 124 | ./mcp.sh call screen_PopCommerce_screen_PopCommerceAdmin.Catalog | ||
| 125 | ``` | ||
| 126 | |||
| 127 | Search for products: | ||
| 128 | ```bash | ||
| 129 | ./mcp.sh call screen_PopCommerce_screen_PopCommerceAdmin_Catalog.Product_FindProduct | ||
| 130 | ``` | ||
| 131 | |||
| 132 | ## Tool Examples | ||
| 133 | |||
| 134 | ### Catalog Management | ||
| 135 | - `screen_PopCommerce_screen_PopCommerceAdmin.Catalog` - Main catalog screen | ||
| 136 | - `screen_PopCommerce_screen_PopCommerceAdmin.Catalog.Product` - Product management | ||
| 137 | - `screen_PopCommerce_screen_PopCommerceAdmin_Catalog.Product_FindProduct` - Product search | ||
| 138 | - `screen_PopCommerce_screen_PopCommerceAdmin_Catalog.Category_FindCategory` - Category search | ||
| 139 | |||
| 140 | ### Order Management | ||
| 141 | - `screen_PopCommerce_screen_PopCommerceAdmin_Order.FindOrder` - Order lookup | ||
| 142 | - `screen_PopCommerce_screen_PopCommerceAdmin.Order.CreateOrder` - Create new order | ||
| 143 | |||
| 144 | ### Customer Management | ||
| 145 | - `screen_PopCommerce_screen_PopCommerceRoot.Customer` - Customer management | ||
| 146 | - `screen_PopCommerce_screen_PopCommerceAdmin.Customer.FindCustomer` - Customer search | ||
| 147 | |||
| 148 | ### Pricing | ||
| 149 | - `screen_PopCommerce_screen_PopCommerceAdmin_Catalog.Product_EditPrices` - Price management | ||
| 150 | |||
| 151 | ## Configuration | ||
| 152 | |||
| 153 | ### Server Configuration | ||
| 154 | |||
| 155 | The MCP server is configured via `MoquiConf.xml`: | ||
| 156 | |||
| 157 | ```xml | ||
| 158 | <webapp name="webroot" http-port="8080"> | ||
| 159 | <servlet name="EnhancedMcpServlet" class="org.moqui.mcp.EnhancedMcpServlet" | ||
| 160 | load-on-startup="5" async-supported="true"> | ||
| 161 | <init-param name="keepAliveIntervalSeconds" value="30"/> | ||
| 162 | <init-param name="maxConnections" value="100"/> | ||
| 163 | <url-pattern>/mcp/*</url-pattern> | ||
| 164 | </servlet> | ||
| 165 | </webapp> | ||
| 166 | ``` | ||
| 167 | |||
| 168 | ### Security Configuration | ||
| 169 | |||
| 170 | Users need appropriate permissions to access MCP services: | ||
| 171 | |||
| 172 | - **McpUser** group - Basic MCP access | ||
| 173 | - **MCP_BUSINESS** group - Business toolkit access | ||
| 174 | - **ArtifactGroup** permissions for screen access | ||
| 175 | |||
| 176 | ## Testing | ||
| 177 | |||
| 178 | ### Running Tests | ||
| 179 | |||
| 180 | ```bash | ||
| 181 | # Run all tests | ||
| 182 | ./test/run-tests.sh | ||
| 183 | |||
| 184 | # Run only infrastructure tests | ||
| 185 | ./test/run-tests.sh infrastructure | ||
| 186 | |||
| 187 | # Run only workflow tests | ||
| 188 | ./test/run-tests.sh workflow | ||
| 189 | |||
| 190 | # Monitor test output | ||
| 191 | ./gradlew test > ./test.log 2>&1 | ||
| 192 | tail -f ./test.log | ||
| 193 | ``` | ||
| 194 | |||
| 195 | ### Test Structure | ||
| 196 | |||
| 197 | The test suite includes: | ||
| 198 | |||
| 199 | 1. **Screen Infrastructure Tests** - Basic MCP connectivity, screen discovery, rendering | ||
| 200 | 2. **PopCommerce Workflow Tests** - Complete business workflow: product lookup → order placement | ||
| 201 | 3. **Integration Tests** - Cross-component validation | ||
| 202 | |||
| 203 | ### Test Configuration | ||
| 204 | |||
| 205 | Tests are configured via `test/resources/test-config.properties`: | ||
| 206 | |||
| 207 | ```properties | ||
| 208 | test.mcp.url=http://localhost:8080/mcp | ||
| 209 | test.user=john.sales | ||
| 210 | test.password=opencode | ||
| 211 | test.customer.firstName=John | ||
| 212 | test.customer.lastName=Doe | ||
| 213 | test.product.color=blue | ||
| 214 | ``` | ||
| 215 | |||
| 216 | ## Development | ||
| 217 | |||
| 218 | ### Project Structure | ||
| 219 | |||
| 220 | ``` | ||
| 221 | moqui-mcp/ | ||
| 222 | ├── component.xml # Component definition | ||
| 223 | ├── MoquiConf.xml # Server configuration | ||
| 224 | ├── service/ | ||
| 225 | │ └── McpServices.xml # Core MCP services | ||
| 226 | ├── src/main/groovy/org/moqui/mcp/ | ||
| 227 | │ ├── EnhancedMcpServlet.groovy # Main MCP servlet | ||
| 228 | │ ├── VisitBasedMcpSession.groovy # Session management | ||
| 229 | │ └── ... # Supporting classes | ||
| 230 | ├── test/ # Test suite | ||
| 231 | ├── data/ # Seed data | ||
| 232 | ├── entity/ # Entity definitions | ||
| 233 | └── screen/ # Screen definitions | ||
| 234 | ``` | ||
| 235 | |||
| 236 | ### Adding New Features | ||
| 237 | |||
| 238 | 1. **New Screen Tools** - Screens are automatically discovered | ||
| 239 | 2. **New Services** - Add to `McpServices.xml` | ||
| 240 | 3. **New Tests** - Add to appropriate test class in `test/` | ||
| 241 | |||
| 242 | ### Debugging | ||
| 243 | |||
| 244 | Enable debug logging: | ||
| 245 | ```bash | ||
| 246 | # Check server logs | ||
| 247 | tail -f ./server.log | ||
| 248 | |||
| 249 | # Check MCP logs | ||
| 250 | tail -f ./moqui.log | ||
| 251 | |||
| 252 | # Test specific tool | ||
| 253 | ./mcp.sh call <tool-name> | ||
| 254 | ``` | ||
| 255 | |||
| 256 | ## 🤔 **Community Tool Gap** | ||
| 257 | |||
| 258 | **What CLI tool should we use for LLM + Java testing?** | ||
| 259 | |||
| 260 | Currently using improvised `mcp.sh` script for basic MCP testing. But there should be a mature tool that handles: | ||
| 261 | |||
| 262 | - **LLM Interaction**: Chat with AI models via MCP | ||
| 263 | - **Java Testing**: Full lifecycle test generation | ||
| 264 | - **Code Generation**: AI writes code, tests validate it | ||
| 265 | - **Iterative Development**: Test → Generate → Refine loop | ||
| 266 | |||
| 267 | **Ideas welcome!** What tools are you using for: | ||
| 268 | - LLM + Java development workflows? | ||
| 269 | - Automated test-driven code generation? | ||
| 270 | - MCP client development? | ||
| 271 | |||
| 272 | *The `mcp.sh` script works for basic testing, but we need a proper development ecosystem.* | ||
| 273 | |||
| 274 | ## API Reference | ||
| 275 | |||
| 276 | ### MCP Protocol Methods | ||
| 277 | |||
| 278 | - `initialize` - Initialize MCP session | ||
| 279 | - `tools/list` - List available tools | ||
| 280 | - `tools/call` - Execute a tool | ||
| 281 | - `resources/list` - List available resources | ||
| 282 | - `resources/read` - Read a resource | ||
| 283 | |||
| 284 | ### Screen Tool Parameters | ||
| 285 | |||
| 286 | - `screenPath` - Path to the screen (required) | ||
| 287 | - `parameters` - Screen parameters (optional) | ||
| 288 | - `renderMode` - Output format: text/html/json (default: html) | ||
| 289 | - `subscreenName` - Target subscreen (optional) | ||
| 290 | |||
| 291 | ## Security Considerations (READ THIS!) | ||
| 292 | |||
| 293 | ### **CRITICAL VULNERABILITIES** | ||
| 294 | |||
| 295 | 1. **ADMIN PRIVILEGE ESCALATION** (Lines 59, 338, 404, 442, 654, 704 in McpServices.xml) | ||
| 296 | - Code: `ec.user.pushUser("ADMIN")` | ||
| 297 | - **Impact**: LLM can bypass ALL security restrictions | ||
| 298 | |||
| 299 | 2. **UNIVERSAL SERVICE EXECUTION** (Lines 326-328) | ||
| 300 | - Code: `ec.service.isServiceDefined(name)` + direct service calls | ||
| 301 | - **Impact**: Can execute ANY Moqui service including destructive ones | ||
| 302 | |||
| 303 | 3. **COMPLETE DATABASE ACCESS** (Lines 499-630) | ||
| 304 | - Code: Entity access with `ec.entity.find()` on ALL entities | ||
| 305 | - **Impact**: Read/write access to entire database | ||
| 306 | |||
| 307 | 4. **SCREEN AUTHORIZATION BYPASS** (Lines 817-1933) | ||
| 308 | - Code: Direct screen rendering with elevated context | ||
| 309 | - **Impact**: Can access any screen, including admin interfaces | ||
| 310 | |||
| 311 | 5. **TEST DATA POLLUTION** (McpTestServices.xml) | ||
| 312 | - Code: Creates realistic test data in production tables | ||
| 313 | - **Impact**: Data corruption, reporting confusion | ||
| 314 | |||
| 315 | ### **ATTACK VECTORS** | ||
| 316 | |||
| 317 | An LLM with this access can: | ||
| 318 | - **Delete all products**: Call `mantle.product.Product` delete services | ||
| 319 | - **Steal customer data**: Read `mantle.party.Party` and related entities | ||
| 320 | - **Create admin users**: Call user management services with ADMIN context | ||
| 321 | - **Modify prices**: Update `mantle.product.ProductPrice` entities | ||
| 322 | - **Cancel orders**: Mass order cancellation through service calls | ||
| 323 | - **Export financial data**: Dump payment, invoice, accounting data | ||
| 324 | - **Bypass audit trails**: Direct entity manipulation skips logging | ||
| 325 | |||
| 326 | ### **MITIGATION STRATEGIES** | ||
| 327 | |||
| 328 | 1. **NEVER use with ADMIN accounts** | ||
| 329 | 2. **Create dedicated MCP users with minimal permissions** | ||
| 330 | 3. **Run in isolated containers with no production data** | ||
| 331 | 4. **Implement rate limiting and connection monitoring** | ||
| 332 | 5. **Regular security audits of MCP access logs** | ||
| 333 | 6. **Separate database instances for MCP testing** | ||
| 334 | |||
| 335 | ## Performance | ||
| 336 | |||
| 337 | - Session caching reduces database overhead | ||
| 338 | - Recursive discovery is performed once per session | ||
| 339 | - Screen rendering uses Moqui's optimized screen engine | ||
| 340 | - Connection pooling handles concurrent requests | ||
| 341 | |||
| 342 | ## Troubleshooting | ||
| 343 | |||
| 344 | ### Common Issues | ||
| 345 | |||
| 346 | 1. **Server Not Running** | ||
| 347 | ```bash | ||
| 348 | ./gradlew --status | ||
| 349 | ./gradlew run --daemon | ||
| 350 | ``` | ||
| 351 | |||
| 352 | 2. **Authentication Failures** | ||
| 353 | - Verify user exists in Moqui | ||
| 354 | - Check user group memberships | ||
| 355 | - Validate credentials in `opencode.json` | ||
| 356 | |||
| 357 | 3. **Missing Screens** | ||
| 358 | - Ensure required components are installed | ||
| 359 | - Check screen path syntax | ||
| 360 | - Verify user has screen permissions | ||
| 361 | |||
| 362 | 4. **Session Issues** | ||
| 363 | ```bash | ||
| 364 | ./mcp.sh --clear-session | ||
| 365 | ./mcp.sh --new-session | ||
| 366 | ``` | ||
| 367 | |||
| 368 | ### Debug Mode | ||
| 369 | |||
| 370 | Enable detailed logging by setting log level in `MoquiConf.xml`: | ||
| 371 | ```xml | ||
| 372 | <logger name="org.moqui.mcp" level="DEBUG"/> | ||
| 373 | ``` | ||
| 374 | |||
| 375 | ## Contributing | ||
| 376 | |||
| 377 | 1. Follow Moqui coding conventions | ||
| 378 | 2. Add tests for new features | ||
| 379 | 3. Update documentation | ||
| 380 | 4. Ensure security implications are considered | ||
| 381 | 5. Test with the provided test suite | ||
| 382 | 72 | ||
| 383 | ## License | 73 | ## License |
| 384 | 74 | ... | ... |
-
Please register or sign in to post a comment