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