# Story 3.6: Verification & Testing Guide
**Epic:** Epic 3 - Installation & Quick Start Guide
**Story ID:** STORY-3.6
**Status:** Draft
**Created:** 2025-12-27
**Updated:** 2025-12-27
---
## User Story
**As a** user who completed installation and first workflow tutorial
**I want** comprehensive verification steps and testing procedures
**So that** I can confirm everything is working correctly and troubleshoot any issues
---
## Story Description
### Current System Context
The MCP server provides multiple verification points:
**Health Check Endpoint:**
- URL: `http://localhost:<MCP_PORT>/health`
- Response: `{"status":"ok","version":"0.9.1"}`
**MCP Tools Available:** 17 tools across 4 categories
- Workflows: 8 tools (list, get, create, update, delete, activate, deactivate, execute)
- Executions: 4 tools (list, get, delete, retry)
- Tags: 5 tools (create, get, update, delete, list)
- Credentials: 6 tools (informative guidance only)
**Testing Infrastructure:**
- `/test-mcp-tools.js` - Comprehensive test suite
- `/test-comprehensive.js` - Full integration tests
- Health check endpoint
- n8n API connectivity validation
**Current Testing Documentation:**
- README.md mentions test files
- No comprehensive verification guide
- No systematic testing procedure
- No troubleshooting decision tree
### Enhancement: Comprehensive Verification & Testing Guide
Create systematic verification guide covering:
**Installation Verification:**
- Package installation confirmation
- Build verification (manual install)
- Version checking
- File structure validation
**Configuration Verification:**
- Environment variables loaded correctly
- Multi-instance configuration working
- n8n API connectivity test
- API key validation
**MCP Server Verification:**
- Server starts successfully
- Health endpoint responds
- Correct port binding
- Process running check
**Claude Desktop Integration Verification:**
- MCP server appears in Claude
- Tool discovery working
- Basic tool execution test
- Multi-tool workflow test
**n8n Integration Verification:**
- API connectivity test
- Authentication successful
- Workflow CRUD operations
- Execution tracking working
- Tags management functional
**Comprehensive Testing:**
- Running test suite
- Interpreting test results
- Test cleanup procedures
- Custom test scenarios
**Troubleshooting Decision Tree:**
- Systematic issue diagnosis
- Common failure patterns
- Fix verification
- When to seek help
---
## Acceptance Criteria
### Documentation Requirements
**AC1: Installation Verification**
- [ ] **NPM Installation Check:**
```bash
# Global installation
npm list -g @bmad-labs/mcp-n8n-workflow-builder
# Expected: @bmad-labs/mcp-n8n-workflow-builder@0.9.1
# Local installation
npm list @bmad-labs/mcp-n8n-workflow-builder
# Expected: @bmad-labs/mcp-n8n-workflow-builder@0.9.1
# Version check
npx @bmad-labs/mcp-n8n-workflow-builder --version
# Expected: 0.9.1
```
- [ ] **Manual Build Check:**
```bash
# Verify build directory exists
ls -la build/
# Expected files:
# - index.js (main entry point)
# - config/ (configuration modules)
# - services/ (business logic)
# - types/ (TypeScript definitions)
# - utils/ (utilities)
# Verify build is recent
stat build/index.js
# Check timestamp matches recent build
```
- [ ] **File Structure Validation:**
```bash
# Check required files exist
test -f package.json && echo "✅ package.json"
test -f tsconfig.json && echo "✅ tsconfig.json"
test -d src && echo "✅ src/"
test -d build && echo "✅ build/"
```
- [ ] Success criteria: All checks pass with ✅
**AC2: Configuration Verification**
- [ ] **Environment Variables Check:**
```bash
# For .env configuration
test -f .env && echo "✅ .env file exists"
grep -q "N8N_HOST" .env && echo "✅ N8N_HOST configured"
grep -q "N8N_API_KEY" .env && echo "✅ N8N_API_KEY configured"
# For multi-instance configuration
test -f .config.json && echo "✅ .config.json exists"
# Validate JSON syntax
node -e "JSON.parse(require('fs').readFileSync('.config.json'))" \
&& echo "✅ .config.json valid JSON"
```
- [ ] **Configuration Loading Test:**
```javascript
// Create test script: verify-config.js
const { ConfigLoader } = require('./build/config/configLoader');
const config = ConfigLoader.getInstance();
console.log('✅ Config loaded successfully');
console.log('Environments:', Object.keys(config.environments || {}));
console.log('Default env:', config.defaultEnv || 'from .env');
```
- [ ] **n8n API Connectivity Test:**
```bash
# Test n8n API directly
curl -X GET \
'https://your-instance.app.n8n.cloud/api/v1/workflows' \
-H "X-N8N-API-KEY: your_api_key" \
-H "Accept: application/json"
# Expected: JSON response with workflows list
# ✅ Success: {"data": [...]}
# ❌ Failure: 401 Unauthorized / Network error
```
- [ ] **API Key Validation:**
- Test with correct key → 200 OK
- Test with invalid key → 401 Unauthorized
- Test with missing key → 401 Unauthorized
**AC3: MCP Server Verification**
- [ ] **Server Startup Test:**
```bash
# Start server
npm start
# OR
node build/index.js
# OR
npx @bmad-labs/mcp-n8n-workflow-builder
# Expected output:
# MCP Server starting...
# Health check endpoint: http://localhost:3456/health
# MCP Server started successfully
```
- [ ] **Health Endpoint Test:**
```bash
# In separate terminal
curl http://localhost:3456/health
# Expected response:
# {"status":"ok","version":"0.9.1"}
```
- [ ] **Port Binding Verification:**
```bash
# Check port is listening
lsof -i :3456
# OR (Linux)
netstat -tlnp | grep 3456
# Expected: node process listening on port 3456
```
- [ ] **Process Verification:**
```bash
# Check process is running
ps aux | grep "mcp-n8n-workflow-builder"
# OR
ps aux | grep "build/index.js"
# Expected: Active node process
```
**AC4: Claude Desktop Integration Verification**
- [ ] **MCP Server Discovery:**
```
In Claude Desktop:
User: "What MCP servers do you have available?"
Expected response includes:
- n8n-workflow-builder
```
- [ ] **Tool Discovery Test:**
```
User: "What n8n tools do you have?"
Expected: List of 17 tools across 4 categories:
- Workflows (8)
- Executions (4)
- Tags (5)
- Credentials (6 - guidance only)
```
- [ ] **Basic Tool Execution:**
```
User: "List my n8n workflows"
Expected: Claude uses list_workflows tool
Response: List of workflows with IDs, names, status
```
- [ ] **Multi-Tool Workflow Test:**
```
User: "Create a tag called 'Test', list all tags, then delete the test tag"
Expected sequence:
1. create_tag('Test') → success, returns tag ID
2. get_tags() → shows all tags including 'Test'
3. delete_tag(tag_id) → success, tag removed
All operations complete without errors
```
**AC5: n8n Integration Verification**
- [ ] **Workflow CRUD Test:**
```
Test sequence in Claude Desktop:
1. CREATE:
User: "Create a simple test workflow with just a Start node"
✅ Workflow created, ID returned
2. READ:
User: "Get the workflow we just created"
✅ Full workflow details returned
3. UPDATE:
User: "Update the workflow name to 'Test Workflow Updated'"
✅ Workflow name updated
4. LIST:
User: "List all workflows"
✅ Updated workflow appears in list
5. DELETE:
User: "Delete the test workflow"
✅ Workflow deleted successfully
```
- [ ] **Execution Tracking Test:**
```
1. Create simple workflow with webhook trigger
2. Activate workflow
3. Trigger via curl
4. List executions
5. Get execution details
6. Verify execution data
All steps complete with expected results
```
- [ ] **Tags Management Test:**
```
1. Create tag: "Verification Test"
2. List tags, verify new tag exists
3. Update tag name to "Verified"
4. Get updated tag
5. Delete tag
6. Verify tag removed
All operations successful
```
**AC6: Comprehensive Test Suite**
- [ ] **Running Test Suite:**
```bash
# Install test dependencies if needed
npm install
# Run comprehensive tests
node test-mcp-tools.js
# Expected output:
# ✅ Workflow Tests: PASSED (8/8)
# ✅ Execution Tests: PASSED (4/4)
# ✅ Tag Tests: PASSED (5/5)
# ✅ Cleanup: PASSED
#
# Overall: ALL TESTS PASSED
```
- [ ] **Test Configuration:**
```javascript
// In test-mcp-tools.js
const config = {
mcpServerUrl: 'http://localhost:3456/mcp',
healthCheckUrl: 'http://localhost:3456/health',
testFlags: {
runWorkflowTests: true,
runTagTests: true,
runExecutionTests: true,
runCleanup: true // Cleanup test artifacts
}
};
```
- [ ] **Interpreting Test Results:**
- ✅ Green checkmarks → All tests passed
- ❌ Red X → Test failed (see error details)
- ⏭️ Skipped → Test skipped (check flags)
- 🧹 Cleanup → Test artifacts removed
- [ ] **Test Cleanup Verification:**
```
After tests complete:
1. No test workflows remain in n8n
2. No test tags remain
3. No test executions clutter history
List workflows and tags to confirm cleanup
```
**AC7: Troubleshooting Decision Tree**
- [ ] **Server Won't Start → Diagnosis:**
```
Issue: Server fails to start
Check 1: Port conflict
→ Run: lsof -i :3456
→ If port in use: Change MCP_PORT in config
→ If port free: Continue to Check 2
Check 2: Missing dependencies
→ Run: npm install
→ Verify node_modules exists
→ If missing: Run npm install
Check 3: Build artifacts missing (manual install)
→ Run: test -d build && echo "OK" || echo "Missing"
→ If missing: Run npm run build
Check 4: Environment variables
→ Verify .env or .config.json exists
→ Check file contents
→ Fix configuration issues
```
- [ ] **Tools Not Available in Claude → Diagnosis:**
```
Issue: Claude Desktop doesn't show n8n tools
Check 1: MCP server in config
→ Open claude_desktop_config.json
→ Verify "n8n-workflow-builder" entry exists
→ Fix: Add correct configuration
Check 2: Claude Desktop restart
→ Completely quit Claude Desktop (Cmd+Q)
→ Restart application
→ Wait for MCP servers to initialize
Check 3: Server running
→ Check health endpoint: curl http://localhost:3456/health
→ If fails: Start MCP server
Check 4: JSON syntax errors
→ Validate JSON: node -e "JSON.parse(require('fs').readFileSync('claude_desktop_config.json'))"
→ Fix syntax errors
```
- [ ] **API Connection Fails → Diagnosis:**
```
Issue: Tools fail with connection errors
Check 1: n8n instance accessible
→ Test: curl https://your-instance.app.n8n.cloud
→ If fails: Check n8n instance is running
Check 2: API key valid
→ Test n8n API directly with key
→ If 401: Regenerate API key in n8n
Check 3: Network/firewall
→ Check corporate proxy settings
→ Verify firewall allows connections
→ Test from different network
Check 4: URL format
→ Verify N8N_HOST doesn't include /api/v1
→ Server auto-appends /api/v1
→ Fix: Remove /api/v1 from config
```
- [ ] **Workflow Creation Fails → Diagnosis:**
```
Issue: create_workflow returns error
Check 1: Workflow structure
→ Verify nodes array is valid
→ Check connections format
→ Fix: Use workflow prompts for valid structure
Check 2: Node types valid
→ Verify node types exist in n8n
→ Check typeVersion matches
→ Fix: Use standard n8n node types
Check 3: Credentials required
→ Some nodes need credentials configured
→ Configure in n8n UI first
→ Then create workflow
Check 4: Instance parameter
→ If multi-instance: specify instance
→ Verify instance name correct
→ Fix: Use correct instance identifier
```
**AC8: Success Confirmation Checklist**
- [ ] Complete verification checklist:
```markdown
## Installation Verification ✅
- [ ] Package installed successfully
- [ ] Build directory present (manual install)
- [ ] Version matches expected (0.9.1)
## Configuration Verification ✅
- [ ] .env or .config.json exists
- [ ] Environment variables load correctly
- [ ] n8n API connection successful
- [ ] API key valid
## MCP Server Verification ✅
- [ ] Server starts without errors
- [ ] Health endpoint responds
- [ ] Correct port binding
- [ ] Process running
## Claude Desktop Integration ✅
- [ ] MCP server discovered
- [ ] All 17 tools available
- [ ] Basic tool execution works
- [ ] Multi-tool workflows work
## n8n Integration ✅
- [ ] Workflow CRUD operations successful
- [ ] Execution tracking working
- [ ] Tags management functional
- [ ] Test suite passes (17/17 tests)
## Overall Status
All checks passed → ✅ **SYSTEM READY**
Some checks failed → ⚠️ **TROUBLESHOOTING NEEDED** (use decision tree)
```
---
## Technical Implementation Notes
### Documentation Structure
```markdown
# Verification & Testing Guide
## Overview
### Verification Checklist
- Installation
- Configuration
- MCP Server
- Claude Desktop
- n8n Integration
- Testing
### When to Use This Guide
- After installation
- After configuration changes
- When troubleshooting
- Before production use
## Installation Verification
### NPM Installation
- Global check
- Local check
- Version verification
### Manual Build
- Build directory check
- File structure validation
- Build timestamp
### Success Criteria
## Configuration Verification
### Environment Variables
- .env file check
- .config.json validation
- Variable loading test
### n8n API Connectivity
- Direct API test
- Authentication validation
- Network connectivity
### Success Criteria
## MCP Server Verification
### Server Startup
- Start command
- Expected output
- Error handling
### Health Endpoint
- Curl test
- Expected response
- Troubleshooting
### Port and Process
- Port binding check
- Process verification
### Success Criteria
## Claude Desktop Integration
### MCP Discovery
- Server visibility
- Tool discovery
### Tool Execution
- Basic tool test
- Multi-tool workflow
### Success Criteria
## n8n Integration Verification
### Workflow CRUD
- Create test
- Read test
- Update test
- Delete test
### Execution Tracking
- Trigger workflow
- List executions
- Get execution details
### Tags Management
- Create tag
- List tags
- Update tag
- Delete tag
### Success Criteria
## Comprehensive Testing
### Running Test Suite
- Test command
- Test configuration
- Expected output
### Interpreting Results
- Success indicators
- Failure diagnosis
- Cleanup verification
### Custom Tests
- Creating test scenarios
- Validation procedures
## Troubleshooting
### Decision Trees
1. Server won't start
2. Tools not available
3. API connection fails
4. Workflow creation fails
### Common Solutions
- Port conflicts
- Configuration errors
- Network issues
- Permission problems
### When to Seek Help
- GitHub issues
- Community support
## Success Confirmation
### Final Checklist
- All verification categories
- Overall status assessment
### Next Steps
- Production usage
- Advanced features
- Community resources
```
### Content Sources
**Primary References:**
- `/test-mcp-tools.js` - test suite structure
- `/test-comprehensive.js` - integration tests
- `/README.md` - testing section
- `/docs/TROUBLESHOOTING.md` (to be created in Epic 8)
### Visual Assets Needed
1. **Flowchart:** Verification sequence (Installation → Config → Server → Claude → n8n → Tests)
2. **Decision Tree:** Server won't start diagnosis
3. **Decision Tree:** Tools not available diagnosis
4. **Decision Tree:** API connection fails diagnosis
5. **Screenshot:** Successful test suite output
6. **Checklist Diagram:** Success confirmation visual
---
## Dependencies
### Upstream Dependencies
- **Story 3.1** OR **Story 3.2** (Installation)
- **Story 3.3** (Configuration)
- **Story 3.4** (Claude Desktop Integration)
- **Story 3.5** (First Workflow Tutorial)
### Downstream Dependencies
- **Epic 4 Stories** assume verification is complete
- **Epic 8 Story 8.1** (Common Issues) references this for systematic diagnosis
### Related Stories
- **Epic 8 Story 8.2** (Debug Mode Guide) - advanced troubleshooting
- **Epic 8 Story 8.3** (Testing Infrastructure) - developer testing guide
---
## Definition of Done
### Content Checklist
- [ ] Installation verification documented
- [ ] Configuration verification complete
- [ ] MCP server verification steps
- [ ] Claude Desktop integration tests
- [ ] n8n integration verification
- [ ] Test suite running guide
- [ ] Troubleshooting decision trees (4+)
- [ ] Success confirmation checklist
### Quality Checklist
- [ ] All verification steps tested on 3 platforms
- [ ] Test suite executed and documented
- [ ] Decision trees validated with real failures
- [ ] Screenshots from actual test runs
- [ ] Markdown formatting validated
- [ ] Internal links working
### Review Checklist
- [ ] Peer review by Dev Agent
- [ ] QA Agent validation
- [ ] Editor review for clarity
- [ ] User testing with deliberate failures
---
## Estimation
**Effort:** 6 story points (4-5 hours)
**Breakdown:**
- Installation verification: 45 minutes
- Configuration verification: 45 minutes
- MCP server verification: 45 minutes
- Claude Desktop integration tests: 60 minutes
- n8n integration tests: 60 minutes
- Test suite documentation: 45 minutes
- Troubleshooting decision trees: 60 minutes
**Page Count:** 12-15 pages
---
## Notes
### Testing Philosophy
- Systematic verification from bottom to top
- Each layer depends on previous layer
- Clear success/failure criteria for each check
- Decision trees for efficient troubleshooting
- Emphasis on self-service diagnosis
### Success Metrics
- User can complete verification in 15 minutes
- 90%+ of issues diagnosed through decision trees
- Clear go/no-go decision for production use
- Reduced support requests through self-service
---
**Story Owner:** QA Agent + Technical Writer (Scribe Persona)
**Reviewers:** Dev Agent, QA Agent, DevOps Agent
**Target Milestone:** Epic 3 - Phase 2 (Stories 3.4-3.6)
