# ๐ฎ Postman Testing Guide for Trackex MCP Server
## ๐ Setup Instructions
### 1. **Import the Collection**
1. Open Postman
2. Click "Import"
3. Upload `Trackex-MCP-Postman-Collection.json`
4. Set environment variables:
- `mcp_base_url`: `http://localhost:3002`
- `api_key`: Your actual 64-character API key
### 2. **Start Both Servers**
```bash
npm run dev:both
```
Make sure both servers are running:
- Main API: `http://localhost:3000`
- MCP Server: `http://localhost:3002`
## โ **What You CAN Test with Postman**
### **1. Health Check**
```
GET http://localhost:3002/health
```
**Expected Response:**
```json
{
"status": "healthy",
"message": "MCP HTTP Test Wrapper is running",
"config": {
"apiBaseUrl": "http://localhost:3000/api/v1",
"debug": false,
"requireApiKey": true
}
}
```
### **2. Get Today's Tasks**
```
GET http://localhost:3002/mcp/get_today_tasks
Headers: X-API-Key: your-api-key
```
**Expected Response:**
```json
{
"success": true,
"message": "Tasks retrieved successfully",
"tasks": [...],
"total": 5
}
```
### **3. Create Task**
```
POST http://localhost:3002/mcp/create_task
Content-Type: application/json
{
"api_key": "your-api-key",
"title": "Test Task from Postman",
"description": "Testing MCP endpoint",
"task_type": "adhoc",
"priority": "medium"
}
```
### **4. Get Pending Tasks**
```
GET http://localhost:3002/mcp/get_pending_tasks
Headers: X-API-Key: your-api-key
```
### **5. Get Adhoc Tasks**
```
GET http://localhost:3002/mcp/get_adhoc_tasks
Headers: X-API-Key: your-api-key
```
## โ **What You CANNOT Test with Postman**
### **Natural Language Queries:**
```
โ "Show me my tasks for today"
โ "Create a task to fix the login bug"
โ "How many tasks are pending?"
โ "Mark task 123 as completed"
```
**Why?** Because natural language processing happens at the AI level (Claude, ChatGPT), not at the HTTP API level.
## ๐งช **Step-by-Step Testing Process**
### **Step 1: Test Health**
1. Send GET to `/health`
2. Verify MCP server is running
3. Check configuration
### **Step 2: Test Authentication**
1. Try request without API key โ Should get 400 error
2. Try with invalid API key โ Should get authentication error
3. Try with valid API key โ Should succeed
### **Step 3: Test Data Retrieval**
1. Test `/mcp/get_today_tasks`
2. Test with different `limit` parameters
3. Verify data structure matches expected format
### **Step 4: Test Task Creation**
1. Create task with minimal data
2. Create task with full data
3. Test validation errors (missing title, etc.)
### **Step 5: Test Error Handling**
1. Send malformed JSON
2. Send invalid parameters
3. Test API key validation
## ๐ง **Common Issues & Solutions**
### **Issue: "Unable to connect"**
**Solution:**
- Ensure MCP server is running: `npm run dev:both`
- Check port 3002 is not blocked
### **Issue: "Invalid API key format"**
**Solution:**
- API key must be exactly 64 characters
- Use a valid API key from your Trackex system
### **Issue: "API key is required"**
**Solution:**
- Include `X-API-Key` header OR
- Include `Authorization: Bearer` header OR
- Include `api_key` in request body (for POST)
## ๐ **Testing Natural Language (Alternative Methods)**
Since Postman can't test natural language, here are alternatives:
### **Method 1: Claude AI Integration**
1. Set up Claude with your MCP server
2. Chat naturally: "Show me today's tasks"
3. Claude converts to MCP calls automatically
### **Method 2: Build a Test Chat Interface**
```html
Trackex AI Chat Test
```
### **Method 3: Use Claude Desktop App**
1. Install Claude Desktop
2. Configure it to use your MCP server
3. Chat naturally and see real MCP calls
## ๐ **Testing Checklist**
- [ ] โ Health check passes
- [ ] โ Authentication works with valid API key
- [ ] โ Authentication fails with invalid API key
- [ ] โ Get today's tasks returns data
- [ ] โ Create task works with valid data
- [ ] โ Create task fails with invalid data
- [ ] โ Pending tasks endpoint works
- [ ] โ Adhoc tasks endpoint works
- [ ] โ Error responses are properly formatted
- [ ] โ Natural language (requires AI integration)
## ๐ฏ **Summary**
**Postman is perfect for:**
- โ Testing HTTP endpoints
- โ Validating API responses
- โ Testing authentication
- โ Debugging API issues
**Postman cannot test:**
- โ Natural language processing
- โ AI conversation flows
- โ Dynamic language interpretation
**For natural language testing, you need an actual AI interface that can:**
1. Understand human language
2. Convert it to structured API calls
3. Call your MCP endpoints
4. Format responses back to human language