search_docs

Instructions

Implementation Reference

• src/tools/doc-tools.ts:49-74 (registration)

  Registration of the 'search_docs' tool with the MCP server using Zod schema for input validation.

  // Register search_docs tool
  server.tool(
    'search_docs',
    'Search for docs in a ClickUp workspace using a query string. Returns matching docs with their metadata.',
    {
      workspace_id: z.string().describe('The ID of the workspace to search in'),
      query: z.string().describe('The search query'),
      cursor: z.string().optional().describe('Cursor for pagination')
    },
    async ({ workspace_id, query, cursor }) => {
      try {
        // Search for docs in the workspace
        const result = await docsClient.searchDocs(workspace_id, { query, cursor });
        
        return {
          content: [{ type: 'text', text: JSON.stringify(result.docs, null, 2) }]
        };
      } catch (error: any) {
        console.error('Error searching docs:', error);
        return {
          content: [{ type: 'text', text: `Error searching docs: ${error.message}` }],
          isError: true
        };
      }
    }
  );

• src/tools/doc-tools.ts:58-73 (handler)

  Handler function that executes the search_docs tool logic: calls docsClient.searchDocs and returns JSON result.

  async ({ workspace_id, query, cursor }) => {
    try {
      // Search for docs in the workspace
      const result = await docsClient.searchDocs(workspace_id, { query, cursor });
      
      return {
        content: [{ type: 'text', text: JSON.stringify(result.docs, null, 2) }]
      };
    } catch (error: any) {
      console.error('Error searching docs:', error);
      return {
        content: [{ type: 'text', text: `Error searching docs: ${error.message}` }],
        isError: true
      };
    }
  }

• src/tools/doc-tools.ts:53-57 (schema)

  Zod schema defining input parameters for search_docs: workspace_id (string), query (string), and optional cursor (string).

  {
    workspace_id: z.string().describe('The ID of the workspace to search in'),
    query: z.string().describe('The search query'),
    cursor: z.string().optional().describe('Cursor for pagination')
  },

• src/clickup-client/docs.ts:29-32 (helper)

  SearchDocsParams interface defining the parameters for the searchDocs API call: query and optional cursor.

  export interface SearchDocsParams {
    query: string;
    cursor?: string;
  }

• src/clickup-client/docs.ts:117-157 (helper)

  searchDocs method on DocsClient that makes the actual HTTP GET request to ClickUp API v2 team docs/search endpoint.

  async searchDocs(workspaceId: string, params: SearchDocsParams): Promise<{ docs: Doc[], next_cursor: string }> {
    // Get the API token directly from the environment variable
    const apiToken = process.env.CLICKUP_API_TOKEN;
    
    try {
      // According to the ClickUp API documentation, the endpoint is:
      // GET /api/v2/team/{team_id}/docs/search
      // where team_id is the workspace ID
      const url = `https://api.clickup.com/api/v2/team/${workspaceId}/docs/search`;
      
      // Use the exact same headers that worked in the successful request
      const headers = {
        'Authorization': apiToken,
        'Accept': 'application/json'
      };
      
      // According to the ClickUp API documentation, this should be a GET request
      // with the parameters as query parameters
      const queryParams: any = {
        doc_name: params.query,
        cursor: params.cursor
      };
      
      // If the query is a space ID, use it as a space_id parameter
      if (params.query.startsWith('space:')) {
        const spaceId = params.query.substring(6);
        queryParams.space_id = spaceId;
        delete queryParams.doc_name;
      }
      
      const response = await axios.get(url, {
        headers,
        params: queryParams
      });
      
      return response.data;
    } catch (error) {
      console.error('Error searching docs:', error);
      throw error;
    }
  }