Fulfill 3PL MCP Server

MCP server for searching and managing 3PL (third-party logistics) providers.

Installation

For Users (via npm)

Add to your Claude Desktop config:

{
  "mcpServers": {
    "fulfill-3pl": {
      "command": "npx",
      "args": [
        "-y",
        "fulfill-mcp-server-3pl@latest"
      ],
      "env": {
        "SUPABASE_URL": "your-supabase-url",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-key",
        "SLACK_BOT_TOKEN": "optional-slack-token",
        "SLACK_CHANNEL_ID": "optional-channel-id"
      }
    }
  }
}

Then restart Claude Desktop.

For Development

# Clone and install
git clone https://github.com/your-org/fulfill-3pl-mcp.git
cd fulfill-3pl-mcp
npm install

# Configure
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
npm test

Cursor (stdio)

• Name: fulfill-3pl-mcp
• Command: node
• Args: dist/mcp-stdio.js
• Env: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY

Tools

3PL Management (9 tools)

• search_3pls(filters) → Search with filters, pagination, sorting
• get_3pl_profile(id) → Get detailed profile with capabilities, facilities, contacts
• get_facets() → Get aggregated counts for filter options
• find_data_gaps(filters) → Find 3PLs with missing data fields
• search_field_values(filters) → Search for specific values within fields
• get_field_completeness() → Get completeness statistics for all fields
• submit_feedback(data) → Submit bug/feature feedback to Slack and Supabase
• recommend_3pls(rawIntake) → Generate ranked recommendations from brand intake text
• compare_3pls(ids) → Compare multiple 3PLs side-by-side

Brand Opportunities (4 tools)

• get_brand_pipeline(filters) → Track opportunities by stage with conversion metrics
  • 4,291 opportunities tracked
  • Stage distribution and lead values
• get_placement_analytics(filters) → Analyze placement performance
  • 25,498 placements analyzed
  • 41% decline rate, 21% accept rate
• get_attribution_metrics(filters) → Marketing attribution with ROI
  • NEW: Multi-source attribution (PostHog, Salesforce, GA4-ready)
  • 899 partner referrals tracked
  • 39 3PL partners auto-matched
• get_opportunity_details(opportunityId) → Full opportunity details with placements

Current Data Mappings

• Names for specialties from public.specialties
• Names for technology partners from public.partners
• Contacts from public.team_members (via three_pl_team_member_works_at)
• Customers from public.customers (via three_pl_providers)
• Locations parsed from warehouse_locations and locations_for_map (text JSON)
• External IDs in metadata.sources: webflow_record_id, salesforce_account_id

Deployment Options

Docker (Production - WebSocket)

docker compose up -d
# Access at ws://localhost:3001

Local Development (stdio)

npm run dev  # Development with hot reload
npm start    # Production (uses transport from .env)

Recent Updates

v1.2.0 - Attribution System Overhaul (2025-01-19)

• ✅ Multi-Source Attribution - Extensible system for PostHog, GA4, Salesforce, and more
• ✅ Partner Referral Tracking - 899 referrals identified with 39 3PL partners auto-matched
• ✅ Unified Attribution View - Combined view with referral → paid → organic → direct hierarchy
• ✅ Attribution Metrics Enhanced - Now includes partner referrals as primary attribution source
• ✅ GA4 Integration Ready - Full documentation for adding Google Analytics data

v1.1.0 - Brand Opportunities

• ✅ Brand Pipeline Tool - Track 4,291 opportunities by stage with conversion metrics
• ✅ Placement Analytics - Analyze 25,498 placements with accept/decline rates
• ✅ Attribution Metrics - Marketing ROI tracking with multi-source support
• ✅ Opportunity Details - Full brand requirements with placement history

Transport Options

• Stdio (default): Standard input/output for local MCP clients
• WebSocket: Remote access on port 3000 (configurable via MCP_WEBSOCKET_PORT)

  MCP_TRANSPORT=websocket npm start

Roadmap / Next Tasks

• Salesforce data enrichment (fields already in Supabase)
• Brand proximity matching for matchmaking
• Multi-criteria scoring with confidence levels
• Performance: indexes and Redis caching for high-volume queries
• Relevance scoring improvements

Docker

• docker compose up --build

CI

• GitHub Actions runs typecheck/lint/build/tests on push/PR.