Pursuit MCP

Instructions

Implementation Reference

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

  The tool handler for 'search_pursuit', decorated with @mcp.tool. It imports helpers, calls search and format, and returns JSON string of results. This is the primary entrypoint for the tool.
  @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 executes the actual HTTP search request to the Pursuit API endpoint, parses JSON response, and limits 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 processes raw Pursuit search results, extracting and structuring fields like package, docs, type, module, title, url, etc., into a formatted output.
  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 input/output structures, Pursuit API results (PursuitResult), formatted results (FormattedResult), and overall output (FormatOutput). Used for type validation throughout the tool implementation.
  """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
• src/pursuit_mcp/server.py:26-27 (registration)

  Entry point to run the MCP server, which activates all registered tools including search_pursuit.
  if __name__ == "__main__": mcp.run()