Glean MCP Server

Instructions

    Example request:

    {
        "query": "Find people named John Doe",
        "filters": {
            "department": "Engineering",
            "city": "San Francisco"
        },
        "pageSize": 10
    }

    

Implementation Reference

• packages/local-mcp-server/src/tools/people_profile_search.ts:129-139 (handler)

  The core handler function that performs the people profile search by mapping input parameters to Glean API request and calling the entities.list endpoint.

  export async function peopleProfileSearch(
    params: ToolPeopleProfileSearchRequest,
  ) {
    const mappedParams = convertToAPIEntitiesRequest(params);
    const parsedParams = ListEntitiesRequestSchema.parse(
      mappedParams,
    ) as ListEntitiesRequest;
    const client = await getClient();
  
    return await client.entities.list(parsedParams);
  }

• packages/local-mcp-server/src/tools/people_profile_search.ts:39-80 (schema)

  Zod schema defining the input parameters for the people_profile_search tool, including query, filters, and pageSize with validation.

  export const ToolPeopleProfileSearchSchema = z
    .object({
      query: z
        .string()
        .describe('Free-text query to search people by name, title, etc.')
        .optional(),
  
      filters: z
        .record(z.string(), z.string())
        .refine(
          (val) =>
            Object.keys(val).every((key) =>
              PEOPLE_FACETS_VALUES.includes(key as any),
            ),
          {
            message:
              'Invalid filter key. Must be one of: ' +
              PEOPLE_FACETS_VALUES.join(', '),
          },
        )
        .describe(
          'Allowed facet fields: email, first_name, last_name, manager_email, department, title, location, city, country, state, region, business_unit, team, team_id, nickname, preferred_name, roletype, reportsto, startafter, startbefore, industry, has, from. Provide as { "facet": "value" }.',
        )
        .optional(),
  
      pageSize: z
        .number()
        .int()
        .min(1)
        .max(100)
        .describe(
          'Hint to the server for how many people to return (1-100, default 10).',
        )
        .optional(),
    })
    .refine(
      (val) => val.query || (val.filters && Object.keys(val.filters).length > 0),
      {
        message: 'At least one of "query" or "filters" must be provided.',
        path: [],
      },
    );

• packages/local-mcp-server/src/server.ts:160-171 (registration)

  Registration and dispatch logic in the callToolHandler switch case that validates input, calls the handler, formats response, and returns MCP content.

  case TOOL_NAMES.peopleProfileSearch: {
    const args = peopleProfileSearch.ToolPeopleProfileSearchSchema.parse(
      request.params.arguments,
    );
    const result = await peopleProfileSearch.peopleProfileSearch(args);
    const formattedResults = peopleProfileSearch.formatResponse(result);
  
    return {
      content: [{ type: 'text', text: formattedResults }],
      isError: false,
    };
  }

• packages/local-mcp-server/src/server.ts:87-106 (registration)

  Tool registration in listToolsHandler, providing name, description, and input schema for discovery.

  {
    name: TOOL_NAMES.peopleProfileSearch,
    description: `Search for people profiles in the company
  
    Example request:
  
    {
        "query": "Find people named John Doe",
        "filters": {
            "department": "Engineering",
            "city": "San Francisco"
        },
        "pageSize": 10
    }
  
    `,
    inputSchema: z.toJSONSchema(
      peopleProfileSearch.ToolPeopleProfileSearchSchema,
    ),
  },

• packages/local-mcp-server/src/tools/people_profile_search.ts:147-193 (helper)

  Helper function to format raw Glean API search results into a readable text summary for MCP response.

  export function formatResponse(searchResults: any): string {
    if (
      !searchResults ||
      !Array.isArray(searchResults.results) ||
      searchResults.results.length === 0
    ) {
      return 'No matching people found.';
    }
  
    const formatted = searchResults.results
      .map((person: any, index: number) => {
        const metadata = person.metadata ?? {};
  
        const displayName = metadata.preferredName || person.name || 'Unnamed';
  
        const title = metadata.title || 'Unknown title';
  
        const department = metadata.department || 'Unknown department';
  
        const location =
          metadata.location ||
          metadata.structuredLocation?.city ||
          metadata.structuredLocation?.country ||
          'Unknown location';
  
        const email =
          metadata.email || metadata.aliasEmails?.[0] || 'Unknown email';
  
        // Show first team affiliation if present for additional context
        const primaryTeam =
          Array.isArray(metadata.teams) && metadata.teams.length > 0
            ? metadata.teams[0].name
            : undefined;
  
        const teamSuffix = primaryTeam ? ` [${primaryTeam}]` : '';
  
        return `${index + 1}. ${displayName} – ${title}${teamSuffix}, ${department} (${location}) • ${email}`;
      })
      .join('\n');
  
    const total =
      typeof searchResults.totalCount === 'number'
        ? searchResults.totalCount
        : searchResults.results.length;
  
    return `Found ${total} people:\n\n${formatted}`;
  }