Basecamp MCP Server

Instructions

Implementation Reference

• src/lib/basecamp-client.ts:371-377 (handler)

  Core handler function in BasecampClient that retrieves uploads from a project or specific vault using the Basecamp API.

  async getUploads(projectId: string, vaultId?: string): Promise<Upload[]> {
    const endpoint = vaultId 
      ? `/buckets/${projectId}/vaults/${vaultId}/uploads.json`
      : `/buckets/${projectId}/uploads.json`;
    const response = await this.client.get(endpoint);
    return response.data;
  }

• src/index.ts:461-472 (registration)

  Registers the 'get_uploads' tool in the MCP server's ListTools response, defining its name, description, and input schema. Note: No corresponding case handler in CallToolRequestSchema yet.

  {
    name: 'get_uploads',
    description: 'List uploads in a project or vault',
    inputSchema: {
      type: 'object',
      properties: {
        project_id: { type: 'string', description: 'Project ID' },
        vault_id: { type: 'string', description: 'Optional vault ID to limit to specific vault' },
      },
      required: ['project_id'],
    },
  },

• src/types/basecamp.ts:157-377 (schema)

  Type definition for Upload objects returned by the getUploads handler.

  export interface Upload {
    id: string;
    filename: string;
    title?: string;
    description?: string;
    byte_size: number;
    content_type: string;
    created_at: string;
    creator: Person;
    download_url: string;
    project?: ProjectInfo;
  }
  
  export interface Webhook {
    id: string;
    payload_url: string;
    types: string[];
    created_at: string;
    updated_at: string;
  }
  
  export interface DailyCheckIn {
    id: string;
    title: string;
    created_at: string;
    updated_at: string;
    creator: Person;
  }
  
  export interface QuestionAnswer {
    id: string;
    content: string;
    created_at: string;
    creator: Person;
  }
  
  export interface SearchResults {
    projects?: BasecampProject[];
    todos?: Todo[];
    messages?: Message[];
    campfire_lines?: CampfireLine[];
    uploads?: Upload[];
  }
  
  export interface APIResponse<T = any> {
    status: 'success' | 'error';
    data?: T;
    error?: string;
    message?: string;
  }
  
  export interface MCPToolResult {
    status: 'success' | 'error';
    [key: string]: any;
  }
  
  export type AuthMode = 'basic' | 'oauth';

• src/types/basecamp.ts:157-168 (helper)

  Interface defining the structure of upload data.

  export interface Upload {
    id: string;
    filename: string;
    title?: string;
    description?: string;
    byte_size: number;
    content_type: string;
    created_at: string;
    creator: Person;
    download_url: string;
    project?: ProjectInfo;
  }