PulseMCP Server

Instructions

Implementation Reference

• src/index.ts:139-184 (handler)

  The handler function for the 'list_servers' tool. Validates input arguments using isListServersArgs, makes an API call to fetch server list with filters, handles the response by stringifying JSON, and manages errors.

  case "list_servers": {
    if (!isListServersArgs(request.params.arguments)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        "Invalid arguments for list_servers"
      );
    }
  
    try {
      const response = await this.axiosInstance.get<ListServersResponse>(
        "/servers",
        {
          params: {
            query: request.params.arguments.query,
            "integrations[]": request.params.arguments.integrations,
            count_per_page: request.params.arguments.count_per_page,
            offset: request.params.arguments.offset,
          },
        }
      );
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(response.data, null, 2),
          },
        ],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        return {
          content: [
            {
              type: "text",
              text: `API Error: ${
                error.response?.data?.error?.message ?? error.message
              }`,
            },
          ],
          isError: true,
        };
      }
      throw error;
    }
  }

• src/index.ts:14-41 (schema)

  TypeScript interfaces defining the input arguments (ListServersArgs) and response structure (ListServersResponse) for the list_servers tool.

  interface ListServersArgs {
    query?: string;
    integrations?: string[];
    count_per_page?: number;
    offset?: number;
  }
  
  interface ListServersResponse {
    servers: Array<{
      name: string;
      url: string;
      external_url?: string;
      short_description?: string;
      source_code_url?: string;
      github_stars?: number;
      package_registry?: string;
      package_name?: string;
      package_download_count?: number;
      EXPERIMENTAL_ai_generated_description?: string;
      integrations: Array<{
        name: string;
        slug: string;
        url: string;
      }>;
    }>;
    next?: string;
    total_count: number;
  }

• src/index.ts:97-125 (registration)

  Registration of the 'list_servers' tool in the ListToolsRequest handler, including name, description, and JSON input schema.

  {
    name: "list_servers",
    description: "List MCP servers with optional filtering",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search term to filter servers",
        },
        integrations: {
          type: "array",
          items: {
            type: "string",
          },
          description: "Filter by integration slugs",
        },
        count_per_page: {
          type: "number",
          description: "Number of results per page (maximum: 5000)",
          maximum: 5000,
        },
        offset: {
          type: "number",
          description: "Number of results to skip for pagination",
        },
      },
    },
  },

• src/index.ts:51-61 (schema)

  Type guard function for validating ListServersArgs input in the handler.

  const isListServersArgs = (args: any): args is ListServersArgs => {
    if (typeof args !== "object" || args === null) return false;
  
    if ("query" in args && typeof args.query !== "string") return false;
    if ("integrations" in args && !Array.isArray(args.integrations)) return false;
    if ("count_per_page" in args && typeof args.count_per_page !== "number")
      return false;
    if ("offset" in args && typeof args.offset !== "number") return false;
  
    return true;
  };