search_companies

Instructions

Implementation Reference

• src/tools.py:71-97 (handler)

  The MCP tool handler for search_companies. It fetches all companies (paginated) via the client, then applies client-side filtering by sector, city, and/or name_contains.

  @mcp.tool
  async def search_companies(
      name_contains: str | None = None,
      sector: CompanySector | None = None,
      city: str | None = None,
      page: int = 1,
      per_page: int = 100,
  ) -> list[Company]:
      """Search companies by various criteria.
  
      Args:
          name_contains: Filter companies containing this text in their name
          sector: Filter companies by sector
          city: Filter companies by city
          page: Page number for pagination (default: 1)
          per_page: Results per page (default: 100, max: 100)
      """
      async with StandardMetrics() as client:
          results = (await client.get_companies(page=page, page_size=per_page)).results
          if sector:
              results = [c for c in results if c.sector == sector]
          if city:
              results = [c for c in results if c.city == city]
          if name_contains:
              results = [c for c in results if name_contains.lower() in c.name.lower()]
          return results

• src/server.py:74-78 (registration)

  The MCP server instance is created in server.py and tools are registered by importing all from src.tools, which includes the @mcp.tool decorated search_companies function.

  mcp = fastmcp.FastMCP[Any](
      "smx-mcp",
      instructions=_MCP_INSTRUCTIONS,
  )
  from src.tools import *  # noqa: F403 - need to register all of the tools

• src/_types.py:24-46 (schema)

  The CompanySector enum type used for the 'sector' parameter in search_companies for input validation.

  class CompanySector(enum.StrEnum):
      B2B_SOFTWARE = "B2B Software"
      DIRECT_TO_CONSUMER = "Direct-to-consumer"
      CONSUMER_INTERNET_MOBILE = "Consumer Internet/Mobile"
      AR_VR = "AR/VR"
      LIFE_SCIENCES = "Life Sciences"
      HEALTH_TECHNOLOGY = "Health Technology"
      HARDWARE = "Hardware"
      EDTECH = "Edtech"
      MEDIA = "Media"
      FINTECH = "Fintech"
      GOVTECH = "Govtech"
      CRYPTO_BLOCKCHAIN = "Crypto/blockchain"
      OTHER = "Other"
      LOGISTICS = "Logistics"
      INSURTECH = "Insurtech"
      SOFTWARE_INFRASTRUCTURE = "Software Infrastructure"
      SECURITY = "Security"
      ARTIFICIAL_INTELLIGENCE = "Artificial Intelligence"
      AG_TECH = "AG-Tech"
      SUSTAINABILITY = "Sustainability"
      GAMING = "Gaming"

• src/_types.py:82-100 (schema)

  The Company Pydantic model that defines the structure of company objects returned by search_companies.

  class Company(pydantic.BaseModel):
      id: str
      name: str
      slug: str | None = None
      description: str | None = None
      city: str | None = None
      sector: CompanySector | None = None
      firm_sector: str | None = None
      fiscal_year_end: str | None = pydantic.Field(
          None,
          description="MM/DD format",
      )
      website: str | None = None
      logo_url: str | None = None
      status: str | None = None
      investment_lead_id: str | None = None
      invested_fund_ids: list[str] | None = None
      unique_ref: str | None = None

• src/_client.py:120-134 (helper)

  The StandardMetrics.get_companies() method that search_companies calls internally to fetch the list of companies from the API.

  async def get_companies(
      self,
      *,
      page: int = 1,
      page_size: int = 100,
      ids: list[str] | None = None,
  ) -> PaginatedCompanies:
      """Get all companies associated with your firm."""
      params: dict[str, Any] = {"page": page, "page_size": page_size}
      if ids:
          for company_id in ids:
              params.setdefault("ids[]", []).append(company_id)
      response = await self._request("GET", "v1/companies/", params=params)
      return PaginatedCompanies.model_validate(response)