JoeMCP

# JoeAPI MCP Server Model Context Protocol (MCP) server for JoeAPI construction management system. Exposes construction management tools to Claude and other AI assistants. ## Overview This MCP server provides: - **18 pre-built workflows** for common construction management tasks - **60+ individual tools** for direct API access (CRUD operations) - **Multi-transport support**: Smithery (cloud) and STDIO (local) ## Architecture ``` mcp/ ├── index.ts # Main MCP server (Smithery + STDIO) ├── local-server.ts # STDIO transport runner ├── claude-desktop-config.example.json # Claude Desktop config ├── README.md # This file └── server.ts # Legacy (deprecated) mcp-build/ # Compiled JavaScript (production) ├── index.js # Compiled server ├── local-server.js # Compiled STDIO runner └── *.d.ts # TypeScript definitions ``` ## Deployment Options ### 1. Smithery (Cloud) - **EXISTING** Your MCP server is already deployed on Smithery for cloud access. **Access:** Via Smithery marketplace **URL:** `https://smithery.ai/server/@your-username/joeapi` **Transport:** HTTP **Use case:** Remote access, team collaboration ### 2. Local STDIO - **THIS SETUP** Run MCP server locally on your machine for development/testing. **Transport:** STDIO (Standard Input/Output) **Use case:** Local development, faster iteration, offline work --- ## Local STDIO Setup ### Prerequisites 1. **JoeAPI running locally:** ```bash npm run dev # Start JoeAPI on http://localhost:8080 ``` 2. **Build MCP server:** ```bash npm run mcp:build ``` 3. **Configure Claude Desktop:** - Copy `mcp/claude-desktop-config.example.json` - Update the `command` path to match your installation - Add to Claude Desktop config ### Option A: Development Mode (TypeScript) **For rapid development with auto-recompile:** ```bash npm run mcp:local ``` This runs `tsx mcp/local-server.ts` - TypeScript executed directly (no build needed). ### Option B: Production Mode (Compiled JavaScript) **For production use:** ```bash # Build once npm run mcp:build # Run compiled version npm run mcp:start ``` This runs `node mcp-build/local-server.js` - faster startup, production-ready. --- ## Claude Desktop Configuration ### Step 1: Find Claude Config Directory **macOS:** ```bash ~/Library/Application Support/Claude/ ``` **Windows:** ``` %APPDATA%\Claude\ ``` **Linux:** ``` ~/.config/Claude/ ``` ### Step 2: Edit `claude_desktop_config.json` ```json { "mcpServers": { "joeapi-local": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/joeapi/mcp-build/local-server.js" ], "env": { "JOEAPI_BASE_URL": "http://localhost:8080" }, "disabled": false } } } ``` **Important:** - Use **absolute paths** (not relative like `~/` or `./`) - Change `/ABSOLUTE/PATH/TO/joeapi/` to your actual path - Example: `/Users/joe/dev/joeapi/mcp-build/local-server.js` ### Step 3: Restart Claude Desktop Close and reopen Claude Desktop. The MCP server will connect automatically. ### Step 4: Verify Connection In Claude Desktop, type: ``` Can you use the find_workflow tool? ``` If connected, Claude will have access to all JoeAPI tools. --- ## Available Tools ### Workflow Discovery (ALWAYS START HERE!) **find_workflow** - Discover pre-built workflows - Set `autoExecute: false` to see ALL 18 workflows - Set `autoExecute: true` with workflow name to get step-by-step instructions ### 18 Pre-Built Workflows 1. `win_loss_rate` - Calculate proposal win/loss statistics 2. `sales_pipeline` - Analyze active proposals in pipeline 3. `work_in_process_report` - WIP report for active projects 4. `job_costing_detail` - Detailed job costing analysis 5. `project_profitability` - Profit analysis by project 6. `cost_variance_analysis` - Actual vs. estimated cost variance 7. `cash_flow_forecast` - Project cash flow projections 8. `schedule_variance_analysis` - Schedule delays and impacts 9. `client_portal_update` - Generate client progress updates 10. `subcontractor_performance` - Analyze subcontractor metrics 11. `material_tracking` - Track material costs and usage 12. `labor_productivity` - Analyze labor efficiency 13. `cost_per_square_foot` - Calculate $/sqft by trade 14. `change_order_tracking` - Track change orders/revisions 15. `upgrade_pricing` - Price client upgrade requests 16. `update_schedule` - Extend/adjust project schedules 17. `plan_takeoff` - Estimate from building plans 18. `estimate_from_previous` - Create estimate from past job ### 60+ Individual Tools (Categories) - **Clients** - CRUD operations for clients - **Contacts** - Manage client contacts - **SubContractors** - Subcontractor management - **Proposals** - Create and track proposals - **ProposalLines** - Line items within proposals - **Estimates** - Project estimates - **ProjectManagements** - Active project data - **ProjectSchedules** - Project timelines - **ProjectScheduleTasks** - Individual tasks - **ActionItems** - Track action items with: - Comments - Supervisors - Cost changes - Schedule changes - **Transactions** - QuickBooks transaction data - **JobBalances** - Current job balances - **CostVariance** - Cost variance analysis - **Invoices** - Invoice management - **ScheduleRevisions** - Schedule change tracking - **ProjectDetails** - Comprehensive project data - **ProposalPipeline** - Pipeline analytics - **EstimateRevisions** - Estimate change history - **CostRevisions** - Cost revision tracking - **Deposits** - Deposit/retainer management - **ProposalTemplatePricing** - Standard pricing templates --- ## Environment Variables ### Required ```bash JOEAPI_BASE_URL=http://localhost:8080 # Local JoeAPI server ``` ### Optional (if JoeAPI requires auth) ```bash JOEAPI_API_KEY=your_api_key # API key for JoeAPI JOEAPI_USER_ID=1 # Dev user ID ``` Set these in: 1. **Claude Desktop config** (recommended): ```json "env": { "JOEAPI_BASE_URL": "http://localhost:8080" } ``` 2. **Shell environment** (alternative): ```bash export JOEAPI_BASE_URL=http://localhost:8080 ``` --- ## Troubleshooting ### MCP Server Not Connecting **1. Check JoeAPI is running:** ```bash curl http://localhost:8080/health # Should return: {"status":"healthy",...} ``` **2. Check MCP server builds:** ```bash npm run mcp:build # Should complete without errors ``` **3. Check Claude Desktop logs:** **macOS:** ```bash tail -f ~/Library/Logs/Claude/mcp*.log ``` **Windows:** ```powershell Get-Content $env:APPDATA\Claude\logs\mcp*.log -Wait ``` **4. Test MCP server manually:** ```bash npm run mcp:local # Should output: "JoeAPI MCP Server running locally" # Press Ctrl+C to stop ``` ### Tools Not Appearing in Claude **1. Verify config path is absolute:** ```json "args": ["/Users/joe/dev/joeapi/mcp-build/local-server.js"] ``` Not: `["~/dev/joeapi/mcp-build/local-server.js"]` ❌ **2. Check disabled flag:** ```json "disabled": false // Should be false ``` **3. Restart Claude Desktop:** - Close completely (Cmd+Q on macOS) - Reopen **4. Check for errors in MCP logs** ### JoeAPI Connection Errors **Error:** `JoeAPI error (401)` - JoeAPI requires authentication - Add API key or dev user ID to config **Error:** `JoeAPI error (404)` - Endpoint not found - Check JoeAPI version matches MCP server **Error:** `ECONNREFUSED` - JoeAPI not running - Start with: `npm run dev` --- ## Development ### Adding New Tools 1. **Edit `mcp/index.ts`:** ```typescript { name: 'my_new_tool', description: 'Description of tool', inputSchema: { type: 'object', properties: { param1: { type: 'string', description: '...' } }, required: ['param1'] } } ``` 2. **Add handler in `CallToolRequest`:** ```typescript case 'my_new_tool': { const { param1 } = args as { param1: string }; result = await callJoeAPI(baseUrl, `/api/v1/endpoint`); break; } ``` 3. **Rebuild:** ```bash npm run mcp:build ``` 4. **Restart Claude Desktop** ### Adding New Workflows 1. **Add to `prompts` array in `mcp/index.ts`:** ```typescript { name: 'my_workflow', description: 'Brief description', arguments: [...], prompt: 'WORKFLOW: My Workflow\n\nPURPOSE: ...\n\nSTEPS:\n1. ...' } ``` 2. **Rebuild and restart** --- ## Scripts Reference ```bash # Development npm run mcp:local # Run TypeScript directly (tsx) npm run dev # Run JoeAPI server # Production npm run mcp:build # Compile TypeScript → JavaScript npm run mcp:start # Run compiled JavaScript # Both npm run verify-db # Test database connection ``` --- ## Comparison: Smithery vs Local STDIO | Feature | Smithery (Cloud) | Local STDIO | |---------|------------------|-------------| | **Setup** | Already deployed | Requires local setup | | **Access** | Remote, anywhere | Local machine only | | **Speed** | Network latency | Instant (local) | | **Availability** | Always on | Requires JoeAPI running | | **Updates** | Auto-deployed | Manual build required | | **Collaboration** | Team access | Single user | | **Best for** | Production, team | Development, testing | --- ## Support - **MCP SDK Docs**: https://modelcontextprotocol.io - **Claude Desktop MCP Guide**: https://docs.claude.com/docs/mcp - **JoeAPI Issues**: Check GitHub repo - **MCP Server Code**: `mcp/index.ts`