Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/projects.ts:107-139 (handler)

  Handler function that executes the basecamp_get_project tool: initializes client, fetches project by ID, returns formatted JSON or error message.

  async (params) => {
    try {
      const client = await initializeBasecampClient();
  
      const response = await client.projects.get({
        params: { projectId: params.project_id },
      });
  
      if (response.status !== 200 || !response.body) {
        throw new Error(`Failed to fetch project: ${response.status}`);
      }
  
      const project = response.body;
  
      const jsonData = {
        id: project.id,
        name: project.name,
        description: project.description || "",
        created_at: project.created_at,
        updated_at: project.updated_at,
        url: project.app_url,
        dock: project.dock || [],
      };
  
      return {
        content: [{ type: "text", text: JSON.stringify(jsonData, null, 2) }],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: handleBasecampError(error) }],
      };
    }
  },

• src/tools/projects.ts:88-140 (registration)

  Registration of the basecamp_get_project tool via server.registerTool, including title, description, input schema, annotations, and handler reference.

    server.registerTool(
      "basecamp_get_project",
      {
        title: "Get Basecamp Project Details",
        description: `Fetch detailed information about a specific Basecamp project. This tool retrieves complete project details including name, description, dock configuration, and metadata.
  
  Examples:
    - Use when: "Get details for project 12345"
    - Use when: Need full project information including dock configuration`,
        inputSchema: {
          project_id: BasecampIdSchema.describe("Project ID to retrieve"),
        },
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      async (params) => {
        try {
          const client = await initializeBasecampClient();
  
          const response = await client.projects.get({
            params: { projectId: params.project_id },
          });
  
          if (response.status !== 200 || !response.body) {
            throw new Error(`Failed to fetch project: ${response.status}`);
          }
  
          const project = response.body;
  
          const jsonData = {
            id: project.id,
            name: project.name,
            description: project.description || "",
            created_at: project.created_at,
            updated_at: project.updated_at,
            url: project.app_url,
            dock: project.dock || [],
          };
  
          return {
            content: [{ type: "text", text: JSON.stringify(jsonData, null, 2) }],
          };
        } catch (error) {
          return {
            content: [{ type: "text", text: handleBasecampError(error) }],
          };
        }
      },
    );

• src/schemas/common.ts:10-12 (schema)

  Zod schema for Basecamp ID (number), used in the tool's project_id input parameter.

  export const BasecampIdSchema = z
    .number()
    .describe("Basecamp resource identifier");

• src/index.ts:61-61 (registration)

  Top-level call to registerProjectTools which includes basecamp_get_project among other project tools.

  registerProjectTools(server);