@3bids/mcp-contractor

MCP server for 3Bids contractors - manage your home services business from Claude Code.

Overview

This MCP (Model Context Protocol) server powers Company Brain: a Claude Code workspace for contractors to inspect, operate, and improve the business through 3Bids.

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Claude Code   │────▶│  3bids MCP Server │────▶│  Convex Backend │
│   (contractor)  │◀────│  (this package)   │◀────│ original-peacock│
└─────────────────┘     └──────────────────┘     └─────────────────┘

Installation

For a pitch-deck demo, use the short path:

npx --yes @3bids/mcp-contractor demo

That command stores demo MCP credentials and prints the Claude Code MCP setup command. Add --claude to run the Claude Code setup automatically.

npm install -g @3bids/mcp-contractor

Or configure directly in Claude Code:

claude mcp add 3bids -s user -- npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp serve --bundle headless

Affiliate-only Share & Earn setup:

npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login --affiliate

Generate the token from Share & Earn -> Claude MCP in the affiliate dashboard. Affiliate tokens are read-only, expire after 1 year, and can be revoked from the same panel. The login command prompts for the token so it does not land in shell history.

That registers a separate 3bids-affiliate Claude Code MCP server using the restricted affiliate bundle. Manual setup:

claude mcp add 3bids-affiliate -s user -- npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp serve --bundle affiliate

Headless Bundle

This package defaults to a restricted headless bundle that exposes high-signal read and preview tools. The managed OpenClaw bundle is available through the explicit --bundle openclaw flag, the affiliate reporting bundle is available through --bundle affiliate, and the full catalog requires both --bundle full and THREEBIDS_ENABLE_FULL_MCP=1 in a trusted local operator environment.

For the managed Company Brain setup, generate an MCP token in the contractor app and download Company Brain for Claude Code from Settings -> API Tokens. The zip contains Claude skills, playbooks, and local context files for headless operation.

Canonical allowlist:

• Source of truth: src/tools/openclaw.ts
• Entry point: serve or serve --bundle headless
• OpenClaw bundle: serve --bundle openclaw
• Dedicated binary: 3bids-mcp-openclaw
• Build target: npm run build:openclaw
• NPM script: npm run start:openclaw

Example:

npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login
npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp serve

The default headless bundle intentionally excludes onboarding setup tools, internal admin tools, SMS/campaign launchers, payout actions, and other financial or external side-effect tools.

Affiliate Bundle

The affiliate bundle is read-only and identity-scoped so poster-affiliates and contractor-affiliates can use Claude without seeing contractor operations. Affiliate-generated MCP tokens validate only against this bundle; they do not authenticate contractor tools.

Included tools:

| Tool | Description | |------|-------------| | get_affiliate_dashboard | Share & Earn overview, earnings, referrals, payout readiness | | get_affiliate_earnings_summary | Lifetime earnings, payable/pending/paid balances, referred revenue, and tier | | get_affiliate_next_payout | Next paycheck estimate, payable-now balance, payout blockers, and Stripe readiness | | list_affiliate_referrals | Paginated referred-user list | | get_affiliate_referral_overview | Referral totals, top referrals, recent referrals, funnel, and optional referral page | | list_affiliate_commissions | Recent commissions and status totals | | get_affiliate_payouts | Payout readiness and recent payouts | | get_affiliate_channel_analytics | Click/signup funnel and per-channel breakdown | | get_affiliate_campaign_performance | Campaign/channel performance plus weekly click, signup, and earning activity | | get_affiliate_activity_timeline | Weekly activity, recent referrals, commissions, and payouts | | get_affiliate_share_links | Referral code, links, QR payload, and message templates | | get_affiliate_commission_schedule | Tier rate, commission window, and payout minimum | | get_affiliate_earnings_projection | Calculator assumptions, scenario matrix, and projected commissions | | read_3bids_docs | Customer-facing 3Bids concept docs |

The bundle excludes contractor job tools, dispatch, bids, messaging, admin tools, campaign launchers, and payout mutations.

By default, the package connects to the production Convex site: https://original-peacock-353.convex.site.

Set CONVEX_SITE_URL only when you intentionally need a non-production deployment, and pair non-production origins with THREEBIDS_MCP_ALLOW_UNTRUSTED_ORIGIN=1.

Getting Your MCP Token

1. Log in to the 3Bids contractor app
2. Go to Contractor -> Settings -> API Tokens
3. Click Generate New Token
4. Run npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login If the browser flow is unavailable, run npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login --manual and paste the token into the stdin prompt.

Available Tools (full bundle examples)

Jobs (Read-Only)

| Tool | Description | |------|-------------| | search_jobs | Search available jobs by keyword, category, location, budget | | get_job | Get full job details including your bid status | | get_job_stats | Get your job statistics | | get_nearby_jobs | Find jobs near your location | | get_recommended_jobs | Get AI-recommended jobs |

Bids (Read/Write)

| Tool | Description | |------|-------------| | list_bids | List your bids with status filter | | get_bid | Get bid details | | submit_bid | Submit a new bid | | update_bid | Update a pending bid | | withdraw_bid | Withdraw a bid | | get_bid_stats | Get bid statistics |

Messages (Read/Write)

| Tool | Description | |------|-------------| | list_conversations | List job conversations | | get_messages | Get messages for a job | | send_message | Send a message | | get_unread_count | Get unread message count | | list_quick_replies | Get message templates |

Earnings (Read-Only)

| Tool | Description | |------|-------------| | get_earnings_summary | Get financial summary | | get_payment_history | Get payout history | | get_pending_payouts | Get pending releases | | get_escrow_detail | Get project breakdown | | get_tax_summary | Get tax-year summary |

Dispatch (Read/Write)

| Tool | Description | |------|-------------| | get_dispatch_board | Get today's dispatch overview | | list_assignments | List job assignments | | get_assignment | Get assignment details | | create_assignment | Schedule a job | | update_assignment_status | Update assignment status | | get_today_route | Get optimized route | | get_team_locations | Get team GPS locations |

Profile (Read/Write)

| Tool | Description | |------|-------------| | get_profile | Get your profile | | update_profile | Update profile info | | get_verification_status | Get verification status | | get_profile_completion | Get profile completion % |

Portfolio (Read/Write)

| Tool | Description | |------|-------------| | list_portfolio | List portfolio items | | add_portfolio_item | Add portfolio item | | update_portfolio_item | Update portfolio item | | remove_portfolio_item | Remove portfolio item |

Active Jobs (Read/Write)

| Tool | Description | |------|-------------| | get_active_jobs | Get non-completed jobs | | mark_job_started | Start work on a job | | update_job_progress | Update job progress | | request_job_completion | Request completion review |

Example Usage

In Claude Code:

> Show me open plumbing jobs near me

Found 12 plumbing jobs within 25 miles:
1. Water heater replacement - $800-1200 - 3.2 miles
2. Bathroom remodel plumbing - $2000-3500 - 5.8 miles
...

> Submit a $950 bid on job #1 with note "Licensed plumber, can start tomorrow"

Bid submitted successfully!
- Job: Water heater replacement (#JOB-2024-1234)
- Amount: $950
- Status: Pending

> What's my earnings this month?

Earnings Summary:
- This month: $4,850
- Pending payouts: $1,200
- In project: $3,400
- Last month: $6,200

> Show today's dispatch board

Today's Schedule (Feb 12, 2026):
- 9:00 AM - Kitchen sink repair @ 123 Main St (en route)
- 11:30 AM - Water heater install @ 456 Oak Ave (scheduled)
- 2:00 PM - Bathroom fixture @ 789 Pine St (scheduled)

Total: 3 jobs | 1 en route | 2 scheduled

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/cli/index.js login
node dist/cli/index.js serve

# Watch mode
npm run dev

Operator release

MCP package publication is an explicit local CLI operation. GitHub Actions do not publish this package, and merging does not auto-publish it.

# Validate tests, both builds, and the exact public tarball without publishing
npm run release:check

# From a clean checkout at exact origin/main, publish only after confirming
# the package.json version exactly
mcp_version=$(node -p "require('./package.json').version")
npm run release:publish -- --confirm "$mcp_version"

The publish command fails closed unless npm authentication works, the release manifest is pending, the version is absent from the registry, and the checkout matches freshly fetched origin/main. It does not commit, push, or deploy the web or Convex applications.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CONVEX_SITE_URL | No | Explicit Convex site URL override. Defaults to production and rejects untrusted origins without local-development opt-in. | | THREEBIDS_MCP_CONVEX_URL | No | Alternate explicit Convex site URL override for local development. | | THREEBIDS_MCP_ALLOW_UNTRUSTED_ORIGIN | No | Set to 1 only for local development against non-production Convex origins. | | THREEBIDS_ENABLE_FULL_MCP | No | Set to 1 only for trusted operators who need serve --bundle full. | | THREEBIDS_API_TOKEN | No | Internal/legacy token override only. User-facing token argv flows such as login --token are blocked; use npm exec --yes --package @3bids/mcp-contractor -- 3bids-mcp login. |

Security

• Tokens are validated on every request via Clerk JWKS or hashed MCP token lookup
• Contractor tokens authenticate contractor/headless bundles and can request the affiliate bundle only for active affiliate identities; affiliate tokens authenticate only the affiliate bundle
• Contractor self-serve tokens default to read-only access and expire after 30 days; affiliate tokens default to read-only access and expire after 1 year
• Rate limiting is enforced per token when token auth is used

Support

• Issues: https://github.com/mindcraftreader/3bidrn/issues
• Docs: https://docs.3bids.io/mcp
• Email: [email protected]

License

MIT