Megaraptor MCP

Instructions

Implementation Reference

• src/megaraptor_mcp/tools/artifacts.py:22-108 (handler)

  The `list_artifacts` tool implementation, decorated with `@mcp.tool()`, which validates inputs and queries the Velociraptor server for artifacts.

  @mcp.tool()
  async def list_artifacts(
      search: Optional[str] = None,
      artifact_type: Optional[str] = None,
      limit: int = 100,
  ) -> list[TextContent]:
      """List available Velociraptor artifacts.
  
      Args:
          search: Optional search term to filter artifacts by name or description
          artifact_type: Optional type filter: 'CLIENT', 'SERVER', or 'NOTEBOOK'
          limit: Maximum number of artifacts to return (default 100)
  
      Returns:
          List of artifacts with their names, descriptions, and types.
      """
      try:
          # Validate inputs
          limit = validate_limit(limit)
  
          if artifact_type and artifact_type.upper() not in ('CLIENT', 'SERVER', 'NOTEBOOK'):
              return [TextContent(
                  type="text",
                  text=json.dumps({
                      "error": f"Invalid artifact_type '{artifact_type}'",
                      "hint": "Must be one of: CLIENT, SERVER, NOTEBOOK"
                  })
              )]
  
          client = get_client()
  
          # Build the VQL query
          conditions = []
          if search:
              conditions.append(f"name =~ '{search}' OR description =~ '{search}'")
          if artifact_type:
              conditions.append(f"type = '{artifact_type}'")
  
          where_clause = f" WHERE {' AND '.join(conditions)}" if conditions else ""
          vql = f"SELECT name, description, type, parameters FROM artifact_definitions(){where_clause} LIMIT {limit}"
  
          results = client.query(vql)
  
          # Format the results
          formatted = []
          for row in results:
              artifact = {
                  "name": row.get("name", ""),
                  "description": (row.get("description", "") or "")[:200],  # Truncate long descriptions
                  "type": row.get("type", ""),
                  "has_parameters": bool(row.get("parameters")),
              }
              formatted.append(artifact)
  
          return [TextContent(
              type="text",
              text=json.dumps(formatted, indent=2)
          )]
  
      except ValueError as e:
          # Validation errors
          return [TextContent(
              type="text",
              text=json.dumps({
                  "error": str(e),
                  "hint": "Check your limit parameter value"
              })
          )]
  
      except grpc.RpcError as e:
          # gRPC errors
          error_info = map_grpc_error(e, "listing artifacts")
          return [TextContent(
              type="text",
              text=json.dumps(error_info, indent=2)
          )]
  
      except Exception:
          # Generic errors - don't expose internals
          return [TextContent(
              type="text",
              text=json.dumps({
                  "error": "Failed to list artifacts",
                  "hint": "Check Velociraptor server connection and try again"
              })
          )]