search_public_apis
Search for free public APIs that match your query using semantic search over names and descriptions.
Instructions
Search for free public APIs that match the input query string.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/public_apis_mcp/tools.py:13-32 (handler)The main handler function for the 'search_public_apis' tool. It loads or builds an embedding index, embeds the query, searches the index for the top-k matches, and returns SearchResult objects.
def search_public_apis(query: str, limit: int = 5) -> list[SearchResult]: """Search for free public APIs that match the input query string.""" idx = ensure_index() qvec, _ = embed_query(query, model_id=idx.model_id) top = idx.search(qvec, top_k=max(1, min(50, int(limit)))) # limit to 50 items, by_id = load_catalog_indexed() results: list[SearchResult] = [] for api_id, score in top: item = by_id.get(api_id) if not item: continue results.append( SearchResult( id=item.id, name=item.api, score=float(score), snippet=item.description, ) ) return results - src/public_apis_mcp/types.py:17-22 (schema)Pydantic model defining the output schema for search results returned by search_public_apis.
class SearchResult(BaseModel): id: str name: str score: float snippet: str - src/public_apis_mcp/tools.py:11-13 (registration)Registration of the tool via the @mcp.tool decorator in the register_tools function, which is called from server.py.
def register_tools(mcp: FastMCP) -> None: @mcp.tool def search_public_apis(query: str, limit: int = 5) -> list[SearchResult]: - The EmbeddingIndex.search method performs cosine similarity search (via dot product on L2-normalized vectors) used by search_public_apis.
def search(self, query_vector: np.ndarray, top_k: int) -> list[tuple[str, float]]: # query_vector expected shape (D,), normalized scores = self.vectors @ query_vector.astype(np.float32) idx = np.argsort(-scores)[:top_k] return [(self.ids[i], float(scores[i])) for i in idx] - Helper function that embeds the query string into a normalized vector for similarity search.
def embed_query(text: str, model_id: Optional[str] = None) -> tuple[np.ndarray, str]: vecs, resolved = embed_texts([text], model_id=model_id) q = vecs[0].astype(np.float32) q = q / (np.linalg.norm(q) + 1e-12) return q, resolved