Megaraptor MCP

Instructions

Implementation Reference

• src/megaraptor_mcp/tools/vql.py:117-279 (handler)

  The implementation of the `vql_help` MCP tool. It defines the available topics and returns help documentation based on the requested topic.

  @mcp.tool()
  async def vql_help(
      topic: Optional[str] = None,
  ) -> list[TextContent]:
      """Get help on VQL (Velociraptor Query Language).
  
      Args:
          topic: Optional topic to get help on. Options:
                 - 'syntax': VQL syntax basics
                 - 'plugins': Common VQL plugins
                 - 'functions': Common VQL functions
                 - 'examples': Example queries
  
      Returns:
          Help text for the requested topic.
      """
      help_content = {
          "syntax": """
  # VQL Syntax Basics
  
  VQL follows a SQL-like syntax:
  
  ```
  SELECT column1, column2, ...
  FROM plugin(arg1=value1, arg2=value2, ...)
  WHERE condition
  ORDER BY column
  LIMIT n
  ```
  
  Key differences from SQL:
  - Uses plugins instead of tables
  - Plugins are function calls with named arguments
  - Supports LET for variable assignment
  - Supports foreach() for iteration
  """,
          "plugins": """
  # Common VQL Plugins
  
  ## Client Information
  - clients() - List/search clients
  - client_info() - Get info about a specific client
  
  ## Collections
  - collect_client() - Schedule artifact collection
  - flows() - List collection flows
  - source() - Get collection results
  
  ## Hunts
  - hunt() - Create a hunt
  - hunts() - List hunts
  - hunt_results() - Get hunt results
  
  ## System Info (Client)
  - info() - Basic system info
  - pslist() - Process list
  - netstat() - Network connections
  - users() - User accounts
  
  ## File System (Client)
  - glob() - File search with wildcards
  - read_file() - Read file contents
  - stat() - File metadata
  - hash() - Calculate file hashes
  
  ## Windows Specific
  - wmi() - WMI queries
  - registry() - Registry access
  - evtx() - Event log parsing
  """,
          "functions": """
  # Common VQL Functions
  
  ## String Functions
  - format() - Format strings
  - split() - Split string
  - regex_replace() - Regex replacement
  - base64encode/decode() - Base64 encoding
  
  ## Time Functions
  - now() - Current timestamp
  - timestamp() - Parse timestamp
  - humanize() - Human-readable time
  
  ## Data Functions
  - count() - Count rows
  - enumerate() - Add row numbers
  - filter() - Filter rows
  - dict() - Create dictionary
  - array() - Create array
  
  ## File Functions
  - read_file() - Read file
  - hash() - Calculate hash
  - upload() - Upload file to server
  """,
          "examples": """
  # VQL Example Queries
  
  ## List all Windows clients
  ```
  SELECT * FROM clients() WHERE os_info.system = 'windows'
  ```
  
  ## Find processes by name
  ```
  SELECT * FROM pslist() WHERE Name =~ 'chrome'
  ```
  
  ## Search for files
  ```
  SELECT * FROM glob(globs='C:/Users/*/Downloads/*.exe')
  ```
  
  ## Get recent event logs
  ```
  SELECT * FROM Artifact.Windows.EventLogs.Evtx(
      EvtxGlob='%SystemRoot%/System32/Winevt/Logs/Security.evtx',
      StartDate=now() - 86400
  )
  ```
  
  ## Collect artifact and wait for results
  ```
  LET flow <= SELECT collect_client(
      client_id='C.xxx',
      artifacts='Windows.System.Pslist'
  ) FROM scope()
  
  SELECT * FROM source(
      client_id='C.xxx',
      flow_id=flow[0].collect_client.flow_id
  )
  ```
  """,
      }
  
      if topic and topic in help_content:
          return [TextContent(
              type="text",
              text=help_content[topic]
          )]
      else:
          # Return overview of all topics
          overview = """
  # VQL Help
  
  VQL (Velociraptor Query Language) is the core query language for Velociraptor.
  
  Available help topics:
  - syntax: VQL syntax basics
  - plugins: Common VQL plugins
  - functions: Common VQL functions
  - examples: Example queries
  
  Use vql_help(topic='<topic>') to get detailed help on a specific topic.
  
  For complete VQL reference, see: https://docs.velociraptor.app/vql_reference/
  """
          return [TextContent(
              type="text",
              text=overview
          )]