Social Search MCP

Instructions

Implementation Reference

• src/social_search_mcp/server.py:176-228 (handler)

  The handle_call_tool function processes the 'search_social' tool call, constructs a domain-limited query, selects a search provider (SearXNG, Serper, or Google), and formats the results.

  @server.call_tool()
  async def handle_call_tool(
      name: str, arguments: dict | None
  ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
      if name != "search_social":
          raise ValueError(f"Unknown tool: {name}")
  
      if not arguments or "query" not in arguments:
          raise ValueError("Missing required 'query' argument")
  
      query = arguments.get("query")
      requested_platforms = arguments.get("platforms", [])
      max_results = min(arguments.get("max_results", 10), 30)
      time_filter = arguments.get("time_filter")
      gl = arguments.get("gl")
      hl = arguments.get("hl")
  
      domains = []
      if requested_platforms:
          for p in requested_platforms:
              p_lower = p.lower()
              if p_lower in PLATFORMS:
                  domains.append(PLATFORMS[p_lower])
              elif "." in p_lower:
                  domains.append(p_lower)
      else:
          domains = list(PLATFORMS.values())
  
      site_query = " OR ".join([f"site:{d}" for d in domains])
      final_query = f"{query} ({site_query})".strip()
  
      provider = os.environ.get("SEARCH_PROVIDER", "searxng").lower()
      
      if provider == "searxng":
          results = search_searxng(final_query, max_results=max_results, time_filter=time_filter)
      elif provider == "serper":
          results = search_serper(final_query, max_results=max_results, time_filter=time_filter, gl=gl, hl=hl)
      elif provider == "google":
          results = search_google(final_query, max_results=max_results, time_filter=time_filter)
      else:
          return [types.TextContent(type="text", text=f"ERROR: Unknown SEARCH_PROVIDER '{provider}'. Use 'searxng', 'serper', or 'google'.")]
  
      if isinstance(results, str):  # Error message returned
          return [types.TextContent(type="text", text=results)]
          
      if not results:
          return [types.TextContent(type="text", text=f"No results found from provider '{provider}'.")]
  
      formatted_results = "\\n\\n".join(
          [f"Title: {r.get('title')}\\nURL: {r.get('url')}\\nSnippet: {r.get('snippet')}" for r in results]
      )
  
      return [types.TextContent(type="text", text=formatted_results)]

• src/social_search_mcp/server.py:136-174 (schema)

  Tool registration and definition of input schema for the 'search_social' tool.

  @server.list_tools()
  async def handle_list_tools() -> list[types.Tool]:
      return [
          types.Tool(
              name="search_social",
              description="Perform a web search focused ONLY on specific social media platforms.",
              inputSchema={
                  "type": "object",
                  "properties": {
                      "query": {
                          "type": "string",
                          "description": "The search query (e.g. 'rent listings', 'used bike')"
                      },
                      "platforms": {
                          "type": "array",
                          "items": {"type": "string"},
                          "description": "List of platforms to search. Options: facebook, instagram, twitter, reddit, linkedin, snapchat, tiktok, pinterest. Defaults to searching all if omitted."
                      },
                      "max_results": {
                          "type": "integer",
                          "description": "Max number of results to retrieve (default: 10, max: 30)"
                      },
                      "time_filter": {
                          "type": "string",
                          "description": "Optional time filter. Options: 'day', 'week', 'month', 'year'. Leave empty for relevance sorting."
                      },
                      "gl": {
                          "type": "string",
                          "description": "Optional geolocation code (e.g. 'in' for India, 'us' for USA)."
                      },
                      "hl": {
                          "type": "string",
                          "description": "Optional language code (e.g. 'hi' for Hindi, 'en' for English)."
                      }
                  },
                  "required": ["query"]
              }
          )
      ]