0f21ef12 by Ean Schuessler

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

… focus on possibilities
1 parent f80b10d7
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
......