FreeAgent MCP Server

Instructions

Implementation Reference

• src/index.ts:206-212 (handler)

  MCP tool handler for 'create_timeslip': validates input attributes and delegates to FreeAgentClient.createTimeslip, returning the created timeslip as JSON.

  case 'create_timeslip': {
    const attributes = validateTimeslipAttributes(request.params.arguments);
    const timeslip = await this.client.createTimeslip(attributes);
    return {
      content: [{ type: 'text', text: JSON.stringify(timeslip, null, 2) }]
    };
  }

• src/index.ts:117-132 (registration)

  Registers the 'create_timeslip' tool in the MCP server's list_tools response, including name, description, and JSON input schema.

  {
    name: 'create_timeslip',
    description: 'Create a new timeslip',
    inputSchema: {
      type: 'object',
      properties: {
        task: { type: 'string', description: 'Task URL' },
        user: { type: 'string', description: 'User URL' },
        project: { type: 'string', description: 'Project URL' },
        dated_on: { type: 'string', description: 'Date (YYYY-MM-DD)' },
        hours: { type: 'string', description: 'Hours worked (e.g. "1.5")' },
        comment: { type: 'string', description: 'Optional comment' }
      },
      required: ['task', 'user', 'project', 'dated_on', 'hours']
    }
  },

• src/index.ts:22-45 (schema)

  Input validation function for create_timeslip parameters, ensuring required fields are present and casting to TimeslipAttributes type.

  function validateTimeslipAttributes(data: unknown): TimeslipAttributes {
    if (typeof data !== 'object' || !data) {
      throw new Error('Invalid timeslip data: must be an object');
    }
  
    const attrs = data as Record<string, unknown>;
  
    if (typeof attrs.task !== 'string' ||
      typeof attrs.user !== 'string' ||
      typeof attrs.project !== 'string' ||
      typeof attrs.dated_on !== 'string' ||
      typeof attrs.hours !== 'string') {
      throw new Error('Invalid timeslip data: missing required fields');
    }
  
    return {
      task: attrs.task,
      user: attrs.user,
      project: attrs.project,
      dated_on: attrs.dated_on,
      hours: attrs.hours,
      comment: attrs.comment as string | undefined
    };
  }

• src/types.ts:1-13 (schema)

  TypeScript interface defining the structure of TimeslipAttributes used for create_timeslip input.

  export interface TimeslipAttributes {
      url?: string;
      task: string;
      user: string;
      project: string;
      dated_on: string;
      hours: string;
      comment?: string;
      billed_on_invoice?: string;
      created_at?: string;
      updated_at?: string;
      timer?: TimerAttributes;
  }

• src/freeagent-client.ts:84-95 (helper)

  FreeAgentClient method that performs the actual API POST request to create a timeslip in FreeAgent.

  async createTimeslip(timeslip: TimeslipAttributes): Promise<Timeslip> {
      try {
          console.error('[API] Creating timeslip:', timeslip);
          const response = await this.axiosInstance.post<TimeslipResponse>('/timeslips', {
              timeslip
          });
          return response.data.timeslip;
      } catch (error) {
          console.error('[API] Failed to create timeslip:', error);
          throw error;
      }
  }