asachs01/float-mcp

Float MCP Server

A comprehensive Model Context Protocol (MCP) server that provides seamless integration with Float.com - the resource management and project planning platform. This server exposes Float's complete API as MCP tools, enabling AI assistants like Claude to interact with Float for project management, resource allocation, time tracking, and team coordination.

🌟 Features

Complete Float API Coverage

• 👥 People Management - Full CRUD operations for team members
• 📁 Project Management - Projects, phases, tasks, and milestones
• ⏱️ Time Tracking - Logged time, timesheets, and billable hours
• 📊 Resource Allocation - Team member assignments and scheduling
• 🎯 Task Management - Project tasks, dependencies, and workflows
• 🏢 Organization - Departments, roles, accounts, and permissions
• 📅 Time Off - PTO requests, approvals, and holiday management
• 📈 Reports - Time reports, utilization, and project analytics

Advanced Features

• 🔄 Rate Limiting - Built-in API rate limiting with exponential backoff
• 🛡️ Type Safety - Full TypeScript support with Zod schema validation
• 📝 Comprehensive Logging - Detailed logging for debugging and monitoring
• ⚡ Performance - Optimized for fast response times and efficient API usage
• 🧪 Testing - Comprehensive integration test suite
• 🐳 Docker Support - Ready-to-deploy Docker container

🚀 Quick Start

Prerequisites

• Node.js 22.0.0 or later
• Float.com account with API access
• Valid Float API key

1. Installation Options

A. DXT Extension (Recommended)

For DXT-compatible environments, download the latest DXT package:

📦 Download Float MCP Extension (.dxt)

Install the .dxt file through your DXT-compatible application.

B. Manual Installation

# Using npm
npm install

# Using yarn
yarn install

2. Configuration

Create a .env file in the project root:

# Float API Configuration
FLOAT_API_KEY=your_float_api_key_here
FLOAT_API_BASE_URL=https://api.float.com/v3

# Optional: Enable debug logging
LOG_LEVEL=info

3. Build & Run

# Build the project
npm run build

# Start the MCP server
npm start

# For development with auto-reload
npm run dev

4. MCP Client Integration

For DXT Installation

After installing the DXT extension, configure your Float API key in the extension settings. The extension will handle the MCP server configuration automatically.

For Manual Installation

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "float-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "FLOAT_API_KEY=YOURAPIKEY",
        "-e",
        "LOG_LEVEL=debug",
        "ghcr.io/asachs01/float-mcp:latest"
      ]
    }
  }
}

🚀 Available Tools

The Float MCP server provides 4 optimized decision-tree tools that efficiently replace 246+ granular tools while maintaining complete functionality:

🔧 Optimized Tools (Recommended)

1. manage-entity - Core Entity Management

Consolidates all CRUD operations for core entities with decision tree routing:

manageEntity({
  entity_type: "people" | "projects" | "tasks" | "clients" | "departments" | "roles" | "accounts" | "statuses",
  operation: "list" | "get" | "create" | "update" | "delete" | "get-current-account" | "bulk-update-account-permissions",
  // ... entity-specific parameters
})

Replaces: All CRUD tools for people, departments, roles, accounts, projects, tasks, clients, and statuses (~120 tools)

2. manage-project-workflow - Project Operations

Handles all project-specific workflow operations:

manageProjectWorkflow({
  workflow_type: "phases" | "milestones" | "project-tasks" | "allocations", 
  operation: "list" | "get" | "create" | "update" | "delete" | "complete" | "archive" | "bulk-create" | "reorder",
  // ... workflow-specific parameters
})

Replaces: Project phases, milestones, project tasks, allocations, dependencies, bulk operations (~60 tools)

3. manage-time-tracking - Time Management

Manages all time-related operations with comprehensive reporting:

manageTimeTracking({
  tracking_type: "logged-time" | "timeoff" | "public-holidays" | "team-holidays",
  operation: "list" | "get" | "create" | "update" | "delete" | "approve" | "reject" | "bulk-create",
  report_type?: "person-summary" | "project-summary" | "timesheet" | "billable-analysis",
  // ... time-specific parameters  
})

Replaces: Logged time, time off, holidays, approvals, timesheets, summaries (~45 tools)

4. generate-report - Analytics & Reporting

Comprehensive reporting and analytics engine:

generateReport({
  report_type: "time-report" | "project-report" | "people-utilization-report" | "capacity-report" | "budget-report",
  // Advanced filtering and grouping options
  group_by?: "person" | "project" | "client" | "department" | "date" | "week" | "month",
  include_details?: boolean,
  // ... extensive reporting parameters
})

Replaces: All reporting tools with advanced analytics, grouping, filtering (~20 tools)

📊 Optimization Benefits

• 🔥 Massive Efficiency: 246+ tools → 4 optimized tools (98.4% reduction)
• 🧠 AI-Friendly: Decision tree parameters instead of tool proliferation
• ⚡ Better Performance: Consolidated API calls and reduced overhead
• 🔒 Full Compatibility: Zero functionality loss, complete backward compatibility
• 🛠️ Easier Maintenance: Centralized logic with consistent patterns

🔄 Legacy Tools (Backward Compatibility)

All original 246+ granular tools remain available for backward compatibility:

Reporting & Analytics

• Reports: get-time-report, get-project-report, get-people-utilization-report
• Analytics: get-person-logged-time-summary, get-project-logged-time-summary

🔧 Configuration

Environment Variables

Getting a Float API Key

1. Log in to your Float account
2. Go to Settings > API > Personal Access Tokens
3. Click Generate New Token
4. Copy the API key
5. Add it to your .env file

📖 Usage Examples

Basic Operations

// List all projects
const projects = await listProjects({});

// Get a specific project
const project = await getProject({ project_id: 12345 });

// Create a new person
const person = await createPerson({
  name: 'John Doe',
  email: 'john@example.com',
  department_id: 1,
});

// Schedule an allocation
const allocation = await createAllocation({
  project_id: 12345,
  people_id: 67890,
  start_date: '2024-01-15',
  end_date: '2024-01-31',
  hours: 8,
});

Advanced Workflows

// Get team utilization report
const utilization = await getPeopleUtilizationReport({
  start_date: '2024-01-01',
  end_date: '2024-12-31',
});

// Bulk create project tasks
const tasks = await bulkCreateProjectTasks({
  project_id: 12345,
  tasks: [
    { name: 'Design Phase', start_date: '2024-01-01' },
    { name: 'Development Phase', start_date: '2024-01-15' },
  ],
});

// Process time off request
await createTimeOff({
  people_ids: [67890],
  timeoff_type_id: 1,
  start_date: '2024-02-01',
  end_date: '2024-02-05',
  status: 1, // Pending approval
});

await approveTimeOff({
  timeoff_id: 123,
  approved_by: 456,
  notes: 'Approved for vacation',
});

🧪 Testing

Running Tests

# Run all tests
npm test

# Run integration tests (requires API key)
npm run test:integration

# Run tests with coverage
npm run test:coverage

# Run specific test suites
npm run test:integration:mock  # Mock API responses
npm run test:integration:real  # Real API calls (use with caution)

Test Configuration

For integration tests with real API calls:

# .env.test
FLOAT_API_KEY=flt_your_test_api_key
TEST_REAL_API=true
TEST_MOCK_MODE=false

🐳 Docker Support

Using Docker

# Build the image
docker build -t float-mcp .

# Run the container
docker run -d \
  --name float-mcp \
  -e FLOAT_API_KEY=your_float_api_key_here \
  -p 3000:3000 \
  float-mcp

Docker Compose

version: '3.8'
services:
  float-mcp:
    build: .
    environment:
      - FLOAT_API_KEY=your_float_api_key_here
      - LOG_LEVEL=info
    ports:
      - '3000:3000'
    restart: unless-stopped

🔍 Troubleshooting

Common Issues

API Key Issues

Error: Unauthorized (401)
# Solution: Check your API key format and validity

Rate Limiting

Error: Too Many Requests (429)
# Solution: The server automatically handles rate limiting with exponential backoff

Connection Issues

Error: Network timeout
# Solution: Check your internet connection and Float API status

Debug Mode

Enable detailed logging:

LOG_LEVEL=debug

This will show all API requests/responses and internal operations.

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

# Clone the repository
git clone https://github.com/asachs01/float-mcp.git
cd float-mcp

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your Float API key

# Run in development mode
npm run dev

Code Quality

# Run linting
npm run lint

# Format code
npm run format

# Type checking
npm run typecheck

📄 Documentation

• - Complete API reference
• - Detailed tool documentation
• - Usage patterns and examples
• - Testing guide
• - Claude Desktop setup

📊 Project Status

• ✅ Complete Float API Coverage - All Float v3 endpoints implemented
• ✅ Production Ready - Full error handling, rate limiting, and logging
• ✅ Well Tested - Comprehensive integration test suite
• ✅ Type Safe - Full TypeScript with Zod validation
• ✅ Docker Ready - Production-ready containerization
• ✅ MCP Compatible - Full Model Context Protocol compliance

🗺️ Roadmap

• Float API v4 Support - When released by Float
• Enhanced Caching - Optional Redis caching layer
• Webhook Support - Real-time Float event notifications
• Bulk Operations - Enhanced bulk import/export tools
• Custom Reports - Advanced reporting and analytics
• Multi-tenant Support - Multiple Float account support

📝 License

This project is licensed under the MIT License - see the file for details.

🙋 Support

• 📖 Documentation: See the directory
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions

🏷️ Tags

float mcp model-context-protocol project-management resource-management time-tracking typescript api-integration claude ai-tools

Built with ❤️ for the Float and MCP communities