Pursuit MCP

Instructions

Implementation Reference

• src/pursuit_mcp/server.py:6-23 (handler)

  The main handler for the 'search_pursuit' tool. Decorated with @mcp.tool for registration. Orchestrates the search by calling helpers and returns JSON-formatted results.
  @mcp.tool async def search_pursuit(query: str, limit: int = 10) -> str: """Search Pursuit for PureScript functions, types, and documentation. Args: query: Search query (function name, type signature, or keyword) limit: Maximum number of results to return (default: 10) Returns: Formatted search results from Pursuit as JSON string """ import json from .format import format from .search import search results = await search(query, limit=limit) return json.dumps(format(results), ensure_ascii=False)
• src/pursuit_mcp/search.py:12-37 (helper)

  Helper function that performs the actual HTTP search request to the Pursuit API and returns raw results.
  async def search( query: str, limit: int = 10, timeout: float = DEFAULT_TIMEOUT ) -> list[PursuitResult]: """Search Pursuit for PureScript functions, types, and documentation. Args: query: Search query (function name, type signature, or keyword) limit: Maximum number of results to return (default: 10) timeout: Request timeout in seconds Returns: List of search results from Pursuit (limited to `limit` results) Raises: httpx.HTTPError: If the request fails """ async with httpx.AsyncClient() as client: response = await client.get( BASE_URL, params={"q": query}, headers={"Accept": "application/json"}, timeout=timeout, ) response.raise_for_status() results = response.json() return results[:limit]
• src/pursuit_mcp/format.py:6-64 (helper)

  Helper function that formats the raw Pursuit results into a display-friendly dictionary structure.
  def format(results: list[PursuitResult]) -> FormatOutput: """Format Pursuit search results as structured dict. Args: results: List of Pursuit search results Returns: Formatted results dictionary with results list and count """ if not results: return {"results": [], "count": 0} formatted_results: list[FormattedResult] = [] for result in results: formatted_result: FormattedResult = {} # Package and version information if "package" in result: formatted_result["package"] = result["package"] if "version" in result: formatted_result["version"] = result["version"] # Documentation text if "text" in result: formatted_result["docs"] = result["text"] # Result info (package/module/declaration) if "info" in result: info = result["info"] if isinstance(info, dict) and "type" in info: result_type = info["type"] formatted_result["type"] = result_type # Extract type-specific information if result_type == "declaration": # For declarations, include module, title, and typeText if "module" in info: formatted_result["module"] = info["module"] if "title" in info: formatted_result["title"] = info["title"] if "typeText" in info: formatted_result["typeText"] = info["typeText"] elif result_type == "module": # For modules, include module name if "module" in info: formatted_result["module"] = info["module"] elif result_type == "package": # For packages, include deprecated status if "deprecated" in info: formatted_result["deprecated"] = info["deprecated"] # URL to the result if "url" in result: formatted_result["url"] = result["url"] formatted_results.append(formatted_result) return {"results": formatted_results, "count": len(results)}
• src/pursuit_mcp/types.py:1-101 (schema)

  Type definitions (TypedDicts) for Pursuit search results, used for type safety and structuring the output data.
  """Type definitions for Pursuit API responses.""" from typing import TypedDict, Literal, Union class PackageResultContents(TypedDict): """Contents of a PackageResult. The boolean indicates whether the package is deprecated. """ deprecated: bool class ModuleResultContents(TypedDict): """Contents of a ModuleResult. Contains the module name. """ module_name: str class DeclarationResultContents(TypedDict): """Contents of a DeclarationResult. Contains information about a function, type, or value declaration. """ namespace: str module_name: str title: str type_signature: str | None class PackageResult(TypedDict): """A Pursuit search result for a package.""" tag: Literal["PackageResult"] contents: bool # Deprecation status class ModuleResult(TypedDict): """A Pursuit search result for a module.""" tag: Literal["ModuleResult"] contents: str # Module name class DeclarationResult(TypedDict): """A Pursuit search result for a declaration (function, type, etc.).""" tag: Literal["DeclarationResult"] contents: list[str | None] # [namespace, module_name, title, type_signature] # Union type for all possible result info types PursuitResultInfo = Union[PackageResult, ModuleResult, DeclarationResult] class PursuitResult(TypedDict): """A single Pursuit search result. Represents a search result from the Pursuit API, which can be a package, module, or declaration (function, type, value, etc.). """ package: str version: str markup: str # HTML-formatted documentation text: str # Plain text documentation info: PursuitResultInfo url: str # Direct link to the documentation class FormattedResult(TypedDict, total=False): """A formatted Pursuit search result. All fields are optional as the formatter only includes fields present in the original result. """ package: str version: str docs: str # Plain text documentation type: str # Result type (package, module, declaration) url: str # Declaration-specific fields module: str # Module name (for declaration and module types) title: str # Function/type name (for declaration types) typeText: str | None # Type signature (for declaration types) # Package-specific fields deprecated: bool # Deprecation status (for package types) class FormatOutput(TypedDict): """Output format for formatted search results.""" results: list[FormattedResult] count: int