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:

   npm run dev  # Start JoeAPI on http://localhost:8080
   

2. Build MCP server:

   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:

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:

# 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:

~/Library/Application Support/Claude/

Windows:

%APPDATA%\Claude\

Linux:

~/.config/Claude/

Step 2: Edit claude_desktop_config.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

JOEAPI_BASE_URL=http://localhost:8080  # Local JoeAPI server

Optional (if JoeAPI requires auth)

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):

   "env": {
     "JOEAPI_BASE_URL": "http://localhost:8080"
   }
   

2. Shell environment (alternative):

   export JOEAPI_BASE_URL=http://localhost:8080
   

---

Troubleshooting

MCP Server Not Connecting

1. Check JoeAPI is running:

curl http://localhost:8080/health
# Should return: {"status":"healthy",...}

2. Check MCP server builds:

npm run mcp:build
# Should complete without errors

3. Check Claude Desktop logs:

macOS:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows:

Get-Content $env:APPDATA\Claude\logs\mcp*.log -Wait

4. Test MCP server manually:

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:

"args": ["/Users/joe/dev/joeapi/mcp-build/local-server.js"]

Not: ["~/dev/joeapi/mcp-build/local-server.js"] ❌

2. Check disabled flag:

"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:

   {
     name: 'my_new_tool',
     description: 'Description of tool',
     inputSchema: {
       type: 'object',
       properties: {
         param1: { type: 'string', description: '...' }
       },
       required: ['param1']
     }
   }
   

2. Add handler in CallToolRequest:

   case 'my_new_tool': {
     const { param1 } = args as { param1: string };
     result = await callJoeAPI(baseUrl, `/api/v1/endpoint`);
     break;
   }
   

3. Rebuild:

   npm run mcp:build
   

4. Restart Claude Desktop

Adding New Workflows

1. Add to prompts array in mcp/index.ts:

   {
     name: 'my_workflow',
     description: 'Brief description',
     arguments: [...],
     prompt: 'WORKFLOW: My Workflow\n\nPURPOSE: ...\n\nSTEPS:\n1. ...'
   }
   

2. Rebuild and restart

---

Scripts Reference

# 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