joeMCP by lumberjack-so - MCP Server

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

JoeAPI running locally:

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

Build MCP server:
```
npm run mcp:build
```
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

win_loss_rate - Calculate proposal win/loss statistics
sales_pipeline - Analyze active proposals in pipeline
work_in_process_report - WIP report for active projects
job_costing_detail - Detailed job costing analysis
project_profitability - Profit analysis by project
cost_variance_analysis - Actual vs. estimated cost variance
cash_flow_forecast - Project cash flow projections
schedule_variance_analysis - Schedule delays and impacts
client_portal_update - Generate client progress updates
subcontractor_performance - Analyze subcontractor metrics
material_tracking - Track material costs and usage
labor_productivity - Analyze labor efficiency
cost_per_square_foot - Calculate $/sqft by trade
change_order_tracking - Track change orders/revisions
upgrade_pricing - Price client upgrade requests
update_schedule - Extend/adjust project schedules
plan_takeoff - Estimate from building plans
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:

Claude Desktop config (recommended):

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

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

Edit mcp/index.ts:

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

Add handler in CallToolRequest:

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

Rebuild:
```
npm run mcp:build
```
Restart Claude Desktop

Adding New Workflows

Add to prompts array in mcp/index.ts:

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

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