Usage Guide¶

// Example: Custom dashboard showing today's total
const todayData = await readResource("early://time-entries/today");
const entries = JSON.parse(todayData).entries;
const totalMinutes = entries.reduce((sum, entry) => sum + entry.duration, 0);

// Example: Weekly summary for status meetings
const weekData = await readResource("early://time-entries/week");
const weekSummary = processWeeklyData(JSON.parse(weekData));

// Example: Populate project dropdown
const activities = await readResource("early://activities/active");
const activeProjects = JSON.parse(activities).activities;

// Example: Simple time tracking widget
class EarlyTimeWidget {
  async startTimer(projectName) {
    const activities = await this.mcpClient.callTool('list_activities');
    const project = activities.find(a => a.name.includes(projectName));

    if (project) {
      await this.mcpClient.callTool('start_timer', {
        projectId: project.id,
        description: `Working on ${projectName}`
      });
    }
  }

  async stopTimer() {
    return await this.mcpClient.callTool('stop_timer');
  }
}

// Example: Generate weekly report
async function generateWeeklyReport() {
  const entries = await mcpClient.callTool('get_time_entries', {
    startDate: getWeekStart(),
    endDate: getWeekEnd()
  });

  return processTimeEntries(entries);
}

// Efficient: Get all needed data first
const [activities, todayEntries] = await Promise.all([
  mcpClient.callTool('list_activities'),
  mcpClient.callTool('get_time_entries')
]);

// Then use the data for multiple operations

// Cache activities list (changes infrequently)
class EarlyCache {
  constructor(mcpClient) {
    this.mcpClient = mcpClient;
    this.activitiesCache = null;
    this.cacheExpiry = null;
  }

  async getActivities() {
    if (!this.activitiesCache || Date.now() > this.cacheExpiry) {
      this.activitiesCache = await this.mcpClient.callTool('list_activities');
      this.cacheExpiry = Date.now() + (5 * 60 * 1000); // 5 minutes
    }
    return this.activitiesCache;
  }
}

async function callWithRetry(toolName, args, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await mcpClient.callTool(toolName, args);
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      // Exponential backoff
      await sleep(1000 * Math.pow(2, i));
    }
  }
}

async function getTimeEntries(fallbackToCache = true) {
  try {
    return await mcpClient.callTool('get_time_entries');
  } catch (error) {
    if (fallbackToCache && cachedEntries) {
      console.warn('Using cached time entries due to API error');
      return cachedEntries;
    }
    throw error;
  }
}

// Optional: Restrict network access
const allowedHosts = ['api.early.app'];

if (!allowedHosts.includes(new URL(apiUrl).hostname)) {
  throw new Error('Unauthorized API endpoint');
}

// Example: Health check endpoint
async function healthCheck() {
  try {
    const activities = await mcpClient.callTool('list_activities');
    return {
      status: 'healthy',
      timestamp: new Date().toISOString(),
      activitiesCount: activities.length
    };
  } catch (error) {
    return {
      status: 'unhealthy',
      error: error.message,
      timestamp: new Date().toISOString()
    };
  }
}

class UsageTracker {
  constructor() {
    this.callCounts = {};
    this.errorCounts = {};
  }

  recordCall(toolName) {
    this.callCounts[toolName] = (this.callCounts[toolName] || 0) + 1;
  }

  recordError(toolName, error) {
    this.errorCounts[toolName] = (this.errorCounts[toolName] || 0) + 1;
  }

  generateReport() {
    return {
      totalCalls: Object.values(this.callCounts).reduce((a, b) => a + b, 0),
      mostUsedTool: Object.keys(this.callCounts).sort((a, b) => 
        this.callCounts[b] - this.callCounts[a])[0],
      errorRate: Object.values(this.errorCounts).reduce((a, b) => a + b, 0) /
                 Object.values(this.callCounts).reduce((a, b) => a + b, 0)
    };
  }
}

// tests/custom-integration.test.ts
describe('Custom Integration', () => {
  it('should handle custom workflow', async () => {
    const mockClient = new MockEarlyApiClient();
    const result = await handleCustomWorkflow(mockClient, testArgs);

    expect(result).toBeDefined();
    expect(mockClient.callCount).toBe(3);
  });
});

// tests/integration.test.ts
describe('End-to-End Integration', () => {
  it('should complete full workflow', async () => {
    // Test complete user workflow
    const activities = await mcpServer.callTool('list_activities');
    const timer = await mcpServer.callTool('start_timer', {
      projectId: activities[0].id
    });
    // ... continue workflow
  });
});