Harvest MCP Server

Instructions

Implementation Reference

• src/harvest-client.ts:122-124 (handler)

  Core handler function that executes the Harvest API request to retrieve details of a specific project by ID.

  async getProject(id: string) {
    return this.makeRequest(`/projects/${id}`);
  }

• src/index.ts:187-196 (handler)

  MCP tool call dispatcher case that invokes the HarvestClient.getProject method and formats the JSON response.

  case 'harvest_get_project':
    const project = await harvestClient.getProject(typedArgs.id as string);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(project, null, 2),
        },
      ],
    };

• src/tools.ts:117-127 (schema)

  Defines the tool's metadata, description, and input schema requiring a 'id' parameter of type string.

  {
    name: 'harvest_get_project',
    description: 'Get details of a specific project. Use about {"tool": "harvest_get_project"} for detailed usage examples.',
    inputSchema: {
      type: 'object',
      properties: {
        id: { type: 'string', description: 'Project ID' }
      },
      required: ['id']
    }
  },

• src/index.ts:69-73 (registration)

  Registers the list tools handler which returns the tools array including harvest_get_project schema.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: tools,
    };
  });

• src/harvest-client.ts:27-57 (helper)

  Generic HTTP request helper used by getProject to make authenticated API calls to Harvest.

  private async makeRequest(endpoint: string, options: RequestInit = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    
    const response = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.accessToken}`,
        'Harvest-Account-ID': this.accountId,
        'User-Agent': this.userAgent,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });
  
    if (!response.ok) {
      let errorMessage = `Harvest API error: ${response.status} ${response.statusText}`;
      
      try {
        const errorBody = await response.json() as any;
        if (errorBody.message) {
          errorMessage += ` - ${errorBody.message}`;
        }
      } catch {
        // If we can't parse the error response, use the basic error message
      }
      
      throw new Error(errorMessage);
    }
  
    return response.json();
  }