Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/projects.ts:39-84 (handler)

  Handler function for basecamp_list_projects tool: initializes Basecamp client, fetches all projects using pagination, applies optional filter, returns JSON list of project details or error message.

  async (params) => {
    try {
      const client = await initializeBasecampClient();
  
      // Fetch projects with pagination
      const projects = await asyncPagedToArray({
        fetchPage: client.projects.list,
        request: {
          query: {},
        },
      });
  
      // Apply filter if provided
      let filteredProjects = projects;
      if (params.filter) {
        const regex = new RegExp(params.filter, "i");
        filteredProjects = projects.filter(
          (p) => regex.test(p.name) || regex.test(p.description || ""),
        );
      }
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              filteredProjects.map((p) => ({
                id: p.id,
                name: p.name,
                description: p.description || "",
                created_at: p.created_at,
                updated_at: p.updated_at,
                url: p.app_url,
              })),
              null,
              2,
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: handleBasecampError(error) }],
      };
    }
  },

• src/tools/projects.ts:24-31 (schema)

  Input schema definition using Zod: optional 'filter' string for regex filtering projects.

  inputSchema: {
    filter: z
      .string()
      .optional()
      .describe(
        "Optional regular expression to filter projects by name or description",
      ),
  },

• src/tools/projects.ts:19-85 (registration)

  Tool registration call for 'basecamp_list_projects' including name, title, description, inputSchema, annotations, and handler function.

  server.registerTool(
    "basecamp_list_projects",
    {
      title: "List Basecamp Projects",
      description: `List all projects visible to the authenticated user in a Basecamp account. This tool returns active projects with their IDs, names, descriptions, and metadata. Use this to discover project/bucket IDs needed for accessing messages, todos, and other resources.`,
      inputSchema: {
        filter: z
          .string()
          .optional()
          .describe(
            "Optional regular expression to filter projects by name or description",
          ),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
    },
    async (params) => {
      try {
        const client = await initializeBasecampClient();
  
        // Fetch projects with pagination
        const projects = await asyncPagedToArray({
          fetchPage: client.projects.list,
          request: {
            query: {},
          },
        });
  
        // Apply filter if provided
        let filteredProjects = projects;
        if (params.filter) {
          const regex = new RegExp(params.filter, "i");
          filteredProjects = projects.filter(
            (p) => regex.test(p.name) || regex.test(p.description || ""),
          );
        }
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                filteredProjects.map((p) => ({
                  id: p.id,
                  name: p.name,
                  description: p.description || "",
                  created_at: p.created_at,
                  updated_at: p.updated_at,
                  url: p.app_url,
                })),
                null,
                2,
              ),
            },
          ],
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: handleBasecampError(error) }],
        };
      }
    },
  );